Tool Interface Design

Official Exam Guide Objectives

Task 2.1: Design effective tool interfaces with clear descriptions and boundaries.

Knowledge of

• Tool descriptions as the primary mechanism LLMs use for tool selection; minimal descriptions lead to unreliable selection among similar tools
• The importance of including input formats, example queries, edge cases, and boundary explanations in tool descriptions
• How ambiguous or overlapping tool descriptions cause misrouting (e.g., analyze_content vs analyze_document with near-identical descriptions)
• The impact of system prompt wording on tool selection: keyword-sensitive instructions can create unintended tool associations

Skills in

• Writing tool descriptions that clearly differentiate each tool's purpose, expected inputs, outputs, and when to use it versus similar alternatives
• Renaming tools and updating descriptions to eliminate functional overlap (e.g., renaming analyze_content to extract_web_results with a web-specific description)
• Splitting generic tools into purpose-specific tools with defined input/output contracts (e.g., splitting a generic analyze_document into extract_data_points, summarize_content, and verify_claim_against_source)
• Reviewing system prompts for keyword-sensitive instructions that might override well-written tool descriptions

What You Need to Know

Tool descriptions are the PRIMARY mechanism LLMs use for tool selection. Not supplementary metadata. Not an afterthought. The mechanism. A model handed a toolkit reads the descriptions and decides from them — so where two tools are described in terms that could apply to either, there is nothing else for it to go on and the selection becomes a guess.

What Makes a Good Tool Description

A production-grade tool description includes five elements:

1. What the tool does — the purpose, stated so it could not be mistaken for another tool's
2. What inputs it expects — types, formats, permitted ranges, and which fields are required rather than optional
3. Example queries it handles well — concrete cases that show the model what a good match looks like
4. Edge cases and limitations — what it will not do, and how it behaves when given something outside its range
5. Explicit boundaries — the conditions under which a neighbouring tool is the right call instead

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

Minimal (causes misrouting):

get_customer: "Gets customer info" lookup_order: "Gets order info"

Production-grade (reliable selection):

get_customer: "Finds one customer account, given an email address, a phone number or a customer ID. Returns the profile: name, contact details, account status and loyalty tier. Reach for this when the question is who you are dealing with. Anything about a particular order belongs to lookup_order, not here."

lookup_order: "Returns one order, given an order number (format: #NNNNN) or a tracking ID. Covers current status, the items on it, shipping detail and whether it is eligible for a refund. Reach for this when the customer names an order. Establishing who the customer is belongs to get_customer, not here."

Read the second pair as a decision procedure rather than documentation. Each entry states which identifiers it accepts, what comes back, and — the part that does the real work — the circumstances under which the other tool is the correct choice. There is no case where both look equally applicable.

The Misrouting Problem

Descriptions that overlap produce selection that wavers. Q2 in the sample set builds on exactly this: get_customer and lookup_order described in one line each, and an agent sending "check my order #12345" to the wrong one.

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

• Expand descriptions — correct. It acts on the thing that actually decides selection, and costs an afternoon of writing.
• Few-shot examples — wrong. Examples demonstrate the right choice case by case while leaving the descriptions just as ambiguous, so the confusion persists everywhere the examples do not reach.
• Routing classifier — wrong. It builds infrastructure to make a decision the model is already equipped to make, and sets aside the language understanding you are paying for.
• Tool consolidation — wrong as a first step. Merging tools is a legitimate architectural move, but it is a redesign, and a redesign is not the proportionate answer to a description that needed two more sentences.

A pattern runs through these, and it is worth carrying into other items: 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

A tool with a broad remit cannot be described precisely, because there is no single thing it does. Splitting it into purpose-specific tools gives each one a description that can be exact.

Before splitting:

analyze_document: "Runs analysis over a document and returns what it finds"

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 of the three now maps onto a request a user might actually make, which is what allows the model to choose between them on the strength of what was asked.

Tool Renaming for Clarity

Where two names invite confusion, renaming resolves it at the interface without touching anything underneath. Turn analyze_content into extract_web_results, give the description a web-specific framing, and the tool stops competing for requests that were never meant for it — no implementation change involved.

System Prompt Interactions

A system prompt can quietly overrule descriptions you have just spent time on. An instruction like "always check customer details before proceeding" plants a keyword association strong enough to pull customer-adjacent requests toward get_customer, whatever the tool entries say about boundaries.

So the description work is not finished until you have reread the system prompt for phrasing that competes with it. The failure is subtle, because both halves look correct in isolation, and the exam tests it.

Deep Dive

The tool definition contract in the Messages API

A client tool in the tools array is defined by a small, fixed set of fields:

