2.1 Tool Interface Design

What You Need to Know

Tool descriptions are the PRIMARY mechanism LLMs use for tool selection. Not supplementary metadata. Not an afterthought. The mechanism. When a model receives a set of tools, it reads the descriptions to decide which one to call — and if those descriptions are minimal, something like “Retrieves customer information”, it has no way to tell apart tools that serve overlapping purposes.

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 anchor the model’s understanding
4. Edge cases and limitations — what the tool does NOT do, and what happens when inputs fall outside expected ranges
5. Explicit boundaries — when to use THIS tool versus similar tools in the same toolkit

Here is the difference between a minimal and a production-grade description:

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 gives the model explicit disambiguation. It knows which identifiers each tool accepts, what each returns, and crucially, when NOT to use each tool.

The Misrouting Problem

Two tools with overlapping or near-identical descriptions cause selection confusion. The exam guide’s sample Question 2 presents exactly this scenario: get_customer and lookup_order with minimal descriptions, causing the agent to route “check my order #12345” to the wrong tool.

The exam tests whether you can spot the correct fix. Four plausible options, three of them wrong:

• Expand descriptions — correct. Low effort, high leverage, directly addresses the root cause.
• Few-shot examples — wrong. Adds token overhead without fixing why the model is confused. You’re treating symptoms, not the disease.
• Routing classifier — wrong. Over-engineered as a first step. Bypasses the LLM’s natural language understanding and adds infrastructure complexity.
• Tool consolidation — wrong as a first step. It’s a valid architectural choice long-term, but it costs far more effort than expanding descriptions.

The exam consistently favours low-effort, high-leverage fixes. Better descriptions before routing classifiers. Scoped access before full access. Community servers before custom builds.

Tool Splitting

Generic tools with broad responsibilities create ambiguity. The fix: split them into purpose-specific tools with defined input/output contracts.

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 pick the right one based on what the user actually needs.

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, give it a web-specific description, and the tool’s purpose becomes unambiguous — without touching its implementation.

System Prompt Interactions

Keyword-sensitive instructions in system prompts can create unintended tool associations that override well-written descriptions. If your system prompt says “always check customer details before proceeding”, the model may route any customer-related query to get_customer no matter what the descriptions say.

So after updating tool descriptions, reread your system prompt for conflicts. It’s a subtle failure mode, and the exam tests it.

Key Concept

Tool descriptions are the primary mechanism LLMs use for tool selection. When misrouting is caused by weak descriptions, improving them is the first fix — not few-shot examples, routing classifiers, or tool consolidation.

Read the condition on that, because the exam tests both halves. Descriptions are the fix when the agent has a workable number of tools and simply cannot tell two of them apart. They are not the fix when the toolkit itself is the problem: past roughly 4-5 tools per agent, selection degrades on decision complexity alone, and rewriting 22 descriptions leaves that untouched. Diagnose which one you are looking at before reaching for a remedy. Task Statement 2.3 covers the overload threshold and what to do instead.

Exam Traps

Exam trap

Choosing few-shot examples to fix tool misrouting caused by minimal descriptions

Few-shot examples add token overhead without addressing the root cause. The model is confused because descriptions do not differentiate the tools — fix the descriptions first.

Exam trap

Implementing a routing classifier as the first step to fix tool selection

A routing classifier is over-engineered as a first response. It bypasses the LLM’s natural language understanding and adds infrastructure the exam does not consider proportionate.

Exam trap

Consolidating similar tools into one as the first step

Tool consolidation is a valid long-term architectural choice, but it requires more effort than expanding descriptions. The exam favours low-effort, high-leverage first steps.

Exam trap

Ignoring system prompt wording after updating tool descriptions

Keyword-sensitive instructions in system prompts can silently override well-written tool descriptions, creating unintended tool associations.

Practice Scenario

