Quick Reference: Domain 2 — Tool Design & MCP Integration

Tool descriptions are the primary mechanism Claude uses to select which tool to call. They matter more than tool names.

What to include in a tool description:

• What the tool does (one sentence)
• Expected input formats and constraints
• What it returns (shape of the response)
• Boundary conditions (what it does NOT do)
• Example queries that would trigger this tool

Count the tools before you pick the remedy. Misselection has two different causes and they take opposite fixes:

Descriptions are the first fix only when the toolkit is already a workable size. Past roughly 4–5 tools per agent, selection degrades on decision complexity alone, and rewriting 22 descriptions leaves that untouched. Few-shot examples are not a sanctioned step for misselection — the bank keys them wrong.

• Keep each agent's tool set small and role-focused. The guide contrasts 4–5 tools with 18 to show how selection reliability degrades as the set grows.
• Use descriptive parameter names — customer_email not email, order_date_range not range.
• Mark parameters as required only when truly mandatory. Optional parameters with defaults reduce friction.
• Use enum types for constrained choices — they guide the model better than freeform strings.
• Diagnose before you fix. A small toolkit with two lookalike tools is a description problem. An oversized toolkit is a distribution problem, and no amount of description quality rescues it.

Key exam point: Use tool_choice: { type: "tool", name: "extract_data" } when you need one specific structure every time. When the document type is unknown and any of several extraction schemas could apply, tool_choice: "any" still guarantees structured output while letting the model pick the right tool.

auto is the correct default for agentic loops — the model needs freedom to decide when to call tools and when to respond with text.

Three-layer model: Host ⊃ Client ↔ Server (the host application contains the client; the client connects to servers)

Protocol: JSON-RPC 2.0 over stdio or streamable HTTP.

Configuration files:

• .mcp.json in project root — project-level MCP servers (shared with team)
• ~/.claude.json — personal/global MCP servers (not committed)

Key rule: Use community MCP servers first. Only build custom servers when no community server meets your requirements.

Structured error metadata (the exam-tested pattern). This is an application-level convention carried inside the result content, not part of the MCP envelope — the protocol's CallToolResult defines only content, structuredContent and isError:

{
  "errorCategory": "transient" | "validation" | "business" | "permission",
  "isRetryable": true | false,
  "description": "Rate limit hit; retry after 5 seconds"
}

The four categories: transient (timeouts, service unavailability — isRetryable: true, resend as-is), validation (invalid input — false, correct the input and send a new call), business (policy violations — false, take an alternative path), permission (missing access — false, escalate to a principal with access). Only transient is retryable: the flag asks whether resending this call can work, and everything else needs something to change first. "Not found" is deliberately absent: a query that finds nothing is a valid empty result, not an error.

Critical distinction:

• Access failure (auth error, network timeout) → Retry or escalate. Something went wrong.
• Valid empty result (search returned 0 results) → Accept. The absence of data IS the answer.

Never treat a valid empty result as an error. Never silently swallow an access failure.

Selection principle: Use the most specific tool. Grep for content search, Glob for file discovery, Read for known files. Avoid Bash for tasks that specialised tools handle better.

When Edit fails on a non-unique match: the exam guide names Read + Write as the tested fallback — load the full file, then write the complete modified version.

Current state (checked 14 August 2026): the live tools reference describes Claude first supplying a longer anchor string with enough surrounding context to pin down one occurrence, or setting replace_all: true. Answer Read + Write on the exam; recognise the widening and replace_all behaviour in current Claude Code.