Skip to main content

2.1 Tool interfaces with clear descriptions and boundaries

The single most-tested fact in this domain

Tool descriptions are the primary mechanism an LLM uses for tool selection. When descriptions are minimal, the model has nothing to differentiate similar tools with — so it misroutes. The first fix for unreliable selection is better descriptions, not a routing layer, not few-shot examples, not consolidation.

What a good description contains​

ElementWhy
PurposeWhat the tool is for, in one line
Input formats it acceptsorder_id as #12345 or 12345; email or customer ID
Example queriesAnchors the match between user phrasing and this tool
Edge casesEmpty results, multiple matches, partial data
Boundary explanation"Use this instead of X when…" — the differentiator
OutputsWhat comes back, so the model can plan the next step
{
"name": "lookup_order",
"description": "Retrieves details for a SINGLE order: line items, quantities, prices, fulfilment status, carrier tracking, and return eligibility. Accepts an order number with or without the leading '#' (e.g. '#12345' or '12345'). Example queries: 'where is order 12345', 'what did I buy on order #987'. Returns an empty result (not an error) when the order number does not exist. Use lookup_order when the user references an order. Use get_customer instead when the user references themselves, an email address, or an account, or when you need a verified customer_id before an order operation.",
"input_schema": {
"type": "object",
"properties": { "order_id": { "type": "string" } },
"required": ["order_id"],
"additionalProperties": false
}
}

Overlapping descriptions cause misrouting​

analyze_content and analyze_document with near-identical descriptions is the canonical failure. Two fixes:

  1. Rename and re-describe to remove overlap — analyze_content → extract_web_results with a web-specific description.
  2. Split a generic tool into purpose-specific tools with defined input/output contracts — analyze_document → extract_data_points, summarize_content, verify_claim_against_source.

System prompt wording overrides descriptions​

Tool selection is keyword-sensitive. A system prompt saying "always analyze the customer's content before responding" creates an unintended association with a tool named analyze_content, even when a better-described tool exists. Review system prompts for keyword-sensitive instructions that might override well-written descriptions.

Quiz​

  1. Question 1

    Production logs show the agent frequently calls get_customer when users ask about orders (e.g. "check my order #12345") instead of lookup_order. Both tools have minimal descriptions ("Retrieves customer information" / "Retrieves order details") and accept similar identifier formats. What is the most effective first step to improve tool selection reliability?

  2. Question 2

    Your system exposes analyze_content ("Analyzes content and returns key points") and analyze_document ("Analyzes a document and returns key points"). Traces show web search results going to analyze_document about a third of the time and PDFs going to analyze_content nearly as often. Both tools accept a text blob. What is the most direct fix?

  3. Question 3

    After you added the line "Always verify claims against primary sources before reporting" to the system prompt, the agent began calling verify_claim_against_source on every intermediate note, roughly tripling tool calls and adding 40 seconds per task. The tool descriptions were not touched and were already precise about scope. Where does the problem sit?

  4. Question 4

    A single manage_account tool takes an action string — update_address, close, add_payment_method, change_plan and six others — plus a free-form payload. The agent picks the wrong action about 8% of the time and regularly pairs a correct action with a payload shaped for a different one. The description is 40 lines and grows with every new action. What is the right correction?