Why it matters
The model selects tools from text alone: names, descriptions and parameter schemas. Two tools that both sound like search, or a parameter called data that accepts three shapes, produce calls that are technically valid and semantically wrong. Ergonomics makes the intended use obvious and the wrong use hard, which reduces both errors and the tokens spent deciding.
Mental model
A tool description is a sign above a door, not the floor plan of the building. The metaphor breaks because a sign is read by someone who can look inside, while the model commits to the door before it can see what is behind it, so the sign must carry the consequence too.
How it works
- 1Name tools after the outcome, such as createinvoice, rather than the mechanism, such as postv2endpoint.
- 2State in the description when to use the tool, when not to, and what it returns.
- 3Use flat, typed parameters with enums and formats; avoid free-form objects that hide required fields.
- 4Merge tools that differ only by a flag the model will guess wrong.
- 5Return errors that name the invalid field and the accepted values.
- 6Test selection with near-miss tasks that should route to a different tool.
Step 1 of 6
Name tools after the outcome, such as createinvoice, rather than the mechanism, such as postv2endpoint.
Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.
What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.
Text version
The page's steps: 1. Name tools after the outcome, such as createinvoice, rather than the mechanism, such as p… 2. State in the description when to use the tool, when not to, and what it returns. 3. Use flat, typed parameters with enums and formats; avoid free-form objects that hide requ… 4. Merge tools that differ only by a flag the model will guess wrong. 5. Return errors that name the invalid field and the accepted values. 6. Test selection with near-miss tasks that should route to a different tool.
- Name tools after the outcome, such as create_invoice, rather than the mechanism, such as post_v2_endpoint.
- State in the description when to use the tool, when not to, and what it returns.
- Use flat, typed parameters with enums and formats; avoid free-form objects that hide required fields.
- Merge tools that differ only by a flag the model will guess wrong.
- Return errors that name the invalid field and the accepted values.
- Test selection with near-miss tasks that should route to a different tool.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| One generic tool | Small toolset | Parameter guessing and silent misuse | Operations differ in permission or side effect |
| Many specific tools | Unambiguous selection | Prompt size and overlap | Tools are near-duplicates |
| Free-form input | Flexible for edge cases | Invalid arguments and injection surface | The downstream system needs structure |
| Strict schema | Valid calls, easy validation | Cannot express unusual requests | The domain is genuinely open-ended |
Good for
Small toolset
Cost
Parameter guessing and silent misuse
Fails when
Operations differ in permission or side effect
- Operations differ in permission or side effect
- Tools are near-duplicates
- The downstream system needs structure
- The domain is genuinely open-ended
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: One generic tool is good for Small toolset, costs Parameter guessing and silent misuse, and fails when Operations differ in permission or side effect. Many specific tools is good for Unambiguous selection, costs Prompt size and overlap, and fails when Tools are near-duplicates. Free-form input is good for Flexible for edge cases, costs Invalid arguments and injection surface, and fails when The downstream system needs structure. Strict schema is good for Valid calls, easy validation, costs Cannot express unusual requests, and fails when The domain is genuinely open-ended
Failure modes
- Tool collision. Two tools with similar descriptions split the same requests unpredictably. Debug: build a confusion matrix of intended versus selected tool from traces.
- Description drift. The tool changed but the description did not, so calls arrive with stale expectations. Debug: diff tool schemas and descriptions against the implementation in CI.
- Opaque error. A validation error returns a stack trace and the model retries unchanged. Debug: sample error observations and check each names the field and the fix.
In production
Track selection accuracy per tool, invalid-argument rate and retries after error. Review the toolset whenever a new tool overlaps an existing one.
Common misconceptions
People think: More tools give the agent more capability.
Actually: Past a point each tool dilutes selection and adds prompt cost; capability comes from the right few.
People think: The model will figure out a confusing tool.
Actually: It selects on text, so ambiguity in the description becomes ambiguity in behaviour.
Interview angle
Strong answers treat the description as the routing signal, discuss granularity and overlap, and include error text as part of the interface. Weak answers focus on the backend implementation and assume the model will infer intent.
Sources
- Anthropic, Tool use with Claude — how names, descriptions and input schemas drive tool selection.
- JSON Schema, Understanding JSON Schema — constraints, enums and formats for argument validation.