Tool interfaces with clear descriptions and boundaries

Descriptions guide tool selection

A tool description is the primary mechanism the model uses to select a tool. It is not documentation for humans that the model happens to see — it is the input to the routing decision.

Minimal descriptions make selection less reliable, especially among tools with similar purposes. Two tools described as "Retrieves customer information" and "Retrieves order details" give the model almost nothing to choose on when a request mentions both a customer and an order.

What to include in a description

• what the tool is for, and what it is not for
• input formats it accepts
• example queries
• edge cases
• when to use it versus a similar alternative

The comparison with similar tools is important. A description should explain when to choose this tool instead of another tool with a related purpose.

Two entries in the course catalog, Introduction to Statistics and Statistical Methods, each described accurately and neither telling you which one you should take. The line that settles it is the one comparing them: take this one if you haven't done calculus.

A tool definition is a name, a description, and an input schema. The description is the field selection actually runs on:

{
  "name": "extract_data_points",
  "description": "Pulls named fields out of a document into a record. Use this when the caller needs specific values. Use summarize_content instead when the caller needs the gist.",
  "input_schema": {
    "type": "object",
    "properties": { "document_id": { "type": "string" } },
    "required": ["document_id"]
  }
}

The sentence that compares the two tools gives the model a clear selection rule.

Input formats deserve the same care, for a different reason. An underspecified parameter rarely fails loudly: 3/4/25 is a valid date in two calendars, so the call succeeds against the wrong month and reports nothing. State the accepted format in the parameter's own description and show one example of it.

"deliveredAfter": {
  "type": "string",
  "description": "ISO 8601 date, YYYY-MM-DD. Example: 2025-03-04. Slash-separated dates are rejected, because 3/4/25 is ambiguous."
}

The format rule lets the tool reject an ambiguous date instead of searching the wrong date range.

Rename tools with overlapping purposes

analyze_content and analyze_document with near-identical descriptions will misroute no matter how the model is prompted. The fix is at the interface: rename and re-scope. analyze_content becomes extract_web_results with a web-specific description, and the overlap disappears because the tools are now about different things.

Splitting generic tools

A tool named analyze_document that does several unrelated jobs invites the model to reach for it whenever a document is involved.

Split it into purpose-specific tools with defined input and output contracts: extract_data_points, summarize_content, verify_claim_against_source. Each has an unambiguous trigger, and none competes with the others.

Split only when the jobs differ. When the job is the same and only the target changes — one search run against nine corpora — nine near-identical descriptions compete for every request. That belongs in one tool with an enumerated parameter, each accepted value described, so the difference is stated once.

Check the system prompt too

A well-written tool description can be overridden by keyword-sensitive wording in the system prompt. A sentence like "when the user asks to analyze anything, be thorough" can create an unintended association with whatever tool has "analyze" in its name.

When routing misbehaves, the system prompt is the second place to look.

The dependence runs one way. A boundary written into the description travels with the tool, so every agent given that tool reads it. The same boundary stated in a system prompt holds for that one agent and disappears the moment the tool is handed to another.