Writing Good Tool Definitions: Descriptions, Schemas, and Errors
CoreImplement tools and understand the function-calling loop · Difficulty 2/5
Explanation
Description Quality Matters Most
A clear, detailed description of *what a tool does, when to use it, and what each parameter means* is the single biggest driver of correct tool selection. Under-described tools get misused or ignored -- no amount of schema precision compensates for a vague description.
Precise Input Schemas
The input_schema is JSON Schema: give it types, required fields, enums, and a description per field so the arguments Claude produces are well-formed. This reduces malformed calls, but it does not substitute for a good natural-language description -- the two serve different purposes (schema shapes the arguments; description drives *whether and when* to call the tool at all).
Error Handling
Return structured, informative errors (e.g., an is_error flag or a clear error message inside the tool_result) so Claude can recover or retry intelligently rather than guessing at what went wrong.
Right-Sizing the Tool Set
Too many overlapping tools cause confusion in tool selection and bloat the context window with definitions the model must consider on every turn. Give Claude a focused, non-overlapping set of tools sized to the actual task.
Common exam traps
- Assuming more tools or a bigger tool catalog is strictly better -- overlapping tools cause confusion and waste context; a focused, non-overlapping set outperforms a large one.
- Treating the input schema as the main lever for tool selection -- schema precision governs argument well-formedness, but the natural-language description is what drives whether Claude picks the right tool in the first place.
- Returning a bare failure instead of a structured error, which leaves Claude unable to recover or retry sensibly.
Key Takeaways
- Tool description quality -- what it does, when to use it, what each parameter means -- is the top driver of correct tool selection
- Precise input_schema (types, required, enums, per-field descriptions) produces well-formed arguments but doesn't replace a good description
- Structured, informative errors (is_error / error message) let Claude recover or retry instead of guessing
- Right-size the tool set: too many overlapping tools cause misuse and bloat context
Glossary Terms
The design flaw of giving an agent more, or more powerful, tools than its role genuinely requires. Capability bloat harms security (a hijacked agent can invoke a capability it never needed), reliability (tool-selection accuracy drops as the tool set grows and descriptions overlap), and cost (every tool definition consumes context tokens on every request). The fix is least privilege by removal -- eliminating the capability entirely -- not adding logging or confirmation prompts around it.
The practice of returning structured, actionable error information from tools rather than generic error strings. Well-designed error responses include: error type, what went wrong, what Claude should try next. Prevents Claude from retrying the same failing approach repeatedly.
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.
Related Concepts
The Tool-Use Loop: tool_use, tool_result, and Who Executes
The loop is: send tools array -> Claude emits a tool_use block (name + input) -> your code executes it -> you return a tool_result matched by tool_use_id -> Claude continues or ends the turn
Built-In Tools vs. Custom Tools vs. Skills vs. MCP Servers
Built-in tools: least effort, use them when the capability already exists (web search, code execution, computer use)