Task statement 2.1 · Tool design and MCP integration
Design effective tool interfaces with clear descriptions and boundaries
A customer writes "My account shows order 10024871 as delivered, but it never came", and the support agent calls get_customer instead of lookup_order. Neither tool is broken, but nothing the model read told the two apart.
share
The tempting fixes all add machinery. Five to eight few-shot examples, meaning sample requests paired with the right tool, help only the phrasings they show, cost tokens on every request, and leave the thin descriptions in place. A keyword routing layer bypasses the model's language understanding and breaks on a message like this one, which mentions both an account and an order. Merging both tools into one lookup_entity can be sound design, but it is far more work than a first step warrants.
KnowledgeWhat the model reads when it picks a tool
When you send tools with a request, the API builds a system prompt from each tool's name, description and input schema, then adds your own system prompt. The input schema is written in JSON Schema, a machine-readable list of the fields a call may carry. It shows what a valid call looks like but not when to make one, so tool descriptions are the primary mechanism the model uses for tool selection. Anthropic's docs call the description "by far the most important factor in tool performance". Minimal descriptions therefore lead to unreliable selection among similar tools: "Retrieves order details" fits the delivery complaint no better than "Retrieves customer information" does.
Your system prompt is read in the same pass, so its wording steers selection too. A keyword-sensitive instruction such as "For anything about accounts, use get_customer" creates an unintended tool association between the word account and that tool, whatever the customer is asking. This customer says "account" but asks about a delivery, so the line sends the request to get_customer even after both descriptions are fixed. One such line can override well-written tool descriptions, so a misrouting review always reads the system prompt too.
Interactive · one message, three things the model can read
Minimal descriptions, neutral prompt.
Differentiated descriptions, neutral prompt.
Same descriptions, plus a keyword line.
get_customer. Differentiated: get_customer says it is not for questions about one order, and lookup_order names the 8-digit input and missing deliveries, so the message has one obvious destination. Keyword line: the descriptions are unchanged, but the system prompt ties the word account to get_customer. The customer wrote "account", so the unintended tool association wins over the descriptions. KnowledgeWhat a description has to say
A description that routes reliably differentiates its tool from similar ones. It states the purpose and outputs, the expected inputs with their input formats, one or two example queries, the edge cases that would otherwise fail, and a boundary explanation: when to use this tool versus the similar alternative, by name. Ambiguous or overlapping tool descriptions leave the model guessing, and a guess that is sometimes wrong is misrouting. As Anthropic's engineers put it, "When tools overlap in function or have a vague purpose, agents can get confused about which ones to use."
SkillFixing the misrouting: descriptions first, then the prompt
Production logs show order questions landing on get_customer. The cause is two one-line descriptions: both tools accept an ID, and neither says what it is not for. The fix rewrites both, with one sentence per item in the list above.
Both tools, one line each
get_customer "Retrieves customer information" lookup_order "Retrieves order details"
Result: neither names the other, so the model has no basis to choose.
get_customer "Look up one customer by email, phone or customer ID (C-4471). Returns the profile, account status and recent order numbers. Use it first to confirm who is writing. Not for questions about one order: an 8-digit number is an order number, so use lookup_order." lookup_order "Look up one order by its 8-digit number (10024871; customers may type #10024871). Returns items, status, delivery date and refund eligibility. Use for 'where is my order?', returns and missing deliveries. No number? Call get_customer to list orders."
Result: each boundary names the other tool and the input that belongs to it.
With both rewrites, the delivery complaint reaches lookup_order. If a message still misroutes, review the system prompt for keyword-sensitive instructions next. "For anything about accounts, use get_customer" becomes "Use get_customer to confirm who the customer is, and lookup_order for questions about a specific order", which names an intent rather than a word. Few-shot examples and routing layers come after these two cheaper fixes.
SkillWhen no description can fix it: split or rename
Some tools cannot be described clearly because they do several jobs. get_account_info returns a profile with no include argument, charge rows with include: "billing", and ticket ids with include: "tickets". Nothing tells the model which value gives which shape, so it guesses, and every later step must handle all three. Splitting generic tools into purpose-specific tools with defined input/output contracts gives each job one name, one set of inputs and one output.
get_account_info(customer_id,
include?)
→ no include: a profile
→ include "billing": charge rows
→ include "tickets": ticket idsThe output shape depends on an argument the description never explains.
get_customer(customer_id) → profile + account status get_billing_history(customer_id, months) → dated charge rows list_open_tickets(customer_id) → ticket ids + statuses
Each tool has one job, one input contract and one output shape.
In the guide's system, analyze_content and analyze_document had near-identical descriptions, so a request about web search results could land on either. The first fix is renaming tools and updating descriptions to eliminate functional overlap: analyze_content becomes extract_web_results with a web-specific description, so the names stop competing. The second splits the generic analyze_document into extract_data_points, summarize_content and verify_claim_against_source, each stating what it takes and returns.
// before: near-identical (wording illustrative) analyze_content "Analyzes content." analyze_document "Analyzes a document." // after (signatures illustrative) extract_web_results(results) → facts per web result, never uploaded files extract_data_points(doc_id, fields) → {field: value} summarize_content(doc_id, max_words) → summary text verify_claim_against_source(claim, doc_id) → supported | contradicted | absent
KnowledgeSplitting versus consolidating
Anthropic's tool-use docs also recommend consolidating related operations, such as one tool with an action parameter instead of create_pr, review_pr and merge_pr, because fewer tools reduce selection ambiguity. Both directions pass one test: can the model predict what each call needs and returns? A consolidated tool passes when every action value is documented, and get_account_info fails because its include values are not. For misrouting, the guide's Sample Question 2 calls merging into lookup_entity "a valid architectural choice", but more effort than a first step warrants.
More precise than the guide. The guide teaches splitting generic tools, while Anthropic's Define tools page recommends one tool with an action parameter for related operations, and its engineering article suggests workflow tools such as get_customer_context (checked 2026-10-01). Exam answer: split a generic tool with unpredictable outputs into purpose-specific tools with defined input/output contracts, and fix descriptions before consolidating tools that misroute.
| Thin or near-identical descriptions | Rewrite both: purpose, input format, example query, edge case and boundary. Rename a tool whose name competes. |
| A keyword instruction in the system prompt | Rewrite the line around the customer's intent, not a word. |
| One tool whose output depends on a hidden argument | Split it into purpose-specific tools with defined contracts. |
- Descriptions are the primary selection mechanism, so two one-line descriptions make similar tools interchangeable.
- A system-prompt line keyed to a word such as "account" can override correct descriptions.
- The guide splits generic tools, and the docs also accept one tool with a documented
actionparameter.