What you need to know
When Claude decides which tool to call, the description is the main thing it has to go on. The name helps, the schema helps, but the description carries the meaning. A one-line description ("Retrieves customer information") is the commonest reason an agent picks the wrong tool among similar ones.
What a good description contains
| Element | Example for lookup_order |
|---|---|
| What it does | Returns one order's items, status, dates and payment |
| Inputs and their format | order_id: the order number, 5 to 7 digits, with or without a leading # |
| What it returns | Order status, item list, delivery date, refund eligibility |
| When to use it | When the customer gives an order number or asks about a specific delivery |
| When not to use it | To find a customer by name or email: use get_customer |
| Edge cases | Returns found: false for an unknown number; that is not an error |
{"name": "lookup_order",
"description": "Look up one order by its order number (5-7 digits, '#' optional). Returns status, items, delivery date and refund eligibility. Use when the customer names an order or a specific delivery. Do not use to find a customer: use get_customer with an email, phone or account number. An unknown number returns found=false, which is a valid result.",
"input_schema": {"type": "object",
"properties": {"order_id": {"type": "string", "pattern": "^#?[0-9]{5,7}$"}},
"required": ["order_id"]}}Overlap causes misrouting
Two tools with near-identical descriptions, such as analyze_content and analyze_document, force Claude to guess. The fixes are to rename and re-describe so each tool's purpose is distinct (for example, analyze_content becomes extract_web_results, described as working only on fetched web pages), or to split a generic tool.
Split generic tools into purpose-specific ones
A single analyze_document tool with a mode parameter for extraction, summarisation and claim verification asks Claude to pick the tool and the mode, and it often gets the mode wrong. Three tools with their own input and output contracts are easier to choose between:
extract_data_points(document_id, fields)returns structured valuessummarize_content(document_id, length)returns a summaryverify_claim_against_source(claim, document_id)returns supported, contradicted or not found, with the passage
Constrained inputs help too. A free-text language parameter collects "python", "Python3" and "py"; an enum of allowed values does not.
The system prompt can override good descriptions
Tool selection is also shaped by the system prompt. An instruction like "always search before answering" can create an unintended association with any tool whose name contains "search", even when another tool fits better. When tools are misrouted despite good descriptions, review the system prompt for keyword-sensitive instructions.
In the exam
Expect logs showing two tools confused, a generic tool used in the wrong mode, or a capable tool ignored. Choose answers that rewrite descriptions with inputs, outputs and boundaries, rename to remove overlap, split generic tools, or constrain inputs with enums.
Check your understanding
An agent often confuses get_customer and lookup_order, whose descriptions are one line each. What is the most effective first fix?
Show answer
Answer: D. Descriptions are the primary signal for tool selection. Stating what each accepts, returns, and when to use it rather than the other removes the ambiguity at its source.
A generic analyze_document tool with a mode parameter is often called in the wrong mode. Which change helps most?
Show answer
Answer: A. Separate tools with defined contracts make the choice explicit. A mode flag hides three decisions inside one call.
Tools are misrouted even though every description is clear. What should you check next? Select TWO.
Show answer
Answer: A, C. System prompt wording can create unintended tool associations, and overlapping purposes leave Claude guessing even with long descriptions. Temperature and list order are not the levers the exam points to.
Apply it: Rewrite Lakeshore's graph tool
Lakeshore's agent prefers Grep over the in-house portside-graph server, whose main tool is described as "Queries the code graph." Fix the tool interface.
- Write the new description for a
find_callerstool onportside-graph: purpose, inputs, outputs, when to use it and when to use Grep instead. - Decide whether to split a single
query_graph(kind, symbol)tool that handles callers, implementations and dependencies. Justify your answer. - Constrain one input with an enum or pattern, and say what goes wrong without it.
- Check the system prompt for an instruction that might push the agent towards Grep, and rewrite it.
Show model answer
1. Description. "Find every caller of a Java or TypeScript symbol in Portside, including calls through interfaces, re-exports and dependency injection that text search misses. Input: symbol, a fully qualified name such as com.lakeshore.billing.InvoiceService.issue. Returns a list of call sites with file, line and the calling method. Use for 'who calls X' and impact questions. For finding a literal string, error message or log text, use Grep instead."
2. Split. Yes: find_callers, find_implementations and module_dependencies, each with its own input and output. The questions are different and so are the results; one tool with a kind flag invites the wrong kind.
3. Constraint. symbol must match a qualified-name pattern (dot-separated segments). Without it the agent passes bare names like issue, which match dozens of methods and return noise.
4. System prompt. "Always search the code with Grep before answering" becomes "Use portside-graph tools for structural questions (callers, implementations, dependencies) and Grep for literal text."