2.1 Design effective tool interfaces with clear descriptions and boundaries

Key points

1. 1

   Tool descriptions are the primary mechanism the model uses to select a tool. Minimal descriptions ("Retrieves customer information" / "Retrieves order details") leave it nothing to choose on, and the exam's preferred first fix for misrouting is to expand the descriptions, not to add few-shot examples, a routing layer or a merged tool.

2. 2

   A strong description covers: what the tool does, when to use it and when not to, the input formats it accepts with example values (ORD-48213377), what it returns and does not return, and an explicit boundary against similar tools ("for goodwill credit with no returned order use issue_store_credit"). Aim for several sentences, more for complex tools.

3. 3

   Overlapping or near-identical descriptions cause misrouting (analyze_content vs analyze_document). Fix by renaming and rewriting so each tool states its input type and purpose, e.g. analyze_content becomes extract_web_results with a web-specific description.

4. 4

   Split generic tools that take a free-text instruction into purpose-specific tools with defined input/output contracts: analyze_document becomes extract_data_points, summarize_content and verify_claim_against_source. This fixes both selection and downstream parsing.

5. 5

   Edge-case guidance belongs in the description: say what to do when a required input is missing ("if the customer has not provided an order ID, use search_orders"). This prevents fabricated parameters before the call is made; strict: true only guarantees schema shape, not that values are real.

6. 6

   System prompt wording can override well-written descriptions. Instructions that reuse a tool name as an ordinary verb ("verify the customer's account", "extract the key facts") create unintended keyword associations. When behaviour changes right after a prompt edit, or an A/B run without the prompt routes correctly, review the prompt for keyword-sensitive wording rather than rewriting descriptions or renaming widely referenced tools.

7. 7

   Use unambiguous parameter names (user_id rather than user) and, for format-sensitive inputs, input_examples on the tool definition. Consolidate related operations (fewer, more capable tools) and namespace by service (jira_search, github_list_prs) as the tool set grows.

8. 8

   Common distractors: adding "MUST" or "IMPORTANT" imperatives instead of clarifying boundaries, shortening descriptions to save tokens, deleting a sibling tool's description, switching to a bigger model, changing temperature, or reordering the tools array (order is not a selection mechanism).

Read the source

• Define tools (best practices, input_examples, tool_choice)
• Writing tools for agents
• Strict tool use