Tool Schema Design
Tool descriptions are the primary signal Claude uses to pick a tool. Learn to write schemas that route requests correctly instead of misfiring.
A tool schema is not just plumbing that validates JSON. It is the primary mechanism Claude uses to decide which tool to call. The model reads your names, descriptions, and parameter definitions in natural language and reasons about them exactly as it reasons about any other text. Treat the description as an afterthought and Claude will route requests to the wrong tool no matter how correct the underlying code is.
What a production-grade description contains
A weak description like "Retrieves customer information" gives Claude almost nothing to distinguish it from three neighbouring tools. Strong descriptions carry five things: the tool's purpose, its input specifications (types, formats, required vs. optional), example use cases that anchor understanding, edge cases and limitations the tool cannot handle, and explicit boundaries that separate it from similar tools in the same toolkit.
- Purpose — one unambiguous primary function, stated plainly.
- Input specs — accepted formats and constraints, so Claude supplies valid arguments.
- Examples — concrete scenarios that show when the tool applies.
- Limits — what it cannot do, to prevent hopeful misuse.
- Boundaries — an explicit "do NOT use for..." that fences off adjacent tools.
{
"name": "lookup_customer_by_email",
"description": "Look up a single customer record by their exact email address. Returns account status, plan tier, and signup date. Use ONLY when you have a full email address. Do NOT use for name or phone lookups (use search_customers) or for order history (use get_orders).",
"input_schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Full email address, e.g. 'jane@example.com'. Partial matches are not supported."
}
},
"required": ["email"]
}
}A thin, generic description gives Claude nothing to distinguish this tool from its neighbours, so it misroutes requests to whatever tool sounds vaguely relevant.
{
"name": "get_customer",
"description": "Retrieves customer information."
}A rich description states purpose, input format, and an explicit boundary that fences off adjacent tools — selection becomes almost self-evident.
{
"name": "lookup_customer_by_email",
"description": "Look up a customer by exact email. Do NOT use for name/phone lookups (use search_customers)."
}Descriptions are the primary signal for tool selection, not supplementary documentation. When two tools overlap or have thin descriptions, Claude misroutes requests. Expanding and differentiating descriptions is the highest-leverage fix available.
Fixing misrouting: cheapest lever first
When an agent picks the wrong tool, the exam expects you to reach for the low-effort, high-leverage fix before building infrastructure. Expand and differentiate the descriptions first. Only escalate to heavier tactics if the interface is genuinely still ambiguous.
| Fix | Effort | When to reach for it |
|---|---|---|
| Expand descriptions | Low | Always first — clarifies purpose and boundaries |
| Rename tools | Low | When names are generic or collide semantically |
| Split generic tools | Medium | One tool does too many unrelated jobs |
| Few-shot examples | Medium | Rarely — adds overhead without fixing the root cause |
| Routing classifier | High | Over-engineered as a first step; avoid |
Break a vague analyze_document into extract_data_points, summarize_content, and verify_claim_against_source. Purpose-specific names and descriptions make selection almost self-evident.
A common distractor offers a routing classifier or tool consolidation as the first fix for misrouting. Both are high-effort. If the descriptions are thin, the correct answer is to expand them before adding any infrastructure.
Finally, check the system prompt. Keyword-sensitive instructions there can override even a well-written schema, pulling Claude toward a tool the description never intended. A great schema and a conflicting prompt still produce misrouting.
How the exam will try to trick you
The distractors below look right under time pressure — learn the tell.
- The trap
Add 5-8 few-shot examples demonstrating correct tool-selection patterns.
Correct answerExpand and differentiate the descriptions with input formats, example queries, edge cases, and boundaries.
Why: Few-shot examples add token overhead without addressing the root cause — thin, overlapping descriptions.
- The trap
Add a routing classifier (or merge overlapping tools into one) as the first fix for misrouting.
Correct answerRewrite the descriptions first; treat classifiers and consolidation as high-effort last resorts.
Why: Both add infrastructure or effort the exam does not consider proportionate when a cheaper lever exists.
- The trap
Rewrite the tool descriptions and consider the misrouting fixed.
Correct answerAlso review the system prompt for keyword-sensitive instructions.
Why: System-prompt keywords can silently override even a well-written schema and pull Claude to the wrong tool.
Key takeaways
- Tool descriptions are the primary mechanism Claude uses to select a tool, not optional metadata.
- Strong descriptions state purpose, input specs, examples, limitations, and explicit boundaries.
- Fix misrouting by expanding descriptions first; classifiers and consolidation are last resorts.
- Split overloaded generic tools into purpose-specific ones with intent-revealing names.
- Typed input schemas with formats and constraints reduce invalid argument generation.
- Review the system prompt for keyword instructions that can override good schemas.
Frequently asked questions
How do you design a Claude tool schema?+
Give each tool a specific name, a rich description covering purpose, inputs, examples, limits, and boundaries, and a typed input_schema with formats and required fields. The description is what Claude reads to decide whether to call the tool, so it must clearly differentiate the tool from its neighbours.
Why does Claude call the wrong tool?+
Almost always because two tools have overlapping or thin descriptions. Claude reasons over the description text to route requests, so vague or generic descriptions cause misrouting. Expanding and differentiating the descriptions is the cheapest and most effective fix.