Tool description
The description is the model's only clue about when to use a tool. Vague descriptions lead to wrong tool choices.
Last updated
Analogy
API docs for an audience that takes every word literally. "Gets stuff" is as useful to the model as it is to your teammates.
Code example
// Bad: the model can't tell when to use itdescription: "Gets PR data", // Good: says what, when, and what comes backdescription: "List open pull requests for a repo. Use when the user asks " + "about blocked, stale or pending PRs. Returns id, title, author, ageDays.",In an agent
Bad descriptions are the most common agent bug. Rewriting them is often the fix for "it picked the wrong tool".
Questions people ask
How do I write a good tool description?
Say what the tool does, when to use it and what comes back. For example: list open pull requests for a repo; use when the user asks about blocked or stale PRs; returns number, title and age. The model takes every word literally, so vague text like gets PR data leads to wrong choices.
Why does my agent pick the wrong tool?
Most often the descriptions are vague or overlap, so the model cannot tell the tools apart. Rewrite each description to say exactly when it applies and when it does not. Also check that you are not offering too many tools in one prompt; fewer, clearer tools lead to better choices.