Claude Tool Design: Descriptions, Tool Distribution and tool_choice
Claude decides which tool to call mostly from the tool’s name and description. Weak descriptions are the number-one cause of misrouting, and too many tools make selection worse. This lesson covers Task Statements 2.1 and 2.3.
📘 Write descriptions that differentiate
A good tool description states what the tool does, the accepted input formats, example queries, edge cases, what it returns, and when to use it rather than a similar tool.
{
"name": "lookup_order",
"description": "Fetch ONE order by order number (format: # followed by 5 digits, e.g. #12345) for a customer already verified with get_customer. Use for order status, items, totals and delivery dates. Do NOT use for customer profile, address or loyalty questions — use get_customer. Returns {order_id, status, items[], total, delivered_at}.",
"input_schema": {"type": "object",
"properties": {"customer_id": {"type": "string"}, "order_id": {"type": "string"}},
"required": ["customer_id", "order_id"]}
}- Overlapping tools? Rename and rescope (
analyze_content→extract_web_results), or split a generic tool into purpose-specific ones (extract_data_points,summarize_content,verify_claim_against_source). - Check the system prompt for keyword-triggered rules (“whenever the user says account, call get_customer”) that override good descriptions.
🛠️ How many tools per agent?
Giving an agent 18 tools instead of 4–5 increases decision complexity and lowers selection reliability. Agents also misuse tools outside their speciality (a synthesis agent running web searches). Scope tools to the role, and add a narrow cross-role tool (e.g. verify_fact) only for frequent needs, routing complex cases back through the coordinator. Replace generic tools with constrained ones — fetch_url → load_document, which validates the URL.
🛠️ tool_choice options
| Value | Behaviour | Typical use |
|---|---|---|
"auto" | Model may answer in text or call a tool (default) | General agents |
"any" | Model must call some tool | Guarantee structured output when several extraction schemas exist |
{"type":"tool","name":"X"} | Model must call X | Force extract_metadata first, then continue in follow-up turns |
"none" | No tool calls | Pure text responses |
any/named tool_choice with an error; there you use auto plus strict: true tools or structured outputs. For the exam, answer as the official exam guide teaches.🧪 Exam-Style Practice Questions
Try these before opening the answers. They use the same scenario style as the real exam.
Question 1. Two tools have the descriptions "Gets data" and "Gets info". What's the best first fix for misrouting?
- A. Merge them
- B. Add 8 few-shot examples
- C. Add a routing classifier
- D. Rewrite the descriptions with purpose, input formats, example queries, edge cases, and when to use each versus the other
Show answer
Answer: D. Descriptions are the main signal for tool selection, so this is the cheap fix at the root cause. C is over-engineering. A is valid sometimes, but it's more effort than a "first step". B adds tokens without fixing the cause.
Question 2. An agent has 18 tools and selects poorly. What's the best design move?
- A. Use `tool_choice: "any"`
- B. Add more tools for coverage
- C. Increase the temperature
- D. Give each specialised agent the 4–5 tools its role needs
Show answer
Answer: D. Fewer, role-scoped tools improve selection reliability. B makes it worse. A forces *a* call, not the right one. C adds randomness.
Question 3. `analyze_content` and `analyze_document` keep being confused. Content-analysis is only ever used for web search results. What's the best change?
- A. Set `tool_choice` to `auto`
- B. Add "IMPORTANT" to one description
- C. Delete both
- D. Rename it to `extract_web_results` with a web-specific description
Show answer
Answer: D. Renaming and rescoping removes the overlap. C loses capability. B is cosmetic. A is already the default and doesn't help.
📝 Assignment
Do these tasks in order. Each one has a Done when check, so you know when it is complete. The stretch task is optional but close to what the exam expects from an architect. Keep your answers in one notes file or Git repository, and revisit them in your final week of revision together with the cheat sheet in the last lesson of this course.
- Task 1: Rewrite two one-line tool descriptions from your own project using the purpose, inputs, examples and boundaries pattern.
✅ Done when: Each rewritten description names its inputs with an example, says when to use it instead of a similar tool, and states what it returns. - Task 2: Split a generic analyze_document tool into three purpose-specific tools with clear input and output contracts.
✅ Done when: Your three tools have distinct names, non-overlapping purposes and defined input and output fields. - Stretch: test tool_choice auto versus any on the model you use and note how it behaves.
✅ Done when: Your notes record what happened with each tool_choice setting, including any error the model returned.
❓ Frequently Asked Questions
🤔 How does Claude choose which tool to call?
Mainly from each tool's name and description, so descriptions must explain purpose, inputs and when to use the tool over similar ones.
🤔 How many tools should an agent have?
Ideally four or five relevant to its role. Large tool sets make selection less reliable.
🤔 What does tool_choice any do?
It forces Claude to call some tool rather than reply with text, while letting it pick which one.
🤔 Do new Claude models support forced tool_choice?
The newest models reject forced any and named tool_choice. Use auto with strict tools or structured outputs there, but answer exam questions as the exam guide teaches.
🏁 Summary
- The description is the selection signal — make it differentiate.
- Give each agent 4–5 role-relevant tools.
- auto = may call; any = must call some tool; forced = must call that tool.
Next, continue with MCP Tool Error Handling: isError, Error Categories and Retries.
Independent study material by SQA Tools. Not affiliated with, endorsed by or sponsored by Anthropic. Claude is a trademark of Anthropic. Mock questions are original practice items, not real exam content. Exam facts checked against Anthropic's official exam guides and certification FAQ on 11 November 2026.