When an agent has access to a dozen tools, it does not read your source code or your README. It reads a name, a description, and a parameter schema, then guesses. Many "the model keeps calling the wrong tool" bugs are really "the description never said when *not* to call it" bugs.

Describe the decision, not the implementation

A description written for a human maintainer says what the function does internally. A description written for selection says when to use it and how it differs from its neighbors.

Compare:

  • *Weak:* "Queries the orders table."
  • *Better:* "Look up a single order by its order ID. Use this when the user gives an order number. Do not use it to search by customer name or date; use search_orders for that."

The second version names the trigger, the required input, and the nearest confusable tool. That last part matters most. If two tools overlap, say so explicitly in both descriptions and state the tie-breaker.

Make names and parameters carry meaning

  • Verb-first, specific names. get_order_by_id and search_orders are distinguishable at a glance; orders and order_lookup are not.
  • Describe each parameter with an example. "date: ISO 8601 date, e.g. 2026-03-14" prevents a surprising number of format errors.
  • Use enums for closed sets. If status can only be three values, say so in the schema rather than in prose.
  • State the side effects. Mark clearly whether a tool reads, writes, or sends something external. A model deciding between "preview" and "send" needs that difference spelled out.
  • Say what the result looks like. If a tool returns a list capped at 20 items, the description should say so, or the agent will assume the list is complete.

Test selection like any other behavior

Build a small table of realistic user requests and the tool you expect for each, including deliberately ambiguous ones. Run it whenever you add or edit a tool. Two checks are especially informative:

  1. Confusion pairs. For each pair of similar tools, include requests that should go to each. If accuracy drops after you add a new tool, the new description is probably stealing traffic.
  2. Should-use-no-tool cases. Include requests the agent should answer directly. Over-eager tool calling is a failure mode too, and it costs latency and money.

When a case fails, edit the description first, since that is the cheapest fix, and re-run the whole table to make sure you did not shift the problem somewhere else. Only reach for restructuring or merging tools when wording changes stop helping.

The takeaway: the description is part of the tool's contract with the model. Write it for the reader who has to choose, and keep a test table so changes to one tool do not silently reroute traffic from another.

AI AgentsMCP