D5 · Tools and MCPs

This domain is roughly 5 of 53 items. It tests whether you can define tools well (the description is the single most important lever), run the tool-use lifecycle correctly, choose between client- and server-side tools, and understand and author MCP servers. The theme: tools are how Claude acts on the world – describe them precisely and connect them safely.

Learning objectives

By the end of this page you should be able to:

1. Run the tool-use / function-calling lifecycle with correct JSON.
2. Write effective tool descriptions and design input_schema.
3. Use tool_choice (auto/any/tool/none) and know the Fable 5.1 restriction.
4. Use parallel tool calls and distinguish client-side vs server-side tools.
5. Use tool search + defer_loading, programmatic tool calling, and approval patterns.
6. Explain MCP fundamentals and author an MCP server in Python (FastMCP) and TypeScript.
7. Configure MCP in Claude Code / Desktop and via the MCP connector in the Messages API.

5.1 The tool-use lifecycle

{
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about weather, temperature, or conditions in a named location.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {"type": "string", "description": "City name, e.g. 'Paris'"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
      },
      "required": ["city"]
    }
  }]
}

{
  "stop_reason": "tool_use",
  "content": [
    {"type": "text", "text": "Let me check the weather."},
    {"type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": {"city": "Paris"}}
  ]
}

{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01", "content": "18C, partly cloudy"}
  ]
}

Errors are returned with "is_error": true in the tool_result so Claude can recover.

A complete round-trip on the wire

The four Tabs above are the four wire messages of one round-trip. Read them as a single conversation so the tool_use_id threading is unmistakable. The request declares tools; Claude answers with stop_reason: 'tool_use'; you run the function and send a tool_result referencing the same id; Claude produces the end_turn answer.

import anthropic
client = anthropic.Anthropic()

TOOLS = [{
    "name": "get_weather",
    "description": "Get current weather for a city. Use when the user asks about "
                   "weather, temperature, or conditions in a named location. "
                   "Returns a short text summary. Read-only, no side effects.",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name, e.g. 'Paris'"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
        },
        "required": ["city"],
    },
}]

messages = [{"role": "user", "content": "What's the weather in Paris?"}]

# 1. Model turn -> Claude asks for the tool
resp = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024, tools=TOOLS, messages=messages,
)
assert resp.stop_reason == "tool_use"          # NEVER parse text to decide this
messages.append({"role": "assistant", "content": resp.content})

# 2. You run the tool for each tool_use block
for block in resp.content:
    if block.type == "tool_use":
        result = fetch_weather(**block.input)   # your real function
        messages.append({"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": block.id,            # MUST match the originating id
            "content": result,
        }]})

# 3. Model turn again -> Claude gives the final answer
final = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024, tools=TOOLS, messages=messages,
)
assert final.stop_reason == "end_turn"
print(final.content[0].text)

5.2 Tool descriptions – the most important lever

The description is the primary determinant of whether Claude uses a tool correctly. Invest here more than anywhere else. A good description reads like the docstring you would write for a colleague who has never seen the function.

Good vs bad tool descriptions – four pairs

Each good description answers four questions: what it does, when to use it (and when not), what it returns, and what side effects / irreversibility it carries.

5.3 input_schema design checklist

The schema is JSON Schema. It constrains what Claude may pass and, with strict: true, guarantees the shape. Design it deliberately.

• Types — give every property a type. Use the narrowest type (integer over number when whole).
• Enums — constrain closed sets with enum so Claude cannot invent a value: {"type": "string", "enum": ["celsius", "fahrenheit"]}.
• required — list every argument the tool genuinely needs. Omitted-but-required arguments are a top cause of malformed calls.
• Descriptions per property — describe each field, with an example. Claude reads these.
• Nullable / optional — optional params simply omit from required; to allow an explicit null, use {"type": ["string", "null"]}.
• Bounds and formats — minimum, maximum, pattern, format: 'date' reduce garbage input.
• strict: true — enable strict schema adherence so outputs conform exactly (also a way to get structured behaviour on Fable 5.1 where forced tools 400).

{
  "name": "create_ticket",
  "description": "Open a support ticket. Use only after the user confirms they want one.",
  "input_schema": {
    "type": "object",
    "properties": {
      "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"],
                   "description": "Urgency; default to 'normal' unless the user signals otherwise"},
      "summary":  {"type": "string", "description": "One-line summary, e.g. 'Cannot log in'"},
      "due_date": {"type": ["string", "null"], "format": "date",
                   "description": "ISO date, or null if none"}
    },
    "required": ["priority", "summary"]
  },
  "strict": true
}

5.5 tool_choice

