When an agent calls the wrong tool, or calls the right tool with wrong arguments, the instinct is to blame the model. Usually the schema is at fault. The model read a description that did not distinguish this tool from three others, and filled a free-form string field that accepted anything.
A tool definition is documentation written for a reader with no ability to ask a clarifying question, no access to your codebase, and one attempt. That framing changes how you write it.
What changed in 2026
- Strict schema enforcement became available. Constrained decoding against the schema removed malformed-argument errors, which shifted the remaining failures to selection and semantics.
- Tool sprawl made descriptions matter more. With many tools attached, disambiguation became the dominant quality factor — see tool search and deferred loading.
- Description writing became a discipline. Teams began iterating on tool text the way they iterate on prompts, with evaluation.
- Model-facing design displaced API mirroring. Wrapping internal APIs in purpose-built tool interfaces became standard practice.
Descriptions do the selection
The name gets a glance. The description decides.
The most valuable sentence in a tool description is frequently the one saying when not to use it. A description covering only capability leaves the model to infer boundaries, and it infers generously.
Weak: "Searches documents."
Strong: "Searches internal policy documents. Use for questions about company procedures, benefits, or compliance. Do not use for customer data, product documentation, or anything requiring current external information."
The second tells the model where the boundary is, which is exactly the information that prevents a wrong selection. It costs thirty tokens and eliminates a class of error.
When two tools could plausibly serve the same request, say so in both descriptions. "For internal documents use this; for public web content use web_search." Cross-referencing removes ambiguity in a way that neither description alone can.
Constrain the parameters
Every free-form field is a place the model can produce something your service rejects.
| Instead of |
Use |
Why |
status: string |
status: enum[open, closed] |
Invalid values become impossible |
date: string |
date: string with format stated |
Removes format ambiguity |
limit: number |
limit: integer, min, max |
Prevents absurd values |
| Ten optional fields |
Three required, two optional |
Fewer chances to err |
filters: object |
Named specific parameters |
Structure the model can fill |
Enums are the highest-value change. A constrained set means the model cannot invent a value, and with strict schema enforcement it literally cannot emit an invalid one.
Where free text is genuinely necessary, state the format in the parameter description with an example. "date: ISO 8601 date, e.g. 2026-05-06" is unambiguous; "date: the date" is not.
Keep the parameter count low. Every optional field is a decision the model has to make, and models fill optional fields more often than intended. If your tool has twelve parameters, it is probably two tools.
Design for the model, not your API
The common shortcut is to expose an internal endpoint directly as a tool. It rarely works well, because your API was designed for a client that reads documentation and has a developer behind it.
Purpose-built tool interfaces do better. That usually means fewer parameters with sensible defaults applied server-side, combining several calls the model would otherwise have to chain, naming things for what they mean rather than for your internal schema, and returning results shaped for reading rather than for parsing.
Return values deserve as much thought as inputs. A tool returning a large JSON blob puts all of it into context permanently — see ReAct agents for why that accumulates. Return what the model needs, not everything the endpoint produces.
Common mistakes
- Description of capability only. No boundary, so wrong selections.
- Free-form strings where an enum fits. Invented values.
- Overlapping descriptions across tools. The model guesses.
- Too many parameters. More chances to err; probably several tools.
- Mirroring the internal API. Designed for a different reader.
- Verbose return values. Fills context with what nobody needed.
- Never evaluating tool selection. Wrong-tool errors are invisible without measurement.
FAQ
How long should a description be?
Long enough to state purpose, scope, and boundary — usually two or three sentences. Every tool description is in context on every request, so length has a real cost when there are many tools.
Should I include examples?
For parameters with non-obvious format, yes, inline in the parameter description. A full usage example in the tool description is usually unnecessary and expensive.
How do I know if my schemas are the problem?
Measure tool selection accuracy on a set of representative requests with known-correct tools. Wrong selections point at descriptions; wrong arguments point at parameter design — the same discipline as LLM regression testing.
Does strict mode remove the need for good schemas?
It guarantees valid shape, not correct choice. The model can still pick the wrong tool and fill valid-but-wrong values.
Where to go next
For errors when a call fails, read agent tool error handling. For managing a large tool set, tool search and deferred loading, and for the reliability side, tool calling reliability.