Production logs show an agent frequently calls get_customer when users ask about orders (e.g. ‘check my order #12345’), instead of calling 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?

• A. Add 5-8 few-shot examples to the system prompt demonstrating correct tool selection patterns for order-related queries.
• B. Expand each tool description to include input formats, example queries, edge cases, and boundaries explaining when to use it versus similar tools.
• C. Implement a routing layer that parses user input before each turn and pre-selects the appropriate tool based on detected keywords.
• D. Consolidate both tools into a single lookup_entity tool that accepts any identifier and internally determines which backend to query.

Answer & explanation

Correct: B

• A — Few-shot examples add token overhead without fixing the underlying issue. The root cause is that descriptions do not differentiate the tools — fix the descriptions first.
• B — Tool descriptions are the primary mechanism LLMs use for tool selection. Expanding them is the lowest-effort, highest-leverage fix that directly addresses the root cause of misrouting.
• C — A routing layer is over-engineered as a first step. It bypasses the LLM’s natural language understanding and adds unnecessary infrastructure complexity.
• D — Consolidation is a valid architectural choice but requires significantly more effort than expanding descriptions. The exam favours proportionate first steps.

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

Exam Simulator

Five exam-style multiple-choice questions on Tool Interface Design. Pick an answer, then open the explanation.

Question 1

Production logs show an agent frequently calls get_customer when users ask about orders (e.g., “check my order #12345”), instead of calling 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?

• A. Add 5-8 few-shot examples to the system prompt covering order-shaped queries.
• B. Add a routing layer that parses each user turn and pre-selects a tool from keywords.
• C. Consolidate both into a single lookup_entity tool that accepts any identifier and internally determines which backend to query.
• D. Expand both descriptions to cover input formats, example queries, edge cases, and explicit boundaries.

Answer & explanation

Correct: D

• D is correct because tool descriptions are the primary mechanism LLMs use for tool selection. Expanding them is the lowest-effort, highest-leverage fix, and it addresses the root cause directly, because neither description currently says what its tool is for or when to prefer the other one.
• A is wrong because few-shot examples add token overhead to every request while leaving the ambiguity in place. They compensate for descriptions that still fail to differentiate the tools.
• B is wrong because a routing layer is over-engineered as a first step. It bypasses the model’s own language understanding and adds infrastructure that must be maintained as the tool set changes.
• C is wrong because consolidation is a legitimate architectural choice but a far larger change than rewriting two descriptions. The exam favours proportionate first steps.

Question 2

A tool named analyse_document has the description “Analyses a document and returns results.” Users report that the agent sometimes extracts data when they want a summary, and vice versa. What is the best approach?

• A. Split it into purpose-specific tools, each with a narrow description and its own input/output contract.
• B. Add few-shot examples that show when to extract data points and when to summarise instead.
• C. Rename it extract_and_summarise_document so both operations are visible in the name.
• D. Add a pre-processing step that classifies intent first.

Answer & explanation

Correct: A

• A is correct because a generic tool with broad responsibilities forces the model to guess which operation the user wants. Splitting it into extract_data_points, summarise_content and verify_claim_against_source gives the model narrow options with defined input/output contracts.
• B is wrong because few-shot examples treat the symptom. The root problem is one tool carrying several responsibilities, and no number of examples removes that ambiguity.
• C is wrong because the name now lists both operations but the tool still performs both, so the model must still infer which one is wanted on any given call.
• D is wrong because a pre-processing step is over-engineered. The fix belongs at the tool interface, not in an external routing layer.

Question 3

After improving tool descriptions for get_customer and lookup_order, a developer notices that order-related queries still sometimes route to get_customer. The system prompt contains: “Always check customer details before proceeding with any request.” What is the likely cause?

• A. The descriptions need more detail still, so that they outweigh the instruction sitting in the system prompt.
• B. A keyword-sensitive system prompt instruction is creating a competing association on every turn.
• C. The model has cached the earlier descriptions and needs a context reset.
• D. The two tool names remain too similar to each other, and both of them should be renamed for clarity.

Answer & explanation

Correct: B

• B is correct because keyword-sensitive instructions in a system prompt can silently override well-written tool descriptions. “Always check customer details before proceeding with any request” associates every request with get_customer, and it is weighed alongside the descriptions rather than beneath them.
• A is wrong because description quality is no longer the constraint; the descriptions were already improved. Adding further detail does not remove a competing instruction.
• C is wrong because tool descriptions are not cached between API calls. Each request is evaluated against the definitions sent with it.
• D is wrong because get_customer and lookup_order are already distinct names. The remaining misrouting traces to the system prompt, not to the names.

Question 4

Two tools have confusingly similar names: analyse_content and analyse_web_content. Both handle web data. What is the most effective fix?

• A. Add detailed descriptions to both tools, setting out how their scopes differ from one another and which to prefer.
• B. Merge both into a single analyse_all_content tool that handles every type.
• C. Rename analyse_content to extract_web_results and give it a description scoped to web results.
• D. Add a routing classifier that picks between the two tools by inspecting the input content first.

Answer & explanation

Correct: C

• C is correct because the overlap sits at the interface, not in the implementation. Renaming to extract_web_results with a specific description makes the tool’s purpose unambiguous without changing what it does.
• A is wrong because when two names are confusingly similar, the descriptions have to work against the names themselves. Ambiguity the name creates is better removed than compensated for.
• B is wrong because merging recreates the generic-tool problem: one tool carrying several responsibilities.
• D is wrong because a routing classifier is over-engineered when a rename resolves the ambiguity outright.

Question 5

A production-grade tool description should include which five elements?

• A. Purpose, expected inputs, example queries, edge cases, and explicit boundaries against similar tools.
• B. Name, version, author, licence, and dependencies.
• C. Endpoint URL, authentication method, rate limits, response schema, and the documented error codes it can return.
• D. Function signature, return type, unit test coverage, a documentation link, and the full release changelog.

Answer & explanation

Correct: A

• A is correct because these five give the model enough context to differentiate one tool from another: what it is for, what it accepts (with formats and constraints), what queries suit it, where it stops, and when a neighbouring tool is the better call.
• B is wrong because these are package metadata fields. None of them tells the model what the tool is for or when to select it.
• C is wrong because these are API specification fields. Inputs partly overlap, but the set omits example queries and boundaries, which are the two that drive selection between similar tools.
• D is wrong because these are software documentation fields aimed at maintainers, not selection signals aimed at the model.