Tool Schema Design for AI Agents: Names, Descriptions and Errors
Tool names, parameter descriptions and error messages decide which tool an AI agent calls. Practical rules, a checklist and tests to cut wrong choices.

Good tool schema design for an AI agent means writing each tool name, description and parameter so the model can tell, from the definition alone, which tool fits a request and what values to pass. The schema is the only description of your systems that the model reads, so its wording decides most of the tool choices it makes. When a name is vague or a parameter has no explanation, the agent guesses, and those guesses are where duplicate records, wrong lookups and rejected writes begin.
Key takeaways
- Name each tool with one verb and one object, and make sure no two tools can plausibly answer the same request.
- Write each description as a decision rule: when to use the tool, when not to, and what it returns.
- Give every parameter a type, a format, its allowed values and a stated source, so the model does not invent them.
- Write error messages that name the failed field, show a valid value and say whether a retry is safe.
- Test the schema with a fixed set of realistic requests before and after every change, and read each failure.
Why agents pick the wrong tool before any code runs
An agent does not see your software. It sees a list of tool names, descriptions and parameter definitions, and it chooses among them by reading that text. Most wrong choices are predictable from the schema itself. Two tools have names that overlap, a description explains what a system does but never when to use it, or a parameter is called id with no note about which identifier is meant.
Anthropic's engineering notes on writing tools for agents make a similar argument: tools should be designed around the tasks an agent has to complete, and their descriptions deserve the same care as the code behind them. A tool that wraps every endpoint of a vendor API gives the model many near-identical choices. A tool built for one task gives it one obvious choice.
Treat the schema as part of the product. Each change to a name or description changes behavior, even when the code underneath is identical.
Name tools so that no two answer the same question
A good tool name carries three facts: the action, the object and, where it matters, the direction of data flow. Names like process, handle, run or update_record force the model to read the description before it can rule a tool in or out, and many models will not read carefully under pressure.
Use these rules when you name tools:
- Start with a verb that matches the real action, such as search, get, draft, create, cancel or approve.
- Name the object the tool acts on, such as invoice, customer or appointment.
- Keep read and write tools visibly separate, so a write never looks like a lookup.
- Make the difference between two similar tools explicit in the names. A get tool takes one known identifier, while a search tool takes free text and returns a list.
- Avoid names that describe a vendor's internals, since the model needs the business task, not the endpoint.
If a name needs a long description to be understood, it is probably too vague. For a deeper look at naming conventions, see Tool Schemas for Superintelligent Agents: Naming and Types That Work.
Write descriptions as decision rules
The description is where the model learns the boundary of each tool. A description that only says what the tool does leaves the model to guess when to use it. A useful description answers four questions: what the tool does, when to use it, when not to use it, and what changes as a result of the call.
A practical template for each description:
- One sentence stating the action and the object.
- The concrete situations where this tool is the right choice.
- The neighboring tool to use instead, named exactly, for the situations where this one does not fit.
- What the result contains, and whether the result can be partial or paginated.
- Whether the call changes any record, stated in plain words such as creates a pending draft, never sends, or cancels immediately.
Illustrative scenario: a company gives an agent two tools, one that drafts a refund request and one that issues a refund. The draft description says it creates a pending request for a person to approve and that it never moves money. The issue description says it requires an approval reference and must not be used to answer questions about whether a refund exists. When a customer asks whether a refund was paid, the agent calls the lookup tool, not either write tool, because both descriptions say so.
The description is a rule the model can check against the request in front of it.
Make every parameter explain itself
Parameters cause the quietest failures. The model fills them with plausible values, and a plausible value is often the wrong one: a customer name where a customer identifier was required, a day and month in the wrong order, or a currency code that the system does not accept. Each parameter needs enough definition that the model can fill it from the right source or leave it empty on purpose.
Check each parameter against this list:
- State the type and format, including how dates and times are written and which time zone applies.
- List the allowed values when the set is closed, rather than leaving them implied.
- Say where the value comes from, such as a previous lookup result, a user message, or a field the agent must never guess.
- Name identifiers precisely, for example the customer identifier returned by the customer search tool, not just customer.
- Mark optional parameters and state what the system does when they are omitted.
- Keep parameter names literal. A field called amount_in_cents tells the model more than a field called amount.
The same discipline applies to outputs. If a tool returns a field, describe it, because the model will reason over that field in the next step. For more on typed fields, see Tool Schemas for AI Agents: Typed Fields and Clear Errors.
Write error messages the agent can act on
An error message is part of the interface. A message such as invalid input tells the model that something failed and nothing else, so it often retries the same call with small variations. A useful error tells the model what to change, whether to ask the user for something, and whether the failed attempt left any trace in the system.
Every error should answer five questions:
- Which field failed, and which rule it broke.
- What a valid value looks like, with one example or the full list of allowed values.
- Whether the request changed anything, so the agent knows if a retry could duplicate a record.
- Whether the next step is a lookup, a question to the user, or a stop.
- Whether the response shape is the same as for success, so the agent can parse it without special cases.
Illustrative scenario: a scheduling tool expects a date written as year, month, day. An agent sends a day and month separated by a slash, and the error reads that the date is ambiguous, that the expected format is a four-digit year followed by a two-digit month and day, and that no appointment was created. The next call uses the correct format, and no person sees the error.
Errors also deserve scrutiny for security. Tool results and error text are input to the model, so an error should never echo raw user text back in a form that could steer the next action. The OWASP guidance on prompt injection prevention covers this class of risk, and it applies to any text an agent reads from a tool.
Test the schema before and after every change
Schema edits are behavior changes, and they are easy to make without noticing their effect. A short, fixed test set catches most regressions before they reach a live workflow. OpenAI's guide to evals describes the general practice of defining expected behavior and grading outputs against it, and the same approach works for tool choice.
A sound process looks like this:
- Collect realistic requests from recent operations, with personal and financial details removed.
- Include common requests, ambiguous requests, and requests that must not run, such as a write that needs approval.
- For each request, record the expected tool, the expected arguments and any expected refusal or handoff.
- Run the full set after every schema edit, and compare the results with the previous version.
- For each wrong choice, fix the name, description or error that caused it. Changing the prompt alone usually hides the problem rather than solving it.
- Track failures by tool, so a rising error rate points to one definition that needs attention.
Keep the test set in version control next to the schema, so a change to either one is reviewed with the other.
How a managed approach keeps tool schemas accurate
Be Human treats the tool schema as part of each agent's operating context. In a first engagement, the team defines one useful role, lists the tools that role needs, and writes names, descriptions, parameter rules and error formats for each tool. Each tool is marked as read only, draft, or write with approval, so the boundary is visible in the schema itself. In managed operations, the same team reviews the schema when a connected system changes, reruns the test set after each edit, and reviews logs that show which tool each request reached. The work is ongoing because vendor changes and new requests alter how a schema performs over time, and a schema that was accurate in its first week is not guaranteed to remain accurate.
If you are not yet sure which task should go to an agent first, the free Be Human AI diagnostic can help you find the first task worth handing over.
Frequently asked questions
How many tools should one agent receive? Give an agent only the tools its single role needs, and add more only after the current ones perform well on the test set. A large list of overlapping tools gives the model more ways to choose wrongly, and each addition needs its own description, permissions and error handling.
Should tool descriptions be long? Descriptions should be complete but direct. Cover the action, the situations for use, the situations to avoid, the neighboring tool to use instead, and whether the call changes anything. If a sentence does not help the model decide, remove it.
Can a better schema replace a more capable model? A clear schema often reduces mistakes more than a model change does, because it removes the guessing. It cannot fix a task that is unsuitable for automation, and it does not replace permission limits or approval steps for writes that matter.
What should happen when the agent still picks the wrong tool? Read the logged request and the chosen tool, then find the name, description or parameter that made the wrong choice look reasonable. Fix that definition, add the request to the test set, and rerun the full set before release.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


