Tool Interface Design

What You Need to Know

A tool is a function that an agent can call. It has a name and a plain-language description. Tool descriptions are the primary mechanism LLMs use for tool selection. Given a set of tools, the model reads the tool descriptions to decide which tool to call. Tool descriptions are not supplementary metadata. Minimal descriptions, such as "Retrieves customer information", give the model no way to distinguish overlapping tools.

This lesson uses one made-up example throughout: a tailor whose booking agent has two tools. Their descriptions are "Retrieves client information" and "Retrieves alteration details". When the agent is asked whether a hem is ready, it calls the client tool, because both descriptions fit.

What Makes a Good Tool Description

A production-grade tool description includes five elements.

1. What the tool does: its primary purpose, stated unambiguously
2. What inputs it expects: data types, formats, constraints, and required versus optional fields
3. Example queries it handles well: concrete use cases that show the model what the tool is for
4. Edge cases and limitations: what the tool does not do, and what happens when inputs are outside expected ranges
5. Explicit boundaries: when to use this tool versus similar tools in the same toolkit

The tailor's alteration tool would name the ticket number it accepts. It would list "is my hem ready?" as a query.

Minimal (causes misrouting):

get_customer: "Retrieves customer information"
lookup_order: "Retrieves order details"

Production-grade (reliable selection):

get_customer: "Looks up a customer account by email address,
phone number, or customer ID. Returns customer profile
(name, contact details, account status, loyalty tier).
Use this when you need to verify who the customer is.
Do NOT use for order-specific queries — use lookup_order
for those."

lookup_order: "Retrieves order details by order number
(format: #NNNNN) or tracking ID. Returns order status,
items, shipping details, and refund eligibility.
Use this when a customer asks about a specific order.
Do NOT use for customer identity verification —
use get_customer for that."

The second version states explicitly how the tools differ: which identifiers each tool accepts, what each tool returns, and when not to use each tool.

The Misrouting Problem

Two tools with overlapping or near-identical descriptions confuse the model when it selects a tool. Both descriptions fit a request like the hem question, so nothing in the descriptions shows the model which tool is right. Expand both descriptions with the five elements.

Tool Splitting

Generic tools with broad responsibilities create ambiguity, because a broad description fits many requests. Split them into purpose-specific tools with defined input and output contracts, as a tailor might split one garment tool into fittings and alterations.

Before splitting:

analyze_document: "Analyses a document and returns results"

After splitting:

extract_data_points: "Extracts structured data fields
(dates, amounts, names) from a document"

summarize_content: "Produces a concise summary of a
document's key arguments and conclusions"

verify_claim_against_source: "Checks whether a specific
claim is supported by the source document, returning
supporting/contradicting evidence"

Each resulting tool does one narrow, clearly described job the model can match to the user's need.

Tool Renaming for Clarity

When two tools have confusingly similar names, renaming fixes the overlap at the interface level. Rename analyze_content to extract_web_results with a web-specific description, and its purpose becomes unambiguous without touching its implementation. The tailor's tools could become find_client and find_alteration.

System Prompt Interactions

Keyword-sensitive instructions in system prompts can create unintended tool associations that override well-written descriptions. When the system prompt says "always check customer details before proceeding", the model may route any customer-related query to get_customer, whatever the descriptions say. The tailor's "always check client details first" could send hem questions to the client tool. After you update descriptions, reread your system prompt for conflicts. These conflicts are a subtle failure mode.

In the exam

In the exam guide's sample Question 2, get_customer and lookup_order have minimal descriptions, and the agent routes "check my order #12345" to the wrong tool. Pick the correct fix from four plausible options.

• Expand descriptions: correct. It needs low effort, has a large effect, and addresses the root cause directly.
• Few-shot examples: wrong. They add token overhead without fixing why the model is confused. They address the effects and leave the cause in place.
• Routing classifier: wrong. A routing classifier is code that parses the user input before each turn and selects the tool from detected keywords. It is over-engineered as a first step. It bypasses the LLM's natural language understanding and adds infrastructure complexity.
• Tool consolidation: wrong as a first step. It is a valid architectural choice long-term, but it costs far more effort than expanding descriptions.

The exam consistently favours low-effort fixes with a large effect: better descriptions before routing classifiers, scoped access before full access, community servers (servers built by other people) before servers you build yourself. The exam also tests system prompt conflicts.

Exam Traps

Practice Scenario

Build Exercise

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 2, Task Statement 2.1 — Anthropic
• Tool use — Anthropic API Documentation — Anthropic
• Model Context Protocol Specification — Tools — Model Context Protocol
• CCAR-F Exam Guide v1.0: Sample Question 2 — Anthropic