Tool Interface Design
Designing clear, composable tool interfaces that Claude can use effectively. Tool descriptions are the primary mechanism for tool selection -- minimal or ambiguous descriptions lead to unreliable routing, while well-crafted descriptions with input formats, examples, and boundaries dramatically improve accuracy.
Quick Reference
- →Tool descriptions are the #1 factor in tool selection accuracy -- invest time here
- →Include input formats, example queries, edge cases, and boundaries in every description
- →Ambiguous or overlapping descriptions cause misrouting between similar tools
- →Rename generic tools to reflect their actual purpose (analyze_content -> extract_web_results)
- →Split broad tools into specific ones: analyze_document -> extract_data_points + summarize_content + verify_claim_against_source
- →System prompt keywords can override or bias tool descriptions -- test interactions
- →Differentiate similar tools by specifying WHAT each one does NOT do
- →Parameter names should be self-documenting: use customer_email not id
- →Always include a description field for every parameter, not just the tool itself
- →Test tool selection with ambiguous queries to find routing failures early
Why Tool Descriptions Are the #1 Selection Factor
When Claude receives a user message and a set of available tools, it decides which tool to call based almost entirely on the tool descriptions. The name helps, but the description is where Claude learns what the tool does, when to use it, and what inputs it expects. A minimal description forces Claude to guess -- and guessing leads to wrong tool calls, wasted tokens, and broken workflows.
The exam will present scenarios where two tools have similar names but vague descriptions. The correct answer is always to improve the descriptions, not to change the tool names alone. Names are secondary -- descriptions drive selection.
Think of tool descriptions like function docstrings that an AI reads before deciding whether to call the function. Unlike human developers who can read the implementation, Claude only sees the description, parameter schemas, and the system prompt. If the description says 'Retrieves customer information' and another says 'Retrieves order details,' Claude has no way to know which one handles a request like 'What did customer #1234 order last week?' Both descriptions partially match.