Tool Interface Design
ToolsDefinition
The practice of writing tool definitions (name, description, input schema) that enable Claude to reliably select and use tools correctly. Key principles: precise descriptions that distinguish similar tools, explicit input format requirements, clear boundary examples, and documented error return formats.
Example Usage
Write tool descriptions that answer 'when should I use this vs. the other similar tool?' explicitly — Claude uses descriptions to decide between tools.
In Depth
Tool interface design is the discipline of writing tool definitions — name, description, and input schema — in a way that enables Claude to reliably select the right tool and populate it correctly. It sits in Domain 2 of the CCA-F because good tool interfaces are an architectural concern, not an afterthought.
Claude chooses among available tools based primarily on the description field. That means the description is the most important piece of the definition. A strong description answers three questions: what this tool does, when to use it (vs. similar tools), and what it does NOT do. If you have a search_documents tool and a search_database tool, both descriptions must explicitly distinguish them — otherwise Claude will guess, and guesses lead to misroutes and failed calls.
Naming conventions matter. Tool names should be unambiguous, verb-noun pairs that match natural language — get_weather, create_issue, search_products. Avoid abbreviations and internal jargon. Claude's routing uses the name as a signal alongside the description; a name like proc_fn_v2 provides no signal at all.
Input schemas should be precise and complete. Use JSON Schema to constrain types, enumerate valid values with enum, and mark all required fields. Include description properties on each field — Claude reads them when filling in values, and a field described as "ISO 8601 date string" is less likely to receive "tomorrow" than a field with no description. Avoid overly permissive schemas (type: "object" with no properties) because they shift validation burden to your runtime and increase the chance of unexpected inputs.
Document error behaviors in the description. If the tool returns a structured error object when a resource is not found, say so. If it throws on invalid inputs rather than returning an error, note that. This feeds directly into error-response-design — Claude can only use error information it knows exists.
Limit tool counts per call. Claude's ability to distinguish tools degrades as the list grows. Provide only the tools relevant to the current task context. If your architecture has 30 tools, consider using a tool distribution pattern — routing subsets of tools to specialized agents rather than exposing all 30 to every turn.
See Tool Definitions & Descriptions for worked examples and Tool Selection Reliability & Debugging for debugging misroutes.
How It's Tested & Common Confusions
The exam tests tool interface design through scenario-based questions:
- Misroute diagnosis: given a scenario where Claude consistently picks the wrong tool, identify which part of the definition is ambiguous (almost always the description).
- Schema completeness: given a tool schema and an undesirable input Claude produced (e.g., passing a human-readable date instead of ISO 8601), identify which schema field or field description would prevent it.
- Tool count tradeoffs: understand that passing more tools increases ambiguity and costs tokens; the correct design prunes to the relevant subset.
- Description vs. name priority: know that description is the primary routing signal, not the name alone.
- MCP primitives alignment: understand that MCP Tools follow the same interface design principles as native tools — the description field is equally critical.
Frequently Asked Questions
How long should a tool description be?
Long enough to unambiguously distinguish the tool from all similar tools, but no longer. A single sentence is rarely enough; two to four sentences covering what it does, when to use it, and what it does NOT do is typical. Overly long descriptions waste context tokens and may bury the key routing signal.
Should I add examples inside the tool description?
Yes, selectively. A brief example of a valid input or a boundary case ("use this for read-only lookups; for writes, use update_record instead") can dramatically improve selection accuracy for tools that are conceptually close to each other.
Does `strict: true` on a tool definition help with interface reliability?
Yes. Setting `strict: true` in a tool definition tells the API to enforce the schema strictly, guaranteeing that `tool_use.input` will be valid against the schema before it reaches your code. This eliminates a class of runtime errors but does not replace the need for a well-described, clearly-named tool.