What you will be able to do
- Explain why the tool description, more than any other signal, decides which tool Claude calls
- Write a tool description that covers purpose, inputs, examples, edge cases and boundaries against similar tools
- Diagnose misrouting between overlapping tools and fix it by renaming and rescoping descriptions
- Split a generic tool into purpose-specific tools with clear input and output contracts
- Audit a system prompt for keyword-triggered instructions that pull calls away from a tool's described scope
Key concept
Description-driven tool selection — Claude picks a tool by matching the request against each tool's name and description, and the API puts nothing else about the tool in front of the model. When two descriptions say the same thing, Claude has nothing to tell the tools apart, and calls land on the wrong one.
1.The description is what Claude chooses from
A tool definition is the whole interface between your code and the model's decision to call it. Each user-defined tool in the tools parameter has a name, a description, an input_schema and, optionally, input_examples. With the default tool_choice of auto, Claude decides on every turn whether to call a tool. It calls one when the request maps to that tool's described capability and the answer isn't already in context.
| Field | What it carries |
|---|---|
name | The tool's identifier; must match ^[a-zA-Z0-9_-]{1,128}$ |
description | What the tool does, when it should be used, and how it behaves |
input_schema | A JSON Schema object defining the expected parameters |
input_examples | Optional example input objects, each valid against the schema |
Several things that look like they might help are never shown to the model at all. Your backend routing weights, the internal function a tool maps to, and an ID a user might type have no effect on which tool Claude calls. When two tools share a description, the only remaining difference is two near-synonymous names, and process_data against process_information says nothing about which job belongs where. The fix goes in the tool definitions, not in the user's phrasing or the order of the array.
A description that is too short fails in the same way, just less visibly. The documentation's poor example, "Gets the stock price for a ticker.", is too brief and leaves Claude with many open questions about the tool's behavior and usage. Which exchanges? What currency? Should it also answer a question about the company's earnings? Claude fills each of those gaps with a guess.
Because the description is the primary selection signal, a minimal one makes selection unreliable exactly when it matters most: among similar tools. A lone stock-price tool with a one-line description has no rival to be confused with. Add a second tool that also touches prices, and that one line is all Claude has to decide between them. Anthropic's own example of a pair where extra context is needed is create_ticket against create_incident. The same holds for tool search, which matches against names and descriptions, so a vague pair is harder to discover as well as harder to choose between. The remedy is more context in the description itself: what the tool does, when it applies, and what it leaves alone.
Checkpoint 1 of 8· Check yourself
Your agent has two user-defined tools, and Claude keeps calling the wrong one. You can make only one change. Which change can actually affect which tool Claude chooses?
Claude decides which tool to call from the user's request and each tool's description. The array order, backend weights and internal function names give it no extra signal for telling the tools apart. The fix has to go in the definitions Claude reads.
“Claude determines when to call a tool based on the user's request and the tool's description.”Source: platform.claude.com
Checkpoint 2 of 8· Exam question
A team names two tools process_data and process_information, and both share the description "Processes data provided by the user." The model routes roughly half of matching tasks to the wrong tool. What is the most likely root cause?
Correct answer: B — The near-duplicate descriptions give the model no differentiating signal, since descriptions are its main basis for choosing similar tools.
- A. Incorrect. The order of tools in the array does not influence the model's selection; the model bases its decision on the content of tool descriptions, not their position. Reordering will not resolve the ambiguous routing.
- B. Correct. Because the descriptions are nearly identical, the model cannot reliably distinguish between the two tools; descriptions are the primary signal used for tool selection when tools are otherwise similar.
- C. Incorrect. Modern context windows are large enough to accommodate many tool definitions; two short tool descriptions would not approach the limit, so context window size is not the cause of the ambiguous routing.
- D. Incorrect. The problem is that both tools have identical descriptions, so the model cannot differentiate regardless of user phrasing; the root cause is the tool definitions, not the user's prompt. Fixing the descriptions is the correct solution.
2.What a selection-ready description contains
Anthropic ranks detailed descriptions as by far the most important factor in tool performance, ahead of every other lever. A description should explain what the tool does, when it should be used and when it should not, what each parameter means, and any caveats, including what information the tool does not return. Aim for at least 3–4 sentences, and more for a complex tool.
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}| Element | In the example | Mistake it prevents |
|---|---|---|
| Input format and constraints | Valid symbol on NYSE or NASDAQ; e.g. AAPL for Apple Inc. | Passing a company name or an unsupported market |
| Output | Latest trade price in USD | Claude guessing the currency or what kind of price comes back |
| When to use it | Current or most recent price of a specific stock | Calling it for questions it was never built for |
| Boundary | Will not provide any other information about the stock or company | Expecting it to answer earnings or company questions |
Edge cases and examples belong in the description as well. Anthropic's agent-building guidance puts it this way: a good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools. It suggests writing the description the way you would write a docstring for a junior developer, which matters most when many tools look alike. The input format is often what decides whether a call works. A location parameter described as "The city and state, e.g. San Francisco, CA" shows Claude how to pass a multi-word place name. A bare string type does not.
For complex, nested or format-sensitive inputs, input_examples can add concrete calls that are validated against the schema, and an invalid example returns a 400 error. Examples supplement the description and do not replace it. They also help when two tools are similar, because an example can show which one fits a given request. A small wording change can still have a big effect. Anthropic found Claude needlessly appending the current year to web search queries, and fixed it by improving the tool description.
Differentiation between sibling tools comes from four statements made side by side: purpose, inputs, outputs, and when to pick this tool over its neighbour. Take two tools that both touch web pages. One description reads: "Extracts the title, price and availability from a product page. Takes a single URL and returns those three fields as JSON. Use it when the user supplies a link to a product page; for summarizing an article, use summarize_article instead." The other mirrors it: it takes pasted article text, returns a short summary, and says it should not be used for product pages. Neither description needs to be long, but each names its input, its output and the case it hands to the other tool. The decisive part is the last one, because the troubleshooting guidance for Claude calling tool A when you wanted tool B is to differentiate tools by WHEN to use them, not only WHAT they do. Documenting the return format in the description, such as the fields and their types, makes the contrast between siblings concrete.
Checkpoint 3 of 8· Fill the gap
The poor version of this tool declared ticker as just {"type": "string"}, with no other keys. In the complete definition below, which key in the parameter gives Claude the input format it needs?
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
" ? ": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}Each parameter gets its own description that says what the value means and shows the expected format with an example (AAPL, not "Apple"). That stops Claude from passing a company name. A bare string type tells it nothing about the format.
Checkpoint 4 of 8· Check yourself
A teammate wants to cut a nested-input tool's description down to one line and add three schema-valid input_examples instead, since "examples show Claude more than prose does." What is wrong with this plan?
Detailed descriptions are the most important lever for tool performance. input_examples are an optional supplement for complex or format-sensitive inputs. They show how to structure a call, but they don't replace the description's statement of when to use the tool and what it won't do.
“Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the input_examples field”Source: platform.claude.com
3.Overlapping tools: rename and rescope
Overlap is the most common source of misrouting. Anthropic names wrong tool selection as one of the two most common failures, especially when tools have similar names such as notification-send-user and notification-send-channel. The troubleshooting guidance for "Claude calls tool A when you wanted tool B" is to sharpen descriptions and to tell tools apart by when to use them, not only by what they do.
Overlap often creeps in when a tool gains a successor. Say analyze_content was built to summarize any pasted content, including emails and internal notes. Later a web-specific tool arrives, but nobody edits the old description, so it still claims every kind of content. Claude reads two descriptions that both cover web material, and some web tasks go to the general tool. Fixing this takes two edits to the old tool. Give it a name that matches the scope it has left. Then rewrite its description so it explicitly excludes the case the new tool now owns.
Copied descriptions are the other common way overlap starts, and there the older tool is narrowed the other way round. Suppose a different pipeline has analyze_content and analyze_document, written with near-verbatim descriptions, although in practice analyze_content is the tool that receives web search results and analyze_document receives uploaded files. Rename analyze_content to extract_web_results and give it a web-specific description: it takes web search results, returns the extracted fields, and is not for uploaded files. Let analyze_document describe uploaded documents. The overlap disappears at the source because each name and description now states a scope the other does not, so a request about an uploaded PDF no longer matches the web tool. Deleting one tool, or making users paste documents as plain text, removes a capability without fixing the description problem. Giving the tools different internal function names changes nothing Claude can see.
| Weak definition | Stronger definition |
|---|---|
query_db_orders: "Execute order query" | search_customer_orders: "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info." |
| Unprefixed names across services | Service-prefixed names such as github_list_prs, slack_send_message |
Names do some of this work. When tools span several services, prefixing each name with the service keeps selection unambiguous as the library grows. A prefix complements the description and cannot replace it. Two tools with clear names and identical descriptions still overlap.
Checkpoint 5 of 8· Check yourself
After a web-extraction tool was added, analyze_content kept its old description: "Summarizes any content: emails, notes, web pages." Both tools now have detailed descriptions of what they do, but some web tasks still go to analyze_content. Which fix targets the actual cause?
Both descriptions still claim web material, so Claude can't tell when to use one tool instead of the other. Renaming the older tool to its remaining scope and stating that web content is excluded makes the boundary visible. Array order, examples alone, or more detail about what each tool does leave the overlap in place.
“Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”Source: platform.claude.com
Checkpoint 6 of 8· Exam question
A tool named analyze_content, originally built for summarizing pasted text, has its description copied almost verbatim onto a newer tool, analyze_document, meant for uploaded PDFs. Following the pattern of renaming a tool to eliminate overlap, what should the team do?
Correct answer: B — Rename analyze_content to a more specific name, such as summarize_pasted_text, and limit its description to pasted text only, while analyze_document handles uploaded PDFs.
- A. This approach would remove the ability to leverage the Files API for structured document handling and goes against Anthropic's recommendation to differentiate tools by purpose, not eliminate necessary functionality.
- B. Per CCAR-F guidance, tools must have distinct, non-overlapping descriptions to prevent model confusion. The study guide explicitly warns: "Avoid identical or overlapping descriptions across tools." Renaming and scoping the tool to its specific input type eliminates overlap with the PDF-focused
analyze_document, following the recommended pattern of clarifying tool boundaries. - C. Anthropic's tool design best practices warn against identical or overlapping descriptions because the model may confuse them; internal function names are not used for selection, so this fails to prevent misrouting.
- D. This is a reactive measure that does not prevent misrouting at the point of tool selection. Proactively eliminating description overlap is the correct and recommended approach.
4.Splitting a generic tool into purpose-specific contracts
A generic tool overlaps with itself. A single analyze_document that extracts, summarizes or fact-checks, depending on how Claude reads the request, has one description trying to cover three jobs. Each of those jobs takes different inputs and returns different outputs. The fix is to split it into extract_data_points, summarize_content and verify_claim_against_source. Each one gets a defined input/output contract. The verifier takes a claim and a source, for example, while the summarizer takes only content. Each description can then say what the tool returns and when to choose it over its two siblings.
The two rules apply to different shapes of tool, so they do not conflict. Consolidation is for one resource with several actions. Rather than defining create_pr, review_pr and merge_pr separately, you group them into one tool with an action parameter, because fewer, more capable tools reduce selection ambiguity. Splitting is for one name that hides several distinct purposes. Ask whether the operations share a contract. Actions on the same pull request do, so they belong behind one tool with an action parameter. Extraction, summarization and claim verification produce different outputs that Claude uses differently, so each gets its own tool and description.
The contract should be written down, outputs included. Anthropic's example get_orders description lists what comes back: an id, a total in USD, a status of 'pending', 'shipped' or 'delivered', the items, and an ISO 8601 created_at. Spelling out the output makes the boundary between sibling tools concrete. The agent-building guidance gives one more test. Ask how you could change parameter names or descriptions to make the tool's use obvious, and change the arguments so mistakes are harder to make.
The answer depends on the contract, not on the number of verbs. Create and update on the same record can stay as one tool with an action parameter, as long as the description states which fields each action accepts and whether partial updates are allowed. Unknown fields are a sign that the description never stated those inputs. Splitting would not fix that by itself.
Checkpoint 7 of 8· Check yourself
You propose splitting a generic analyze_document into extract_data_points, summarize_content and verify_claim_against_source. A reviewer objects: "Anthropic says to consolidate related operations into fewer tools, so splitting makes selection worse." What is the best response?
The consolidation advice covers grouping actions on the same resource, such as PR operations, behind one tool with an action parameter. A tool that hides several purposes with different input/output contracts, for example a verifier that takes a claim and a source while a summarizer takes only content, should be split so each description can say what it returns and when to choose it.
“Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.”Source: platform.claude.com
5.System prompt wording can override a good description
Tool descriptions and your system prompt are not separate channels. When you call the API with tools, it builds one prompt that contains the tool definitions, the tool configuration and your own system prompt, and Claude reads them together.
In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}System prompt wording measurably steers tool use. "Use the tools to investigate before responding." increases tool calls, "Always call a tool first before responding." pushes further, and "Use your judgment about whether to call a tool or respond directly." keeps triggering conservative. Since one sentence in the system prompt can shift how often Claude calls tools, one sentence can just as easily shift which tool it calls.
Instructions keyed to particular words are where this goes wrong. Suppose a system prompt says "Whenever the user mentions a document, analyze it." That ties the word "document" to whichever tool has "analyze" or "document" in its name. A request to verify one claim in a PDF might then go to a general analysis tool, even though verify_claim_against_source describes that exact job. The careful description is still there. A trigger word elsewhere in the same prompt is drawing the call away from it. When routing stays wrong after the descriptions have been fixed, read the system prompt for phrases like this. Then either remove the keyword link or rewrite it to point at the tool whose description actually fits.
Emphatic wording creates unintended associations too. Claude's recent models respond more strongly to the system prompt than earlier ones, so a line written to stop a tool undertriggering, such as "CRITICAL: You MUST use this tool when...", can now make it fire on requests that belong to a neighbouring tool. Anthropic's fix is to dial back aggressive language: a plain "Use this tool when..." is enough. Blanket defaults like "If in doubt, use [tool]" cause overtriggering for the same reason, and the better instruction is targeted, naming the situation in which the tool helps. Audit a prompt for three patterns: a trigger word that matches a tool's name, an emphatic MUST aimed at one tool, and a default-to-this-tool rule. Each one competes with the descriptions.
Checkpoint 8 of 8· Fill the gap
Debugging a misroute that remains after the tool descriptions were rewritten, you look at the prompt the API builds around your tools. Which placeholder sits right after the tool definitions and explains why instructions outside the tool definitions can still affect which tool Claude calls?
In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
?
{{ TOOL CONFIGURATION }}The API puts your system prompt in the same prompt as the tool definitions, and Claude reads them together. So a keyword-triggered instruction such as "whenever the user mentions a document, analyze it" can pull calls away from a well-scoped description. Backend weights, internal function names and array order are never shown to the model.
Source: platform.claude.comSources
(9)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“It calls a tool when the request maps to that tool's described capability and the answer isn't already in context.”
↩︎ The description is what Claude chooses from“This boundary is steerable through your system prompt.”
↩︎ System prompt wording can override a good description“Claude determines when to call a tool based on the user's request and the tool's description.”
↩︎ Key concept“Claude determines when to call a tool based on the user's request and the tool's description.”
↩︎ Exam trap 1“Claude determines when to call a tool based on the user's request and the tool's description.”
↩︎ Prediction - 2.
“The poor description is too brief and leaves Claude with many open questions about the tool's behavior and usage.”
↩︎ The description is what Claude chooses from“The more context you can give Claude about your tools, the better it will be at determining when and how to use them.”
↩︎ The description is what Claude chooses from“Provide extremely detailed descriptions. This is by far the most important factor in tool performance.”
↩︎ What a selection-ready description contains“Aim for at least 3–4 sentences for each tool description, more if the tool is complex.”
↩︎ What a selection-ready description contains“This makes tool selection unambiguous as your library grows, and is especially important when using tool search.”
↩︎ Overlapping tools: rename and rescope“Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter.”
↩︎ Splitting a generic tool into purpose-specific contracts“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt.”
↩︎ System prompt wording can override a good description“Prioritize descriptions, but consider using input_examples for complex tools.”
↩︎ Exam trap 2“the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt.”
↩︎ Exam trap 4“Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the input_examples field”
↩︎ Checkpoint - 3.https://www.anthropic.com/engineering/advanced-tool-useSecondary source
“Tool search matches against names and descriptions, so clear, descriptive definitions improve discovery accuracy.”
↩︎ The description is what Claude chooses from“Similar tools where examples clarify which one to use (e.g., create_ticket vs create_incident)”
↩︎ What a selection-ready description contains“The most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names like notification-send-user vs. notification-send-channel.”
↩︎ Overlapping tools: rename and rescope - 4.https://www.anthropic.com/engineering/building-effective-agentsSecondary source
“A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools.”
↩︎ What a selection-ready description contains“How can you change parameter names or descriptions to make things more obvious?”
↩︎ Splitting a generic tool into purpose-specific contracts - 5.https://www.anthropic.com/engineering/writing-tools-for-agentsSecondary source
“we steered Claude in the right direction by improving the tool description”
↩︎ What a selection-ready description contains - 6.
“Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”
↩︎ What a selection-ready description contains“Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”
↩︎ Overlapping tools: rename and rescope“Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do.”
↩︎ Exam trap 3 - 7.
“Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.”
↩︎ Splitting a generic tool into purpose-specific contracts - 8.https://platform.claude.com/cookbook/tool-use-tool-choiceSecondary source
“Writing a detailed prompt helps Claude determine when to call a tool and when not to.”
↩︎ System prompt wording can override a good description - 9.https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practicesOfficial docs
“The fix is to dial back any aggressive language.”
↩︎ System prompt wording can override a good description