The description decides which tool the model picks

When an agent has get_customer and lookup_order, the model doesn’t “know” which to use: it decides by reading what each one says. The tool description is the main thing it uses to choose. If it says “Retrieves order details” and nothing else, choosing between similar tools becomes a coin toss.

The five parts of a good description

1. Purpose: what it does and what it returns.
2. Expected inputs: the format of each parameter, for example an order_id shaped like #12345.
3. Example queries: “where is my order #12345?”, “when will yesterday’s purchase arrive?”.
4. Edge cases: a carrier tracking number looks like an ID, but it isn’t one and belongs to track_shipment.
5. Explicit boundaries against its neighbors: “for questions about the customer’s profile, use get_customer”.

Boundaries have to be reciprocal: if lookup_order sends profile questions to get_customer, but get_customer doesn’t say where it ends, it still looks valid for orders.

Data types, error codes or rate limits are API specification: they help you integrate, not choose.

When the description isn’t enough

Symptom	Fix
Single-purpose tool with a poor description	Expand the description
Two near-identical names (analyze_content and analyze_web_content)	Rename the generic one, for example to extract_web_results
One tool does several things (an action parameter, “analyzes and summarizes”)	Split it into purpose-specific tools
One lookup split into four get_order_* tools	Merge them: split by responsibility, not by field
A new tool “returns everything” and breaks the others	Narrow it to what only it provides

A purpose-specific tool has its own input and output contract: analyze_document becomes extract_data_points, summarize_content and verify_claim_against_source. When the functional overlap is in the name, it’s better to remove it at the root than to compensate with a longer description that fights the name.

The system prompt chooses too

The model chooses with the whole context: system prompt, descriptions and message. An instruction like “Always check customer details before proceeding” ties every request to get_customer, and it can silently beat well-written descriptions. If the error persists after improving the descriptions, or shows up only when the message contains a certain word (“account”), look for a competing instruction in the system prompt. If it expresses a real requirement, rewrite it with its exact scope (“verify before changing data”, not “before anything”) instead of deleting it.

The usual traps

As a first step, all of these treat the symptom or are over-engineering:

• adding few-shot examples of tool selection: they cost tokens on every request and the ambiguity remains;
• a keyword router or an upfront classifier;
• forcing tool_choice;
• merging everything into one generic tool with a type parameter, which just moves the ambiguity into the parameter.

In the exam

If the descriptions are one line long, the proportionate first step is to rewrite them with the five parts. If they’re already good, check the name, whether the tool does several things, and the system prompt, in that order.