Anthropic's own ranking of these is unambiguous: "Provide extremely detailed descriptions. This is by far the most important factor in tool performance." Note also that passing tools at all causes the API to insert a special tool-use system prompt automatically — tools are never free, which is why a tool that earns its place must be described well enough to be chosen correctly.

{
  "name": "lookup_order",
  "description": "Retrieves order details by order number (format: #NNNNN) or tracking ID…",
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  }
}

Sourceplatform.claude.com › define-toolsfetched 2026-07-30

The MCP tool definition adds an output contract

An MCP tool definition carries name (unique identifier), description (human-readable description of functionality), and inputSchema (JSON Schema defining expected parameters), plus optional title, outputSchema (JSON Schema defining the expected output structure), and annotations ("optional properties describing tool behavior"). Where the Messages API constrains only the input, MCP lets you pin the output too. Annotations are the slot for behavioural metadata, but treat them as advisory: the spec warns that "clients MUST consider tool annotations to be untrusted unless they come from trusted servers."

MCP's design guidance mirrors the splitting advice in this lesson: "Each tool performs a single operation with clearly defined inputs and outputs." Clients discover tools with tools/list and execute them with tools/call.

Sourcesmodelcontextprotocol.io › toolsmodelcontextprotocol.io › server-conceptsfetched 2026-07-30

The description has a hard budget in Claude Code

Claude Code truncates tool descriptions and server instructions at 2KB each. That is a real ceiling on "just write a longer description": keep them concise to avoid truncation, and put critical details near the start. A boundary statement buried in the fifth paragraph may simply never reach the model.

Tool search compounds this. It is enabled by default: MCP tool definitions are deferred rather than loaded into context upfront, Claude uses a search tool to discover relevant ones, and only the tools it actually uses enter context. Because the search is driven by text, server authors are told to write server instructions that explain what category of tasks the tools handle, when Claude should search for them, and the key capabilities the server provides.

Sourcecode.claude.com › mcpfetched 2026-07-30

Consolidate workflows; do not wrap endpoints; namespace what remains

Anthropic's tool-writing guidance identifies the default failure: "A common error we've observed is tools that merely wrap existing software functionality or API endpoints." The recommended shape is a small set of workflow tools:

• Instead of list_users, list_events and create_event, build schedule_event, which finds availability and schedules in one call.
• Instead of get_customer_by_id, list_transactions and list_notes, build get_customer_context, which compiles the relevant information at once.
• Instead of read_logs, build search_logs, returning only relevant lines plus surrounding context.
• The same logic drives the address-book example: search_contacts or message_contact beats paging through list_contacts, because reading an address book page by page is brute-force search.

"More tools don't always lead to better outcomes"; the advice is to "build a few thoughtful tools targeting specific high-impact workflows … and scale up from there". Where several tools genuinely must coexist, namespacing delineates them: by service (asana_search, jira_search) and by resource (asana_projects_search, asana_users_search). Anthropic found "selecting between prefix- and suffix-based namespacing to have non-trivial effects on our tool-use evaluations", so it is worth testing rather than assuming. Namespacing also reduces the number of tool descriptions loaded into context and "offloads agentic computation from the agent's context back into the tool calls themselves".

Sourceanthropic.com › writing-tools-for-agentsfetched 2026-07-30

What a good description actually contains

Two independent Anthropic sources converge on the same checklist. From the tool-design guidance: "A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools," and tool definitions "should be given just as much prompt engineering attention as your overall prompts." The test to apply is empathy: "Put yourself in the model's shoes. Is it obvious how to use this tool, based on the description and parameters, or would you need to think carefully about it? If so, then it's probably also true for the model."

From the tool-writing guidance: write it as you would describe the tool to a new hire — make the implicit context explicit (specialised query formats, definitions of niche terminology, relationships between underlying resources) and enforce expected inputs and outputs with strict data models. Two concrete mistake-proofing moves:

• Name parameters unambiguously — user_id, not user.
• Make the schema prevent the mistake. (From the agent-building guidance.) Anthropic "changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly" — the relative-path errors disappeared because the interface made them impossible.

Sourcesanthropic.com › building-effective-agentsanthropic.com › writing-tools-for-agentsfetched 2026-07-30

Descriptions are measurable, so iterate on them with evals

Description quality is not a matter of taste — it shows up in numbers.

• Claude Sonnet 3.5 reached state of the art on SWE-bench Verified "after we made precise refinements to tool descriptions, dramatically reducing error rates and improving task completion".
• An agent that tested flawed tools and rewrote their descriptions produced "a 40% decrease in task completion time for future agents using the new description".
• "Even small refinements to tool descriptions can yield dramatic improvements."
• The diagnostic signal runs the other way too: "lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples", and lots of redundant calls suggests pagination or token-limit parameters need rightsizing.

