Intermediate9 min
Writing Effective Tool Descriptions
The art of tool descriptions: how the LLM reads them, what makes a description effective, and patterns for reducing tool selection errors.
Quick Reference
- →Tool descriptions are the LLM's only guide for choosing which tool to use — they are more important than the tool's code
- →Include: what the tool does, when to use it, when NOT to use it, required parameters, and example inputs
- →Use negative examples ('Do NOT use this tool for X') to prevent common misuse patterns
- →Keep parameter descriptions specific: 'ISO 8601 date string (e.g., 2024-01-15)' not just 'the date'
- →Test tool descriptions by asking the LLM to explain when it would use each tool — if it gets confused, the descriptions are ambiguous
How LLMs Read Tool Descriptions
When you bind tools to a model, the descriptions are serialized into the system prompt as a JSON schema. The LLM reads this schema at every turn to decide which tool to call. The description is literally the only context the LLM has for choosing correctly.
What the LLM actually sees (simplified)
Empty parameter descriptions are a silent killer
If you don't annotate parameter types and descriptions, the LLM guesses. This leads to format errors (passing 'January 15' instead of '2024-01-15') that fail silently or produce wrong results.