5.6 Parallel tool calls

When subtasks are independent, Claude can emit multiple tool_use blocks in one response. Execute them concurrently and return all tool_result blocks in the next user message (matching each tool_use_id). If the calls are dependent (result of one feeds the next), Claude will serialise them across turns instead.

tool_uses = [b for b in resp.content if b.type == "tool_use"]
results = run_concurrently(tool_uses)     # independent tools in parallel
messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": u.id, "content": r}
    for u, r in zip(tool_uses, results)]})   # ALL results in ONE user turn

5.7 Client-side vs server-side tools

Server-side tools are enabled by declaring them; Anthropic executes them and may pause the turn (pause_turn) while running.

Server-side built-in tools

5.8 Tool search, defer_loading and programmatic calling

• Beyond ~10 tools, use the tool search tool with defer_loading: true so the full tool definitions are loaded on demand rather than all upfront — reduces context bloat and wrong-tool selection (anti-pattern #8).
• Programmatic tool calling lets code invoke tools directly in a controlled loop.
• Approval patterns: require human/hook approval before irreversible tool actions (see hooks, Domains 3 and 6).

# Large catalogue: defer full definitions, expose the search tool.
tools = [
    {"type": "tool_search_tool_20250000", "name": "tool_search"},  # lets Claude find tools on demand
    {"name": "get_order",     "description": "...", "input_schema": {...}, "defer_loading": True},
    {"name": "issue_refund",  "description": "...", "input_schema": {...}, "defer_loading": True},
    # ...50 more deferred tools; only the ones Claude searches for are hydrated into context
]
resp = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                              tools=tools, messages=messages)

The pattern keeps the active tool set small (4–5 in context at a time) even when the catalogue is large, which is exactly the fix for anti-pattern #8.

5.9 MCP fundamentals

The Model Context Protocol is an open standard (JSON-RPC 2.0) for connecting Claude to external tools and data.

• Transports: stdio (local subprocess) and Streamable HTTP (remote; SSE is legacy).
• Capability negotiation happens on initialize.
• OAuth 2.1 secures remote servers.

Host (Claude Desktop / Code)
   │  JSON-RPC 2.0
   ├── stdio ──► local MCP server (subprocess)
   └── Streamable HTTP ──► remote MCP server (OAuth 2.1)

5.10 Authoring an MCP server

A minimal but complete server: it names itself, declares one tool with a typed schema and a docstring description, handles its own errors, and runs over stdio. Both SDKs below are runnable as-is.

