Anatomy of a Tool Schema
A tool schema has three parts: name, description, and input_schema. The name should be a clear verb_noun format (e.g., search_documents, create_user). The description should explain what the tool does, when to use it, and what it returns. The input_schema is a JSON Schema object defining parameters with types, descriptions, and constraints.
Claude reads the description to decide whether to use the tool. It reads the input_schema to decide what parameters to pass. Both must be precise and unambiguous.
Writing Effective Descriptions
Tool descriptions should answer three questions: What does this tool do? When should it be used (and when should it NOT be used)? What does it return? Include edge cases and limitations in the description.
For example, a search_database tool description might say: 'Searches the product database by keyword. Use this when the user asks about specific products, prices, or availability. Do NOT use for general questions about company policies. Returns up to 10 matching products with name, price, and stock status. Returns an empty array if no matches found.'
Parameter Design Best Practices
Each parameter should have a descriptive name, a type, a description, and appropriate constraints. Use enums for parameters with a fixed set of valid values. Mark parameters as required only when they are truly necessary. Provide default values in descriptions for optional parameters.
Avoid overly complex schemas with deeply nested objects. Claude handles flat or shallowly nested schemas most reliably. If you need complex input, consider breaking the tool into multiple simpler tools.
Key Concept
The Description Is the Documentation
Claude decides whether and how to use a tool based entirely on the tool's description and schema. There is no hidden training on your tools — the description IS the documentation. If the description is vague, Claude will use the tool incorrectly. If it is precise, Claude will use it correctly. Invest as much effort in tool descriptions as you would in API documentation for human developers.
Exam Traps
Using vague tool descriptions
A description like 'searches the database' is insufficient. Claude needs to know what database, what kind of searches, what's returned, and when to use it vs. alternatives.
Overloading tools with too many parameters
Tools with many optional parameters are harder for Claude to use correctly. Break complex tools into simpler, focused tools.
Not specifying when NOT to use a tool
Descriptions should include negative guidance — when the tool should NOT be used. This prevents Claude from using tools inappropriately.
Check Your Understanding
You have a tool called 'query' with the description 'runs a query'. Which improvement would most help Claude use this tool correctly?
Build Exercise
Design a Tool Schema Set
What you'll learn
- Write effective tool descriptions
- Design precise input schemas
- Use enums and constraints appropriately
- Test tool schemas with Claude
Design a tool schema for a 'search_products' tool. Include name, description (with when to use/not use), and input_schema with search query, category enum, and price range.
WHY: This exercises all aspects of schema design: naming, description, and parameter constraints.
YOU SHOULD SEE: A complete tool schema with clear description and typed parameters.
Design a companion 'get_product_details' tool that retrieves full details for a specific product by ID.
WHY: Separate tools for search (returns summaries) and details (returns full info) is a common pattern that improves reliability.
YOU SHOULD SEE: A focused tool with a single required parameter (product_id) and clear description.
Test both tools with Claude by creating a message with a user query like 'Find me a laptop under $1000 with at least 16GB RAM'. Observe which tools Claude calls and with what parameters.
WHY: Testing with real queries reveals whether your schemas are clear enough for accurate tool use.
YOU SHOULD SEE: Claude calls search_products first with appropriate parameters, then get_product_details for promising results.
Iterate on the schemas based on test results. Refine descriptions, add constraints, and test again.
WHY: Tool schema design is iterative. Real-world testing reveals ambiguities that aren't obvious during design.
YOU SHOULD SEE: Improved tool usage after schema refinements.
Sources
- Tool Use Overview— Anthropic Documentation
- Tool Use Best Practices— Anthropic Documentation