LLMs, GenAI, RAG, agents, evaluation · insight-0644
Write tool descriptions like an interface spec and test them with varied inputs
- Evidence type
- practitioner heuristic
- Difficulty
- easy
- Roles
- Applied AI, ML engineer
- Industries
- cross-industry
Summary: situation, action, reason, boundary
Situation
Tools are registered with one-line descriptions such as "search bookings", and the agent misuses them.
Action
Describe each tool's purpose, when not to use it, parameter formats with examples, and edge cases; then run a batch of varied requests and review which tool and arguments were chosen.
Reason
The model chooses and fills tools from their descriptions. Anthropic's guidance treats tool definitions as deserving the same care as a human-computer interface and recommends iterating on them with many example inputs.
Boundary
Every agent, especially with more than a handful of tools.
Symptom or risk
The model passes names where ids are expected, uses the wrong date format, or picks a similar-sounding tool, and each mistake looks like model weakness.
Exceptions
Tools with a single obvious use and one parameter.
Trade-offs
Long descriptions add input tokens to every request that loads the tool.
Pitfalls
Fixing misuse with prompt instructions instead of renaming or splitting a confusing tool.
Lessons and concepts
Claims and their sources
Anthropic's guidance recommends documenting tools with example usage, edge cases and input formats and testing how the model uses them with many example inputs.
Tool names, descriptions and schemas are sent as input tokens on each request that includes them.