Writing tool descriptions agents actually use

An agent chooses tools by reading their names and descriptions. If a tool is never called, the problem is often not the tool but how it introduces itself. Descriptions are the interface agents actually see.

Write for the moment of choice

The model is deciding, right now, which tool fits the user's intent. Say plainly what the tool does, when to use it, and when not to. Lead with the verb and the object: 'Create an issue in the project tracker.'

Be specific about inputs

• Name arguments the way a model would guess them
• State accepted shapes and give a short example
• Avoid overlapping tools that compete for the same intent

Close the loop with data

Ship a description change, then watch adoption for that tool. If calls rise and success holds, the wording was the blocker. Treating descriptions as something you measure and iterate on is how underused tools come back to life.