How it works
An agent never reads your tool's implementation. At call time it sees three things: a name, a natural-language description, and a parameter schema. On every turn the model matches the current goal against the descriptions of all tools in context and calls the one whose text looks like the best fit. Selection is soft pattern-matching over prose, not a deterministic lookup.
So the description carries most of the routing signal, and it does three jobs at once:
- Disambiguation — what this tool does that the neighboring tools do not.
- Preconditions — when to reach for it, and when to stay away.
- Argument guidance — what each parameter means and what a good value looks like.
A strong description names the tool's job in one line, states the boundary ("use for X, not Y"), and pins down any parameter the model tends to guess wrong. A weak one restates the tool name, overlaps with three siblings, or hides a side effect behind a friendly verb. The model has no way to recover the missing intent — it only has the words you gave it. Ambiguity in the text becomes non-determinism in the call.
Why it matters in an agent harness
Tool descriptions are part of your control surface, not documentation. They decide which capability the agent invokes, and that choice is upstream of every guarantee the harness tries to hold — permissions, reversibility, blast radius, and cost.
Concrete outcomes:
- Wrong-tool calls waste turns and iteration budget, and each retry is a fresh chance to do damage.
- Overlapping descriptions between a read tool and a write tool are dangerous: a model that confuses
preview_changewithapply_changecrosses your read/write boundary in a single token. - Descriptions that omit side effects defeat approval gates, because an operator can't gate what the agent never signalled it was doing.
- Observability suffers when a tool's name and description don't match its behavior — your traces then lie about intent.
The description is where you encode operating judgment cheaply, before a guardrail has to catch a mistake and before a rollback has to undo one. Get it right and the agent self-selects the safe path; get it wrong and you push correction downstream into more expensive machinery.
Tool Description vs parameter schema
They fail in different ways, and you fix them in different places.
| Tool description | Parameter schema | |
|---|---|---|
| Form | Prose | Types and constraints |
| Drives | Which tool gets called | Whether the call is well-formed |
| Failure mode | Wrong-tool call | Malformed / invalid arguments |
| Fix | Sharpen wording, cut overlap | Tighten types, add enums, mark required |
If the agent keeps calling the wrong tool, no amount of schema tightening helps — that's a description problem. If it calls the right tool with garbage arguments, prose won't save you — constrain the schema. Diagnose the symptom before you edit.
The Rifty take
We treat tool descriptions as harness code, and review them like code. We optimize for separability: each tool's description should let the model tell it apart from its neighbors in one read, and we would rather ship fewer sharply-bounded tools than many overlapping ones. The tradeoff we accept is verbosity — spending context tokens on explicit boundaries and side-effect warnings — because a clear boundary in the prose is cheaper than a wrong call downstream.
Common failure modes
- Overlap — two tools whose descriptions could both match the same request; the model coin-flips between them.
- Silent side effects — a friendly verb ("update", "sync") that hides a destructive or irreversible action.
- Name/behavior drift — the implementation changes, the description doesn't; selection and traces both go stale.
- Under-specified parameters — the model guesses formats, IDs, or units the description never pinned down.
- Tool sprawl — so many tools in context that descriptions blur and selection accuracy falls.
- Copy-paste boilerplate — every tool opens with the same sentence, giving the model no discriminating signal.
Frequently asked questions
How is a tool description different from a tool name?
The name is a short handle; the description is the reasoning surface. The model leans on the description to decide when a tool applies, what it excludes, and how to fill parameters. A precise name helps, but the description carries the disambiguation and precondition signal the name alone can't.
Why does my agent keep calling the wrong tool?
Usually overlapping or vague descriptions, not a weak model. If two tools could plausibly match the same request, the agent effectively guesses. Sharpen each description to state what it does that its neighbors don't, name the boundary explicitly, and remove redundant tools from the context.
How long should a tool description be?
Long enough to disambiguate and pin down error-prone parameters, and no longer. Include the tool's job, its boundary ("use for X, not Y"), and any side effect. Skip restating the name and generic filler. Verbosity that adds discriminating signal earns its tokens; boilerplate that blurs tools does not.
Do MCP tool descriptions work the same way?
Yes. Tools exposed over MCP still reach the model as name, description, and schema, so the same selection dynamics apply. Because MCP servers can be added independently, watch for cross-server overlap and for untrusted description text, since a description is model-visible and can carry an injection payload.
Can a tool description be an attack surface?
Yes. Descriptions are injected into the model's context, so a malicious or compromised tool source can smuggle instructions through its description text. Treat third-party tool descriptions as untrusted input, review them before loading, and isolate tools whose descriptions you don't control.