Build with AI and trust what you make. Free guide, no signup

Write tool descriptions the model can choose from

The model never sees the code behind a tool. It picks from the name and the description alone, which makes the description how the model chooses.

When you give an agent tools, the model never sees the code behind them. It picks which tool to use from the name and the description alone. So the description is not documentation. It is how the model chooses, and a thin description means it picks the wrong one.

A good description says what the tool is for, what it takes in, what it gives back and when to use it instead of a similar one. Add an example. Do that for every tool and the right choice becomes obvious.

Common questions

  1. What makes one description better than another?
    A good description is precise and uses the same words and units as the others, so the model can compare them side by side. It gives an example or two, covers the edge cases, and says when to use this tool rather than the similar one next to it.
  2. The model keeps picking the wrong tool. What do I check first?
    Two tools that sound the same are the usual trap. If their descriptions overlap the model cannot tell them apart, so it guesses between them.
  3. How do I fix an overlap between two tools?
    Rename one of them to remove the confusion. If it cannot be renamed, rewrite how it is described so it is clear which tool to use when.
  4. What if one tool is trying to do too much?
    The AI needs to know exactly what a tool will do, so nothing generic. Split a broad tool into single-purpose tools, each with a clear contract saying exactly what it does, and there is nothing left to guess.
  5. The descriptions are clear and it still picks wrong. Where else do I look?
    Your own system prompt. A keyword you keep repeating there can tie the model to a tool on the word alone, so a prompt that keeps saying "document" pulls it toward the document tool whatever the descriptions say.
  6. So how do I find the word that is steering it?
    When the wrong tool keeps getting picked, read back over the system prompt for keywords pulling it there, then fix the wording so it stops biasing the choice.

Back to For developers. The craft around it is Working with AI.