AI-Powered Self-Hosted Blog

Designing Tool Definitions for AI Agents: Patterns for Naming, Descriptions, Argument Schemas, and Error Responses to Reduce Wrong Tool Selection and Argument Errors

Published

In one six-month deployment of a multi-agent support platform, 34% of failed turns were attributed to wrong tool selection or argument mismatch rather than hallucination. After revising definitions across a catalog of more than 200 tools, the team reported roughly 60% fewer wrong selections and 45% fewer argument errors in A/B tests.
Those figures are useful as a reason to inspect tool definitions, not as a universal benchmark. The available account does not specify the exact denominator, baseline, or test conditions. The practical lesson is narrower: when a model has trouble choosing a tool or filling its arguments, improving the model or adding another prompt may miss the source of the error. The tool interface itself may be unclear.
A model encounters tool definitions as part of its decision process. Names, descriptions, schemas, and errors shape what it selects and what it sends. Treating those definitions as an interface contract—with the model as a caller that may skim, confuse similar options, or guess—can make agent behavior more reliable.

Two Surfaces, Three Failure Modes

Tool use has two linked stages. On the selection surface, the model decides which tool to call, based on names, descriptions, and the other tools available. On the execution surface, it fills in arguments according to the selected tool’s schema.
That sequence helps localize failures:

Failure mode Surface Typical symptom
Wrong tool selected Selection A related but unsuitable operation runs
Argument mismatch Execution A required value is missing or has the wrong shape
Ambiguous definition Either The model has no clear basis for choosing or filling fields
The distinction matters because a model must select a tool before its arguments can be correct. A long system prompt cannot reliably compensate for a catalog in which two tools sound interchangeable. Start by checking where failure occurs: did the model choose the wrong operation, choose the right one but provide invalid arguments, or encounter a definition that leaves the intended behavior unclear?

Design for the Model’s First Impression

A tool catalog is a choice set. The model sees a name and description in the context of peer tools, then must distinguish among them. A detailed description may help a human developer, but burying the key distinction in several paragraphs makes it harder for the model to select correctly.
Put the most useful information first: what the tool does, when to use it, and how it differs from its closest alternative. Keep further implementation detail in field descriptions or external documentation where appropriate. The selection surface should let the model tell the tools apart at a glance.

Names: Make the Operation Distinct

A name should make both the action and its target clear. Generic names such as process, manage_record, or search leave too much to inference, especially when the catalog contains multiple related operations.
For example, a support catalog might include:

Descriptions: Explain When to Use the Tool

A useful description does more than restate the name. It gives a selection rule, particularly when neighboring tools overlap.
For instance:

Use search_customers to find customers by name, email, or account ID. Use get_customer when you already have the customer ID and need that customer’s full record.
This makes the boundary explicit. A vague description such as “Search customer information” does not tell the model whether to use the tool when it already has an ID or when it needs a brief result versus a full record.
Prefer concise descriptions that clarify three things:

Schemas: Make Valid Arguments Easy to Express

Once a tool is selected, its schema guides argument generation. An overly permissive schema invites guesses; an underspecified field leaves the model uncertain about format or meaning.
For example, a field called date is ambiguous if the tool expects an ISO 8601 timestamp in UTC. A clearer schema uses a name such as start_time and a description such as “ISO 8601 timestamp in UTC, for example 2026-10-20T09:00:00Z.” An enum is safer than a free-form string when only a fixed set of values is valid, such as low, normal, and high.
Make required fields genuinely required, constrain values where possible, and avoid optional fields whose defaults could change the outcome in surprising ways. If two values are mutually exclusive, express that constraint in the schema when the tool framework permits it. Otherwise, document it clearly and validate it at runtime. Good schemas reduce the number of invalid calls the model can generate; server-side validation remains necessary.

Errors: Make the Next Attempt Better

An error response is part of the model’s input for its next decision. A bare message such as “Invalid request” gives it little help. A useful response identifies the problem and, when safe, explains how to correct it.
For example:

{
  "error": "invalid_argument",
  "field": "priority",
  "message": "Expected one of: low, normal, high.",
  "retryable": true
}

This response names the field, states the accepted values, and signals that a corrected attempt may work. For errors that should not be retried, such as a permission denial, say so clearly. Avoid returning internal stack traces, secrets, or vague instructions that could encourage repeated calls without new information.
Error wording should match the schema and descriptions. If the schema says a field is an enum but the error message lists a different set of values, the interface contradicts itself and makes recovery harder.

Measure the Changes in Your Own Catalog

The reported reductions of 60% in wrong selections and 45% in argument errors came from one environment; without the test setup and denominators, they should not be treated as expected outcomes for every system. To measure your own changes, first define the categories. For example, count a wrong selection when a valid but unsuitable tool is called, and an argument error when the chosen tool rejects its arguments. Record those rates over a representative baseline, revise a group of definitions, and compare the same metrics afterward.
A small, focused evaluation can expose collisions before deployment. Present the model with realistic requests and the actual peer tools, then record the selected tool, generated arguments, and validation result. Include near-boundary cases, such as a request to find a customer versus retrieve a known customer’s full record. Repeat the evaluation after revisions so gains and regressions are visible.

Dynamic Catalogs Need Continued Attention

A static catalog can be reviewed as a whole, but some systems add or remove tools based on permissions, context, or runtime state. In those systems, the model’s selection surface changes from one turn to the next. A tool that is unambiguous in isolation may become confusing when a similar option appears, or unavailable when the model needs it.
Reassess tool boundaries as the catalog changes. Keep descriptions accurate about availability and prerequisites, and return a clear error if a previously available operation cannot be used. A two-surface model still helps diagnose these failures, but dynamic availability adds another factor: the model can only choose well among the tools it is shown.

A Practical Review

Before publishing a tool catalog, scan for names that collide, descriptions that fail to distinguish neighboring tools, fields whose formats or defaults are unclear, and errors that do not help the model recover. Then evaluate representative requests against the full set of tools the model will see.
Tool definitions cannot eliminate every reasoning error. They can make the intended choices clearer, make valid arguments easier to produce, and make failures more useful on the next turn. That is a concrete reliability improvement—and one that begins with the interface the model reads.