2.1 Tool interfaces with clear descriptions and boundaries
Tool descriptions are the primary mechanism an LLM uses for tool selection. When descriptions are minimal, the model has nothing to differentiate similar tools with — so it misroutes. The first fix for unreliable selection is better descriptions, not a routing layer, not few-shot examples, not consolidation.
What a good description contains
| Element | Why |
|---|---|
| Purpose | What the tool is for, in one line |
| Input formats it accepts | order_id as #12345 or 12345; email or customer ID |
| Example queries | Anchors the match between user phrasing and this tool |
| Edge cases | Empty results, multiple matches, partial data |
| Boundary explanation | "Use this instead of X when…" — the differentiator |
| Outputs | What comes back, so the model can plan the next step |
{
"name": "lookup_order",
"description": "Retrieves details for a SINGLE order: line items, quantities, prices, fulfilment status, carrier tracking, and return eligibility. Accepts an order number with or without the leading '#' (e.g. '#12345' or '12345'). Example queries: 'where is order 12345', 'what did I buy on order #987'. Returns an empty result (not an error) when the order number does not exist. Use lookup_order when the user references an order. Use get_customer instead when the user references themselves, an email address, or an account, or when you need a verified customer_id before an order operation.",
"input_schema": {
"type": "object",
"properties": { "order_id": { "type": "string" } },
"required": ["order_id"],
"additionalProperties": false
}
}
Overlapping descriptions cause misrouting
analyze_content and analyze_document with near-identical descriptions is the canonical failure. Two fixes:
- Rename and re-describe to remove overlap —
analyze_content→extract_web_resultswith a web-specific description. - Split a generic tool into purpose-specific tools with defined input/output contracts —
analyze_document→extract_data_points,summarize_content,verify_claim_against_source.
System prompt wording overrides descriptions
Tool selection is keyword-sensitive. A system prompt saying "always analyze the customer's content before responding" creates an unintended association with a tool named analyze_content, even when a better-described tool exists. Review system prompts for keyword-sensitive instructions that might override well-written descriptions.
Quiz
- Question 1
Production logs show the agent frequently calls get_customer when users ask about orders (e.g. "check my order #12345") instead of lookup_order. Both tools have minimal descriptions ("Retrieves customer information" / "Retrieves order details") and accept similar identifier formats. What is the most effective first step to improve tool selection reliability?
- Question 2
Your system exposes analyze_content ("Analyzes content and returns key points") and analyze_document ("Analyzes a document and returns key points"). Traces show web search results going to analyze_document about a third of the time and PDFs going to analyze_content nearly as often. Both tools accept a text blob. What is the most direct fix?
- Question 3
After you added the line "Always verify claims against primary sources before reporting" to the system prompt, the agent began calling verify_claim_against_source on every intermediate note, roughly tripling tool calls and adding 40 seconds per task. The tool descriptions were not touched and were already precise about scope. Where does the problem sit?
- Question 4
A single manage_account tool takes an action string — update_address, close, add_payment_method, change_plan and six others — plus a free-form payload. The agent picks the wrong action about 8% of the time and regularly pairs a correct action with a payload shaped for a different one. The description is 40 lines and grows with every new action. What is the right correction?
Links
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
- https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use
- https://code.claude.com/docs/en/agent-sdk/custom-tools
- https://www.anthropic.com/engineering/writing-tools-for-agents