How to Write Tool Descriptions That AI Agents Actually Use

When an AI agent has ten tools available and needs to pick one, it reads the descriptions. That's it. There's no magic — the model scans the text you wrote and decides which function to call based on what you said it does. Which means if your descriptions are generic, ambiguous, or missing key constraints, you will get wrong tool calls. Every time.

I've rebuilt tool descriptions from scratch on three different agent systems after watching them make dumb, preventable mistakes. Here's the framework I landed on.

Lead With What the Tool Does, Not What It Is

The most common mistake I see is describing what a tool is rather than what it does. Compare these two descriptions for the same database query tool:

Bad: "Database query tool for accessing records."

Good: "Fetches a single customer record by customer_id. Use this when you need to look up a specific customer's details. Do NOT use this for searching or listing multiple customers — use search_customers for that."

The second version tells the agent three things: what it gets, when to use it, and when not to use it. That disambiguation is critical when you have multiple tools with overlapping domains.

I aim for this structure in every description:

1. Action verb + what it returns (one sentence)
2. When to use it (trigger condition)
3. When NOT to use it (disambiguation from similar tools)

Make Parameter Constraints Explicit

Parameters get their own descriptions, and those descriptions need to include constraints, not just labels. A parameter named date with description "The date" is useless. The agent doesn't know if you want ISO 8601, Unix timestamp, or "yesterday". It will guess, and it will guess wrong half the time.

Here's a parameter description that actually works:

{
  "name": "start_date",
  "type": "string",
  "description": "Start of date range, inclusive. Format: YYYY-MM-DD (e.g. '2026-01-15'). Must be within the last 90 days. Do not use relative dates like 'yesterday'."
}

Notice what's in there: format, example, constraint, and one explicit negative. That last part — "do not use relative dates" — comes from watching an agent pass "yesterday" three sessions in a row before I added it.

For enum parameters, list the valid values directly in the description even if they're already in the schema. Redundancy here is a feature. The agent reasons over text before it validates against schema — spelling it out in the description catches errors earlier.

Disambiguate Similar Tools Explicitly

The hardest case is when you have two tools that do related things. Search vs. fetch. Create vs. update. List vs. filter. Agents get confused by these constantly if the descriptions don't actively guide the selection.

My pattern: each tool in a similar pair should reference the other one by name and explain the difference. If I have get_user and search_users:

• get_user: "Fetches a single user by exact user_id. Requires you to already know the user_id. If you need to find a user by name or email, use search_users instead."
• search_users: "Searches users by name, email, or role. Returns a list of matching users. If you already have the user_id, use get_user instead — it's faster."

Cross-referencing by name forces the agent to consciously consider which one fits. Without this, it will just pick whichever description sounds vaguely closer and move on.

Add Examples for Complex Parameters

For any parameter that takes structured input — JSON objects, arrays, query strings, filter expressions — include at least one example in the description. Models are good at pattern-matching from examples. A well-chosen example communicates intent faster than a paragraph of explanation.

For a filter parameter that accepts complex expressions:

"description": "Filter expression using field:value syntax. Supports AND/OR. Example: 'status:active AND plan:pro'. For date ranges: 'created_at:>2026-01-01'."

That single example tells the agent the syntax, operator format, and date comparison pattern all at once. No paragraph of prose needed.

Length Is Not Virtue — Precision Is

Longer descriptions aren't better. I've seen bloated descriptions with six sentences of background context that bury the actual usage instruction. The agent has to read all of it and extract what matters — and sometimes it gets distracted by the wrong part.

The right length is: everything needed to use the tool correctly, nothing else. Usually 2-4 sentences for the top-level description, 1-3 sentences per parameter. If you find yourself writing a paragraph explaining domain background, stop. Put that in the system prompt, not the tool description.

Treat Descriptions as Living Documentation

Tool descriptions aren't set-and-forget. I update mine after almost every debugging session. When I see an agent make a wrong tool call in WatchDog traces, I go back and ask: what would the description have needed to say to prevent this? Then I add it.

The most durable improvements come from categorizing failures:

• Wrong tool chosen: Add disambiguation to both the chosen tool and the correct one
• Wrong parameter format: Add format constraint and example to that parameter
• Tool called when it shouldn't be: Add a "do NOT use when..." clause
• Required parameter left empty: Mark it required and explain why it's needed

After three or four of these cycles, tool descriptions on a mature system start looking more like rules than documentation. That's fine — that's what they should be.

The Selector Test

Here's a quick check I run on any tool set before deploying: I take a list of realistic user intents and, for each one, try to pick the right tool using only the descriptions — no code, no schemas. If I can't consistently pick correctly, the agent won't either.

This sounds obvious, but almost every team I've talked to writes tool descriptions as code comments rather than as instructions to a reasoning system. The shift is subtle but it changes everything about what you write and how specific you get.

Tool descriptions are the primary interface between your agent and its capabilities. Treat them accordingly.