Tool Design & MCP Integration — Complete Lesson

The Core Concept

When Claude encounters multiple tools, it has no access to their source code or runtime behavior — only the description text you provide. That description is re-evaluated on every single tool call, making it the most leveraged piece of configuration in your agent design.

The problem compounds with overlapping capabilities. When two tools could plausibly answer the same request, the model falls back to heuristics — and those heuristics are not predictable across invocations.

Knowledge the Exam Tests

Anatomy of a Production Tool Description

A complete tool description has five required components. Missing any one of them degrades routing reliability.

{
  "name": "search_customer_orders",
  "description": """
  Search for a customer's order history by customer ID or email.

  Use this tool when:
  - User asks about their orders, deliveries, or purchases
  - You need order IDs before calling process_refund
  - User references a specific order number

  Do NOT use this tool for:
  - Checking inventory (use check_inventory instead)
  - Looking up product descriptions (use get_product_details)

  Input formats accepted:
  - customer_id: "cust_12345" or integer 12345
  - email: full address, case-insensitive

  Returns: List of orders with order_id, status, total, items[], created_at

  Edge cases:
  - Returns empty list if customer has no orders (not an error)
  - If both customer_id and email provided, customer_id takes precedence
  """,
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string", "description": "e.g. 'cust_12345'" },
      "email":       { "type": "string", "description": "Customer email address" }
    }
  }
}

Weak vs Strong Descriptions

The exam frequently presents minimal descriptions and asks what's wrong, or asks which description causes misrouting. Internalize this contrast.

The Split Pattern

Generic tools that accept a mode parameter are a routing antipattern. The model must guess the correct mode from within a single tool call — the same disambiguation problem that descriptions are supposed to solve, now embedded deeper inside.

System Prompt Interference

This is the least obvious knowledge point in 2.1 and therefore high-probability on the exam. Keyword-sensitive instructions in the system prompt can fire on partial matches and override tool selection logic.

// System prompt instruction:
"When users ask about orders, prioritize the order tool."

// Tools available:
search_orders      — "Search customer order history"
process_refund     — "Process refunds for order items"
lookup_invoice     — "Retrieve invoice for order billing"

// User: "I need my order invoice for tax purposes"
// Expected: lookup_invoice
// Actual:   search_orders (keyword "order" fires the instruction)

The fix: rewrite the system prompt to use specific, unambiguous criteria. "When users ask about order status or tracking, use search_orders." Specificity in the system prompt is as important as specificity in descriptions.

Exam Traps for Task 2.1

🔨 Implementation Task

Exam Simulation — Task 2.1

The Core Concept

When an MCP tool fails, the agent must decide: retry with same inputs? retry with modified inputs? try an alternative? escalate to the coordinator? inform the user? Every one of those decisions requires knowing what kind of failure happened and whether retrying makes sense.

A generic status string like "error": "Operation failed" forces the agent to guess — or worse, to blindly retry a non-retryable failure in an infinite loop. Structured error responses hand the coordinator the data it needs to route appropriately.

Error Categories

The exam tests knowledge of these four distinct error types and their recovery implications. Confusing transient with validation errors — or failing to mark business errors as non-retryable — are the primary failure modes.

The Required Error Schema

The exam tests both the field names and what each field enables. Know all four fields and why each one exists.

{
  "isError": true,                          // MCP isError flag — signals failure to agent
  "errorCategory": "transient",             // transient | validation | permission | business
  "isRetryable": true,                     // drives coordinator retry decision
  "message": "Order service timed out. Retry is safe.",
  "attemptedQuery": "order_id: ORD-8821",  // what was tried (for coordinator context)
  "partialResults": null                    // any partial data recovered before failure
}

Recovery Strategy

The exam tests the layered recovery pattern: subagents handle what they can locally, and only propagate what they can't resolve — along with everything the coordinator needs to make a good decision.