A real bug from this process: on launch, Claude was needlessly appending 2025 to the web search tool's query parameter, biasing results — fixed by improving the tool description, not by changing the model or adding a router.

Sourcesanthropic.com › writing-tools-for-agentsanthropic.com › multi-agent-research-systemfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Design Tool Descriptions That Eliminate Misrouting

Difficulty: Beginner (1/4)

30 minutes

1. Create two MCP tools with intentionally ambiguous descriptions (e.g. get_customer: Retrieves customer information and lookup_order: Retrieves order details)

Why: Reproducing a misrouting scenario first-hand builds intuition for why minimal descriptions fail. The exam tests your ability to identify ambiguous descriptions as the root cause of tool selection errors.

You should see: Two tool definitions registered with your MCP server, each having a single-sentence description that does not mention input formats, example queries, or boundaries.

2. Test with 10 queries covering different user intents and log which tool the model selects for each

Why: Quantifying selection accuracy before and after description changes gives you concrete evidence of the impact. The exam expects you to know that description quality directly affects selection reliability.

You should see: A log showing at least 2-3 misrouted queries where the model selected get_customer for order-related queries or vice versa, demonstrating the ambiguity problem.

3. Rewrite both descriptions to include: purpose, expected inputs with formats, example queries, edge cases, and explicit boundaries against the other tool

Why: This is the core exam skill — the lowest-effort, highest-leverage fix for misrouting. Production-grade descriptions include all five elements: purpose, inputs, examples, edge cases, and boundaries.

You should see: Each tool description is 3-5 sentences long, explicitly states accepted identifier formats, gives example queries, and includes a boundary statement like "Do NOT use for order-specific queries — use lookup_order for those."

4. Re-run the same 10 queries and compare selection accuracy before and after

Why: Measuring improvement validates that description quality is the root cause. The exam expects you to understand that better descriptions produce measurably better selection without any architectural changes.

You should see: Selection accuracy improves to 9/10 or 10/10 correct, with previously misrouted queries now hitting the correct tool. A clear before/after comparison showing the improvement.

5. Review your system prompt for keyword-sensitive instructions that could override the improved descriptions

Why: System prompt conflicts are a subtle failure mode the exam tests. Keywords like "always check customer details" can create unintended tool associations that override even well-written descriptions.

You should see: A list of any keyword-sensitive phrases in your system prompt that could trigger incorrect tool associations, along with rewritten versions that avoid the conflict.

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

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create two MCP tools with intentionally ambiguous descriptions (e.g. get_customer: Retrieves customer information and lookup_order: Retrieves order details)

Why: Reproducing a misrouting scenario first-hand builds intuition for why minimal descriptions fail. The exam tests your ability to identify ambiguous descriptions as the root cause of tool selection errors.

You should see: Two tool definitions registered with your MCP server, each having a single-sentence description that does not mention input formats, example queries, or boundaries.

import { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";

const server = new McpServer({ name: "customer-tools", version: "1.0.0" });

server.registerTool(
  "get_customer",
  {
    description: "Retrieves customer information",
    inputSchema: z.object({ identifier: z.string() }),
  },
  async ({ identifier }) => ({
    content: [{ type: "text", text: `Customer data for ${identifier}` }],
  })
);

server.registerTool(
  "lookup_order",
  {
    description: "Retrieves order details",
    inputSchema: z.object({ identifier: z.string() }),
  },
  async ({ identifier }) => ({
    content: [{ type: "text", text: `Order data for ${identifier}` }],
  })
);

from mcp.server import MCPServer

mcp = MCPServer("customer-tools")


# The docstring becomes the tool description — which is exactly the problem
# this step is staging: one generic sentence, no inputs, no boundaries.
@mcp.tool()
def get_customer(identifier: str) -> str:
    """Retrieves customer information"""
    return f"Customer data for {identifier}"


@mcp.tool()
def lookup_order(identifier: str) -> str:
    """Retrieves order details"""
    return f"Order data for {identifier}"

Step 2. Test with 10 queries covering different user intents and log which tool the model selects for each

Why: Quantifying selection accuracy before and after description changes gives you concrete evidence of the impact. The exam expects you to know that description quality directly affects selection reliability.

You should see: A log showing at least 2-3 misrouted queries where the model selected get_customer for order-related queries or vice versa, demonstrating the ambiguity problem.

const queries = [
  "What is the status of order #12345?",
  "Look up customer john@example.com",
  "Check my order tracking",
  "Find the account for phone 555-0123",
  "Where is my package?",
  "Is order #67890 eligible for a refund?",
  "What loyalty tier is this customer?",
  "I need details on order #11111",
  "Verify the customer account status",
  "When will order #99999 arrive?"
];
for (const query of queries) {
  const response = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    tools: toolDefinitions,
    messages: [{ role: "user", content: query }]
  });
  const toolUse = response.content.find(b => b.type === "tool_use");
  console.log(`Query: ${query} => Tool: ${toolUse?.name}`);
}

