The tool description is a prompt, so write it like one

A developer on an agent team told me they had spent weeks frustrated with a model that “could not use tools right.” It called the wrong function, passed arguments in the wrong shape, used a tool in situations it did not fit. The team had started to conclude the model was not good enough for the job. Then someone actually read the tool descriptions they had written. They were one-liners. Terse, ambiguous, full of shorthand only the team understood. The model was not failing to use the tools. It was using the only guidance it had, and that guidance was thin.

The description is the only thing the model reads

Here is the fact that reframed the whole problem for them. When the model decides whether to call a tool and how, it does not see your code. It does not know what the function really does, what the team meant, or how the arguments are used downstream. It sees the name, the description, and the parameter definitions. That text is the entire basis for the decision. If the description is vague, the model is deciding on vague information, and vague information produces the wrong calls.

Their descriptions had been written as reminders for themselves, not as instructions for the model. A field labeled “id” with no note about which id. A tool described as “handles updates” with no word on what it updates or when to use it. To the people who wrote them, these were clear enough, because they carried the missing context in their heads. The model had no head to carry it in. It had the string, and the string did not say enough.

Blaming the model hides the real lever

As long as the team believed the model was the problem, they were stuck, because they were trying to fix the wrong thing. You cannot make a model choose better by wishing it were smarter. You can make it choose better by giving it better information to choose from, and the description is exactly that information. The frustration came from looking at the one part of the system they could not easily change and ignoring the part sitting right in front of them.

Once they treated the descriptions as prompt-engineering surface, the fix was ordinary work. A description is a prompt. It is text you write to steer a model toward the behavior you want, which is the definition of prompt engineering. It deserves the same care as the main system prompt, because it drives decisions just as directly.

Write descriptions like the prompts they are

Rewriting the tool and parameter descriptions turned the wrong calls into right ones.

Say what the tool does and when to use it. Give the action, the situation that should trigger it, and where it does not apply. That is what the model needs to choose.
Describe every parameter fully. What it is, what format it takes, what a valid value looks like. “id” becomes “the account id, a string like acct_123.” Ambiguity in a parameter is a malformed argument waiting to happen.
Draw the line against similar tools. When two tools are close, each description should name the boundary, so the model knows which one this is for.
Test and revise them like prompts. Run your cases, see where the model picks wrong, and improve the description that led it there. The description is iterated, not written once.

They changed no model and rewrote no dispatch code. They wrote the descriptions properly, and the calls the team had blamed on the model came right.

How we approach it at Density Labs

In the AI Opportunity Assessment, our fixed two-week engagement priced at $2,500, when an agent uses its tools badly we read the tool descriptions before we question the model, because the description is the only thing the model reads to decide. Terse, insider shorthand is one of the most common causes of wrong tool use we find, and rewriting those descriptions with the care you would give the main prompt fixes calls that looked like a model limitation. The cheapest reliability gain is often in text you already control.

The description is the prompt the model reads to choose. Write it with the same care as the rest.