Domain 2: Tool Design & MCP Integration (18% of the exam)

Domain 2 tests whether you can design tools that Claude selects and calls reliably, and whether you understand the Model Context Protocol (MCP) — the open standard that connects Claude to external systems. This is the second-largest domain after agent design, and it is heavily scenario-based: you will be shown a misbehaving tool setup and asked to pick the fix. The right answers almost always come from a few core principles, so internalize them rather than memorizing trivia.

Blueprint overview

The domain breaks into three areas:

1. Designing tools — descriptions, tool_choice, and structured error returns.
2. MCP deep dive — the protocol's primitives, configuration (.mcp.json), and transports.
3. Investigation workflows — using built-in tools (Grep, Read, etc.) in an incremental, evidence-first way.

Tools: what Claude actually sees

When you pass tools to the Messages API, Claude does not see your implementation. It sees only three fields per tool: name, description, and input_schema (a JSON Schema). These are injected into a system prompt, and from them alone Claude decides whether to call a tool and how to fill its arguments.

This makes the description the selection mechanism. Anthropic's guidance is explicit: "Provide extremely detailed descriptions. This is by far the most important factor in tool performance." A good description is 3–4+ sentences and covers what the tool does, when to use it (and when not to), what each parameter means, and what it does not return.

When the model picks the wrong tool, the fix is rarely "fine-tune" — it is improve the descriptions, disambiguate overlapping tools, or consolidate related operations into one tool with an action enum. Namespacing (github_list_prs, slack_send_message) keeps a growing tool library unambiguous.

tool_choice: controlling whether and which tool runs

The tool_choice parameter governs tool selection:

• {"type": "auto"} — default when tools are present; Claude decides whether to call a tool or answer in text.
• {"type": "any"} — Claude must call one of the tools (but chooses which).
• {"type": "tool", "name": "..."} — forces a specific tool.
• {"type": "none"} — prevents any tool call.

Key exam fact: with auto, Claude can interleave reasoning and may or may not call tools; with any or a forced tool, Claude does not emit chain-of-thought before the call by default. Use forced choices for structured-output extraction; use auto for open-ended agents.

Structured errors: keep the agent in the loop

When a tool fails, return the result as a normal tool_result with "is_error": true and a clear, actionable message — do not throw at the API layer. This lets Claude read the error and self-correct (retry with fixed arguments, choose another tool, or ask the user).

Good error messages name what went wrong and how to fix it. Returning an HTTP 500 or an empty result strands the model.

The Messages API tool-use loop and stop_reason

The flow: you send tools → Claude responds with stop_reason: "tool_use" and one or more tool_use content blocks → you execute and send back tool_result blocks in a user message → Claude continues. Always pass tool results back keyed by tool_use_id. When Claude finishes normally the stop_reason is end_turn. Recognizing tool_use as the signal to run the tool is a frequent exam point.

MCP: the three server primitives

MCP is an open standard with a client–server, JSON-RPC 2.0 architecture. A host (Claude Code, Claude Desktop) spawns one client per server. Connections start with an initialize handshake that negotiates a protocolVersion and exchanges capabilities.

Servers expose three primitives — memorize these:

• Tools — executable functions the model invokes to take action (tools/list, tools/call). Model-controlled.
• Resources — read-only data sources that provide context: files, records, schemas (resources/list, resources/read). Application/user-controlled.
• Prompts — reusable templates / slash-command workflows (prompts/list, prompts/get). User-initiated.

The classic distractor confuses a resource (data you read) with a tool (action you invoke). Discovery is dynamic: every primitive has a */list method, and servers that declare listChanged can push list_changed notifications so clients refetch.*

MCP configuration and transports

In Claude Code, servers are declared in .mcp.json (project scope, checked into the repo and shared with the team), or via claude mcp add at user/local scope. A stdio server entry has a command and args; HTTP servers have a url.

Two transports:

• stdio — local subprocess; the host launches the server and talks over stdin/stdout. Best for local tools and lowest latency.
• Streamable HTTP — remote servers over HTTP, supporting auth (OAuth) and server-sent streaming. Best for hosted, shared, or multi-user servers.

MCP tools appear alongside built-in tools, namespaced by server (e.g. mcp__github__list_prs), so the Module 1 description and selection rules still apply.

Investigation workflows

Built-in tools reward an incremental, evidence-first loop: Grep to locate → Read the specific region → trace references → act. Do not Read whole files blindly or fix before reproducing. The exam favors answers that gather targeted evidence before editing.

Master these principles and Domain 2's scenario questions become predictable: the fix is usually a better description, the right tool_choice, a structured error, or the correct MCP primitive/transport.