• For transient errors: subagent implements local retry with exponential backoff. Only propagates to coordinator after local retries exhausted — includes partial results and what was attempted
• For validation errors: subagent returns immediately with structured error and the specific invalid parameter — coordinator must correct input before re-delegating
• For business errors: subagent returns with isRetryable: false and a customer-friendly explanation — coordinator decides whether to escalate to human
• For permission errors: subagent returns with context about what access was needed — coordinator handles re-authentication and re-delegation

Exam Traps for Task 2.2

🔨 Implementation Task

Exam Simulation — Task 2.2

The Core Concept

Tool selection reliability degrades as tool count increases. With 4–5 focused tools, a well-described agent routes correctly and consistently. With 18 tools, the model's decision space becomes cluttered — especially when several tools are broadly described or outside the agent's specialization.

The second problem is specialization boundary violations: a synthesis agent that also has web search tools will occasionally use them when it should be synthesizing — because the tools are available and the user query contains search-like phrasing.

Tool Count Impact

tool_choice Configuration

Three options with very different behaviors. The exam will test whether you can select the right one for a given scenario.

Scoped Tool Access Pattern

The solution to the 85%/15% verification problem — where a synthesis agent needs simple fact-checks 85% of the time — is a scoped cross-role tool rather than full web search access.

• Restrict each subagent's tool set to those relevant to its role, preventing cross-specialization misuse
• Replace generic tools with constrained alternatives (e.g., fetch_url → load_document that validates document URLs)
• Provide scoped cross-role tools for high-frequency needs while routing complex cases through the coordinator
• Use tool_choice: "any" to guarantee the model calls a tool rather than returning conversational text
• Use forced tool_choice to ensure prerequisite tools are called first; process subsequent steps in follow-up turns

Exam Traps for Task 2.3

🔨 Implementation Task

Exam Simulation — Task 2.3

The Core Concept

MCP (Model Context Protocol) is the mechanism for exposing external services — GitHub, databases, Jira, custom APIs — as tools available to Claude. The exam tests two layers: where configuration belongs (project vs user scope) and how to make MCP tools reliable in production (descriptions, resources, credential management).

Server Scoping Rules

Configuration & Credential Management

Never hardcode credentials in .mcp.json. Use environment variable expansion. The ${VAR} syntax is expanded at runtime from the shell environment — the config file itself contains no secrets and is safe to commit.

{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://github.mcp.example.com/sse",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"    // ✓ expanded from shell env
      }
    },
    "jira": {
      "type": "url",
      "url": "https://jira.mcp.example.com/sse",
      "env": {
        "JIRA_API_KEY": "${JIRA_API_KEY}"   // ✓ never commit actual keys
      }
    }
  }
}

{
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "ghp_abc123xyz789actual_token_value"  // ✗ secret in git
      }
    }
  }
}

MCP Resources — The Often-Missed Knowledge Point

MCP resources are a mechanism for exposing content catalogs to agents — not as callable tools, but as structured data the agent can read at startup. This reduces exploratory tool calls because the agent already knows what data is available before deciding what to look up.

Exam Traps for Task 2.4

🔨 Implementation Task

Exam Simulation — Task 2.4

The Core Concept

Claude Code's built-in tools are the primary interface for file and codebase operations. The exam tests precise selection — not just "which tool reads files" but "given this specific task, which combination of tools is correct, and what do you do when your first choice fails?"

The two most commonly confused pairs: Grep vs Glob (content search vs path matching) and Edit vs Read+Write (targeted modification vs full file replacement fallback).

Built-in Tool Reference

Critical Usage Patterns

The Edit → Read + Write Fallback:

Incremental Codebase Understanding:

• Start with Grep to find entry points — search for main function names, entry module exports, top-level imports
• Use Read selectively to follow imports and trace flows from those entry points — not reading all files upfront
• For function usage tracing: first use Grep to identify all exported names, then search for each name across the codebase
• Never use Read on every file in a large codebase — build understanding incrementally from the most relevant starting points

Exam Traps for Task 2.5

🔨 Implementation Task

Exam Simulation — Task 2.5