How to Write Tool Descriptions Agents Actually Understand

Picture this: you're an engineer at a SaaS company, and your support agent keeps refunding customers who only asked about the refund policy. Not a code bug — every function works perfectly in isolation. The agent is simply picking the wrong tool, over and over, and no amount of retrying fixes it. The problem, it turns out, lives in your AI agent tool descriptions — specifically one sentence, a tool description so vague the model couldn't tell "explain the policy" from "issue the refund."

This is the most underestimated skill in agent building. Let me walk through how one team fixed it, because AI agent tool descriptions are where reliability is won or lost.

The Problem: AI Agent Tool Descriptions Nobody Could Read

The support agent had two tools. One looked up refund eligibility and explained the policy. One actually processed a refund. Their descriptions read, in full: "Handle refund" and "Process refund request."

Read those the way the model does — as the only information it has about when to use each. They're nearly identical. "Handle" and "process" are synonyms. Both mention refunds. Faced with "what's your refund policy?", the model flipped a coin, and sometimes the coin said "issue money." The code was flawless. The descriptions were unusable.

It's worth appreciating how invisible this is in code review. A reviewer reads the two functions, sees correct logic, and approves. The descriptions live in a schema dict that looks like documentation, not logic, so nobody scrutinizes them. The bug passed every human check because humans read the code — and the model reads the text.

The Wrong Approach

The team's first instinct was to fix it in the system prompt. They added a paragraph: "Be careful with refunds. Only process a refund if the customer explicitly requests one and is eligible." It helped a little, then failed again the first time a customer phrased things ambiguously.

The reason the patch didn't hold: the system prompt is read once, but the tool choice happens fresh every step, weighed mostly against the tool descriptions right there at the decision point. A distant instruction competes weakly against two descriptions that still looked interchangeable. They were treating a labeling problem as a behavior problem.

There's a general principle hiding here about where the model looks. The tool descriptions are in the model's face at the instant of choosing; the system prompt is context it processed turns ago. When those two sources of guidance disagree, or when one is specific and the other general, the nearby specific one usually wins. Fix the guidance closest to the decision. This is why chasing tool-selection bugs through the system prompt so often feels like whack-a-mole — you're adjusting the far voice while the near one keeps overriding it.

⚡ Pro tip: When an agent picks the wrong tool, fix the tool descriptions before you touch the system prompt. The description sits at the decision point; the system prompt is a faint voice from across the room.

The Correct Prompt

They rewrote both descriptions using a four-part formula: what it does, when to use it, when NOT to use it, and what it returns.

Notice the order matters as much as the content. Leading with "what it does" orients the model; the "when to use / when not" pair draws the boundary; and "what it returns" tells the model what it'll get back so it can plan the next step. Skip any of the four and you leave a gap the model fills with a guess.

check_refund_eligibility:
  "Check whether an order qualifies for a refund and explain the
   policy to the customer. USE when the customer asks about refund
   policy, eligibility, or 'can I get a refund'. Do NOT move any
   money. Returns eligibility status and the policy explanation."

process_refund:
  "Issue an actual refund to the customer's payment method. USE ONLY
   after the customer has explicitly confirmed they want the refund
   AND eligibility was checked. This MOVES REAL MONEY and cannot be
   undone. Returns a confirmation number."

What this does: it makes the two tools impossible to confuse. The first says explicitly "do NOT move money"; the second says "USE ONLY after confirmation" and flags that it's irreversible. The model now has a bright line at the exact moment it's choosing, which is the only moment that matters.

The same formula rescues wrong-tool bugs across domains. A healthcare intake agent that confused "look up patient record" with "update patient record" stopped mixing them once each description named what it must not do. A devops agent that treated "check service status" and "restart service" as interchangeable — turning questions into outages — got a bright line from a single "this RESTARTS the service and causes downtime" clause. A sales agent that logged calls under the wrong contact fixed it by contrasting "find_contact" against "create_contact" explicitly. Different industries, identical cure.

⚡ Pro tip: For any tool with side effects, put the consequence in capital letters in the description: "MOVES REAL MONEY," "DELETES THE RECORD," "SENDS THE EMAIL." The model treats emphasized, explicit consequences with more caution, and you want maximum caution on irreversible actions.

Results and What Changed

Wrong-tool refunds dropped to zero in testing and stayed there in production. The fix was two sentences per tool — no model change, no new system prompt paragraph, no code touched.

More interesting was the second-order effect. Once descriptions carried real "when not to use" boundaries, the team could add more tools without accuracy degrading, because each new tool came with its own bright line rather than blurring into the pile. Their earlier fear of adding tools had been, underneath, a fear of vague descriptions.

That reframing is worth holding onto. Teams often cap their tool count because "too many tools confuses the model." Sometimes true — but usually the confusion comes from overlapping descriptions, not from the raw number. Sharpen the boundaries and the ceiling on how many tools you can safely expose rises substantially.

⚡ Pro tip: The "when NOT to use it" clause is what lets you scale the number of tools. Without boundaries, every tool you add makes the others harder to choose; with boundaries, tools stay distinguishable no matter how many you have.

How to Apply This to Your Situation

Audit your descriptions with one test: read only the descriptions, not the code, and try to pick the right tool for a few sample requests. If you hesitate, the model will too, and now you know which pair needs a sharper boundary.

Do this test with the actual requests your users send, not idealized ones. Real requests are messier and more ambiguous than the examples you'd invent, and it's the messy ones that expose which descriptions can't hold the line. If your descriptions survive your ugliest real tickets, they'll survive the clean ones.

⚡ Pro tip: Run your wrong-tool test with your ugliest real user requests, not clean invented ones. Boundaries that hold under messy input hold everywhere; boundaries tested only on tidy examples fail in production.

Apply the four-part formula to each tool. What does it do, when should it be used, when should it explicitly not be, and what does it return. The second and third parts are the ones people omit and the ones that carry the weight.

For similar tools, write the descriptions as a contrast set — each one naming what makes it different from its neighbors. "get_customer returns profile data only; use get_customer_orders for purchase history" beats two independent descriptions that never reference each other.

Set a recurring check: whenever you add a tool, re-read it beside its two nearest neighbors and ask whether a stranger could tell them apart from the descriptions alone. New tools are where boundaries erode, because the new one is written in isolation while the old ones fade from memory.

⚡ Pro tip: Write descriptions for confusable tools together, in the same sitting, so you can explicitly name the difference in each. Descriptions written separately, months apart, are how two tools end up sounding like synonyms.

Next Steps

Tool descriptions are the interface the model programs against, and they're written in plain language, which fools people into treating them casually. The four-part formula — what, when, when-not, returns — turns a vague label into a reliable instruction, and the "when not to use it" clause is the single highest-value sentence you'll write.

Treat every tool description as a small contract with the model: here's exactly what this does, here's when it applies, here's when it doesn't, here's what you get back. Contracts that precise are what let agents scale from two tools to twenty without the wheels coming off.

⚠️ Common mistake: Writing tool descriptions as short labels ("Handle refund") instead of instructions, on the assumption that the function name says enough. The model doesn't run the function or read your code — it reads the description and nothing else, so a two-word description gives it almost nothing to decide with.

Because these descriptions are pure text that directly controls agent behavior, they're worth managing as carefully as any code. PromptABCD lets you store, version, and reuse tool descriptions across projects, so the four-part refund descriptions this team perfected don't get rewritten as "Handle refund" all over again in the next service.