Tool Schema Best Practices
Tool schemas are the primary signal Claude uses for tool selection. Name, description, and parameter descriptions matter more than implementation.
| Rule | Details |
|---|---|
| Clear tool names | Use verb_noun format: search_documents, create_ticket |
| Describe every parameter | Claude cannot see defaults — describe what happens if omitted |
| Constrain with enums | Use enum arrays for parameters with known valid values |
| Mark required fields | Always explicitly list required parameters in the schema |
| Avoid deep nesting | Flat schemas are easier for Claude to fill correctly |
| Anti-Pattern | Why It Fails |
|---|---|
| Generic tool names (do_action, process) | Claude cannot distinguish between similarly vague tools |
| Missing parameter descriptions | Claude guesses wrong values or skips optional params |
| Too many tools (>15-20) | Tool selection accuracy drops — consolidate or use routing |
| Overlapping tool purposes | Claude picks randomly between similar tools |
MCP Architecture
MCP follows a client-server architecture. Servers expose three capability types:
| Capability | Purpose | Example |
|---|---|---|
| Tools | Executable actions | search_database, send_email |
| Resources | Read-only data access | file://docs/readme.md, db://users/123 |
| Prompts | Reusable prompt templates | code_review, summarize_document |
Transports: stdio for local processes (default), HTTP+SSE for remote servers.
Tool Error Handling
Never throw unhandled exceptions from tools. Return structured errors with is_error: true so Claude can reason about the failure and attempt recovery.
Include actionable context: what failed, why, and what the user or Claude could try differently.
Tool Selection Strategy
When Claude has many tools available, selection accuracy depends on: (1) distinctness of tool names and descriptions, (2) system prompt guidance about when to use which tool, and (3) keeping the total tool count manageable.
Key rule: If you have more than 15-20 tools, consider routing to specialized agents with smaller tool sets.