queries = [
    "What is the status of order #12345?",
    "Look up customer john@example.com",
    "Check my order tracking",
    "Find the account for phone 555-0123",
    "Where is my package?",
    "Is order #67890 eligible for a refund?",
    "What loyalty tier is this customer?",
    "I need details on order #11111",
    "Verify the customer account status",
    "When will order #99999 arrive?",
]

for query in queries:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tool_definitions,
        messages=[{"role": "user", "content": query}],
    )
    tool_use = next((b for b in response.content if b.type == "tool_use"), None)
    print(f"Query: {query} => Tool: {tool_use.name if tool_use else None}")

Step 3. Rewrite both descriptions to include: purpose, expected inputs with formats, example queries, edge cases, and explicit boundaries against the other tool

Why: This is the core exam skill — the lowest-effort, highest-leverage fix for misrouting. Production-grade descriptions include all five elements: purpose, inputs, examples, edge cases, and boundaries.

You should see: Each tool description is 3-5 sentences long, explicitly states accepted identifier formats, gives example queries, and includes a boundary statement like "Do NOT use for order-specific queries — use lookup_order for those."

server.registerTool(
  "get_customer",
  {
    description:
      "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 or check account details. " +
      "Do NOT use for order-specific queries — use lookup_order for those.",
    inputSchema: z.object({
      identifier: z.string().describe("Customer email, phone, or ID"),
    }),
  },
  async ({ identifier }) => ({
    content: [{ type: "text", text: `Customer profile for ${identifier}` }],
  })
);

@mcp.tool()
def get_customer(identifier: str) -> str:
    """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 or check account
    details. Do NOT use for order-specific queries — use lookup_order for those.

    Args:
        identifier: Customer email, phone, or ID
    """
    return f"Customer profile for {identifier}"

Step 4. Re-run the same 10 queries and compare selection accuracy before and after

Why: Measuring improvement validates that description quality is the root cause. The exam expects you to understand that better descriptions produce measurably better selection without any architectural changes.

You should see: Selection accuracy improves to 9/10 or 10/10 correct, with previously misrouted queries now hitting the correct tool. A clear before/after comparison showing the improvement.

let correct = 0;
const expected = ["lookup_order", "get_customer", "lookup_order", "get_customer", "lookup_order", "lookup_order", "get_customer", "lookup_order", "get_customer", "lookup_order"];
for (let i = 0; i < queries.length; i++) {
  const response = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, tools: updatedToolDefinitions, messages: [{ role: "user", content: queries[i] }] });
  const toolUse = response.content.find(b => b.type === "tool_use");
  const match = toolUse?.name === expected[i];
  if (match) correct++;
  console.log(`${match ? "CORRECT" : "WRONG"} | ${queries[i]} => ${toolUse?.name} (expected: ${expected[i]})`);
}
console.log(`Accuracy: ${correct}/${queries.length}`);

correct = 0
expected = [
    "lookup_order", "get_customer", "lookup_order", "get_customer", "lookup_order",
    "lookup_order", "get_customer", "lookup_order", "get_customer", "lookup_order",
]

for query, want in zip(queries, expected):
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=updated_tool_definitions,
        messages=[{"role": "user", "content": query}],
    )
    tool_use = next((b for b in response.content if b.type == "tool_use"), None)
    got = tool_use.name if tool_use else None
    match = got == want
    correct += match
    print(f"{'CORRECT' if match else 'WRONG'} | {query} => {got} (expected: {want})")

print(f"Accuracy: {correct}/{len(queries)}")

Step 5. Review your system prompt for keyword-sensitive instructions that could override the improved descriptions

Why: System prompt conflicts are a subtle failure mode the exam tests. Keywords like "always check customer details" can create unintended tool associations that override even well-written descriptions.

You should see: A list of any keyword-sensitive phrases in your system prompt that could trigger incorrect tool associations, along with rewritten versions that avoid the conflict.

// Test with a system prompt that contains a conflicting instruction
const conflictingPrompt = "Always check customer details before proceeding with any request.";
const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  system: conflictingPrompt,
  tools: updatedToolDefinitions,
  messages: [{ role: "user", content: "What is the status of order #12345?" }]
});
// If get_customer is selected instead of lookup_order, the system prompt is interfering

# Test with a system prompt that contains a conflicting instruction
conflicting_prompt = "Always check customer details before proceeding with any request."

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=conflicting_prompt,
    tools=updated_tool_definitions,
    messages=[{"role": "user", "content": "What is the status of order #12345?"}],
)
# If get_customer is selected instead of lookup_order, the system prompt is interfering

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the code you actually wrote.