# weather_server.py — run: python weather_server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get current weather for a city.

    Use when the user asks about weather, temperature or conditions in a
    named location. Returns a short text summary. Read-only, no side effects.
    """
    if not city:
        raise ValueError("city is required")
    return fetch_weather(city, unit)

@mcp.resource("config://units")
def default_units() -> str:
    """Application-controlled resource: the default unit system."""
    return "celsius"

if __name__ == "__main__":
    mcp.run()   # stdio transport by default; use mcp.run(transport='streamable-http') for remote

// weather_server.ts — run: node weather_server.js
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'weather', version: '1.0.0' });

server.tool(
  'get_weather',
  'Get current weather for a city. Use when asked about weather in a named location. Read-only.',
  { city: z.string().describe('City name, e.g. Paris'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius') },
  async ({ city, unit }) => {
    if (!city) throw new Error('city is required');
    return { content: [{ type: 'text', text: await fetchWeather(city, unit) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);   // for remote: StreamableHTTPServerTransport

5.11 Configuring MCP

# stdio (local subprocess)
claude mcp add weather --scope project -- python weather_server.py

# HTTP (remote server)
claude mcp add --transport http docs https://mcp.example.com/mcp --scope user

# list / remove
claude mcp list
claude mcp remove weather

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["weather_server.py"],
      "env": { "WEATHER_API_KEY": "${WEATHER_API_KEY}" }
    },
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}

resp = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Search the docs for retry policy."}],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/mcp",
        "name": "docs",
        "authorization_token": "Bearer …",   # OAuth 2.1 token for the remote server
    }],
    betas=["mcp-client-2025-04-04"],
)

5.12 MCP vs custom tool vs Skill – decision table

These three ways of extending Claude are frequently confused on the exam.

Rule of thumb: one app, few functions → custom tools; reuse across hosts/teams → MCP; packaged know-how and helper scripts for Claude Code → Skill.

5.13 MCP transports, capability negotiation and OAuth 2.1

The wire details of MCP recur in exam items. MCP is JSON-RPC 2.0; a host and server negotiate capabilities on initialize, then exchange tool/resource/prompt calls over a transport.

Host ──initialize──► Server         (capability negotiation: tools? resources? prompts?)
Host ◄─capabilities─ Server
Host ──tools/list───► Server         (discover model-controlled tools)
Host ──tools/call───► Server         (Claude invokes a tool)
Host ──resources/read► Server        (application-controlled data)
Host ──prompts/get──► Server         (user-controlled templates)

5.14 Approval and human-in-the-loop for irreversible tools

Some tools are irreversible (refunds, deletes, sends, deploys). The correct design gates them deterministically, not by trusting the model.

# Gate an irreversible tool behind approval; return is_error so Claude can adapt.
if block.name == "issue_refund" and block.input["amount_cents"] > 50000:
    result = {"type": "tool_result", "tool_use_id": block.id,
              "content": "Refund over $500 requires human approval; request queued.",
              "is_error": True}

5.15 Common misconceptions

5.16 Scenario walkthrough: a payments tool that must be safe and portable

Scenario. A fintech wants Claude to look up orders, search a help centre, and — carefully — issue refunds, and they want the same tools available in Claude Code, Claude Desktop and a production Messages API service, maintained in one place. They are on Fable 5.1 for its reasoning quality. Early attempts force the refund tool with tool_choice: {type: 'tool', name: 'issue_refund'} (getting 400s), sometimes drop a tool result when two tools run in parallel (getting 400s), and issue refunds with no approval step.

Expert reasoning trace.

1. Choose the reuse mechanism. ‘Same tools across Code, Desktop and the API, one place’ → build an MCP server and connect each host (stdio locally, Streamable HTTP for the shared/remote server secured with OAuth 2.1; the Messages API uses the MCP connector). Copying custom-tool JSON into each app is the maintenance trap.
2. Fix the Fable 5.1 400s on tool choice. Fable 5.1 rejects forced/any tool choice. Use tool_choice: 'auto' with a clear instruction, or structured outputs / strict: true for the extraction parts. Retrying the 400 with backoff is wrong — it is deterministic.
3. Fix the parallel-result 400s. Return exactly one tool_result per tool_use block, all in the same following user turn, each keyed to its tool_use_id; on failure return is_error: true so Claude can recover. Dropping one result causes the 400.
4. Make refunds safe. Refunds are irreversible → gate them with a PreToolUse hook / approval workflow and keep the refund tool out of any routine read-only agent’s allowlist. ‘Confirm before refunding’ in the description is not enforcement.
5. Right-size the catalogue. Keep ~4–5 active tools; if the catalogue grows, use tool search + defer_loading.
6. Reject the tempting alternatives. ‘Force the refund tool for determinism’ — 400 on Fable 5.1. ‘Retry the 400 with backoff’ — deterministic error. ‘Put the tools in CLAUDE.md to share them’ — CLAUDE.md holds instructions, not executable tools. ‘Use a Skill to share across hosts’ — Skills are Claude-Code-only packaged know-how.

Correct decision. An MCP server (OAuth 2.1 for the remote transport) connected to all hosts; auto + instruction or structured outputs on Fable 5.1 instead of forced tool choice; correct parallel tool_result handling with is_error; refunds behind an approval hook and out of routine allowlists; tool search + defer_loading if the catalogue grows.

Exam traps in this domain

Practice questions

Key takeaways

• The tool-use lifecycle: define tools → tool_use → run and return tool_result (matching tool_use_id) → final answer.
• The tool description and input_schema are the single most important lever for correct tool use.
• tool_choice is auto/any/tool/none; Fable 5.1 rejects any and forced tools – use structured outputs / strict / auto.
• Independent tools can run in parallel; return all results in one user turn.
• Client-side tools run in your code; server-side built-ins (web search, code execution, computer use, text editor, bash, memory) run at Anthropic.
• Beyond ~10 tools, use tool search + defer_loading; require approval for irreversible actions.
• MCP is JSON-RPC 2.0 with tools (model), resources (app), prompts (user); stdio for local, Streamable HTTP + OAuth 2.1 for remote; author with FastMCP (Python) or @modelcontextprotocol/sdk (TS).
• Capability negotiation happens on initialize; choose stdio for local subprocess tools and Streamable HTTP + OAuth 2.1 for shared/remote servers (SSE-only is legacy).
• Gate irreversible tools (refunds/deletes/sends/deploys) with a PreToolUse hook / approval workflow and least privilege — the tool description is guidance, not enforcement.
• Return every parallel tool_result in one user turn keyed to its tool_use_id, and mark failures with is_error: true so Claude can recover.
• A forced-tool 400 on Fable 5.1 is deterministic — switch to auto/structured outputs rather than retrying with backoff.