Tool Use and the Model Context Protocol

Tool use is how Claude acts outside the conversation: Claude emits a structured call, and your application or Anthropic's servers run it. The Model Context Protocol (MCP) turns that connection into a shared protocol, so one server can expose tools, resources and prompts to any compatible client. This page teaches both for the Claude certification exams that test them, with an exam map at the end; product facts are as of September 2026, and where the documentation has moved since the July 2026 exam guides, the section shows both versions and which wording to expect on the exam (the guide's).

How tool use works

Tested in: CCAR-F 1.1, EX1-STEP2, APPX-TECH-5, APPX-INSCOPE-1 · CCDV-F D8.1 Tool Implementation, D1.2 Agent Construction with Claude, D1.3 Agent Patterns and Frameworks, D2.3 Claude API Mechanics

Tool use (also called function calling) lets Claude call functions that you define or that Anthropic provides. Claude decides when to call a tool from the user's request and the tool's description, then returns a structured call. Your application executes client tools; Anthropic executes server tools. The docs state the contract in one line: "The model never executes anything on its own." (How tool use works)

Where the code runs: three buckets

The docs call where the code executes "The primary axis along which tools differ": every tool falls into one of three buckets, and the bucket decides what your application is responsible for (How tool use works).

Three consequences follow. Claude never sees a user-defined tool's implementation, only the schema you supplied and the result you returned, so what the tool does, when to use it and what its inputs mean has to be stated in the definition. An Anthropic-schema tool's schema is trained in, which is why Anthropic-defined tools recommends it over an equivalent of your own; the individual tools are listed there too. Server-executed tools usually finish before you see the response; the main exceptions are a paused server loop (pause_turn) and a turn that also calls a client tool. The server-side set also covers MCP connectors and the advisor tool.

The client-tool round trip

The Claude API has no separate tool or function role. Tool calls arrive inside assistant messages and tool results go back inside user messages. Because the model cannot run your code, every client tool call is a round trip:

1. Send a request with your tools array and the user message.
2. Claude responds with stop_reason: "tool_use" and one or more tool_use blocks. Each block carries an id (used to match the result), the tool name, and an input object conforming to your input_schema (only strict: true guarantees that; see Defining a tool).
3. Execute each tool and format each output as a tool_result block whose tool_use_id matches the call's id.
4. Send a new request containing the original messages, the assistant's response, and a user message holding the tool_result blocks.
5. Repeat while stop_reason is "tool_use". Any other stop reason ("end_turn", "max_tokens", "stop_sequence" or "refusal") exits the loop: Claude has either produced a final answer or stopped for another reason that your application should handle.

The Messages API is stateless, so the harness re-sends everything on each turn: past actions, tool descriptions and instructions. Appending each result to that history is what lets Claude reason about its next action, which is what CCAR-F 1.1-K2 and 1.1-S2 test, and the guide's first preparation exercise asks you to build this loop and handle both "tool_use" and "end_turn" correctly (EX1-STEP2).

Agentic harness dispatch

Anthropic defines an agent harness as "the software scaffolding around a model: the loop, tools, context management, and guardrails that turn raw intelligence into a working agent" (Agent harness design). The Claude Code glossary puts it the same way: "Claude Code is the harness; Claude is the model inside it." Dispatch is the harness step that routes each call to real code: run the tool in your codebase that corresponds to the tool name, passing the tool input. In Anthropic's Managed Agents design, the harness is the loop that calls Claude and routes its tool calls to the relevant infrastructure, and every tool gets one interface, execute(name, input) → string (a name and input go in, a string comes back); that interface supports custom tools, MCP servers and Anthropic's own tools.

The excerpt below is "Ring 4: Error handling" of Anthropic's build a tool-using agent tutorial. run_tool is the dispatcher: it maps a name to a handler and raises on an unknown name. The loop sends any exception back as an is_error: true result instead of crashing, so Claude can retry with corrected input, ask the user for clarification, or explain the limitation.

# Excerpt from Ring 4: the imports (json, anthropic), client and tools
# (create_calendar_event, list_calendar_events) are defined above this
# point, and messages just after run_tool, in the tutorial's full example.
def run_tool(name, tool_input):
    if name == "create_calendar_event":
        if "attendees" in tool_input and len(tool_input["attendees"]) > 10:
            raise ValueError("Too many attendees (max 10)")
        return {"event_id": "evt_123", "status": "created", "title": tool_input["title"]}
    if name == "list_calendar_events":
        return {"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}
    raise ValueError(f"Unknown tool: {name}")

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

while response.stop_reason == "tool_use":
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            try:
                result = run_tool(block.name, block.input)
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(result)}
                )
            except Exception as exc:
                # Signal failure so Claude can retry or ask for clarification.
                tool_results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": str(exc),
                        "is_error": True,
                    }
                )

    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})

    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

// Excerpt from Ring 4: the import, client and tools (create_calendar_event,
// list_calendar_events) are defined above this point, and messages just
// after runTool, in the tutorial's full example.
function runTool(name: string, input: Record<string, unknown>) {
  if (name === "create_calendar_event") {
    const attendees = input.attendees as string[] | undefined;
    if (attendees && attendees.length > 10) {
      throw new Error("Too many attendees (max 10)");
    }
    return { event_id: "evt_123", status: "created", title: input.title };
  }
  if (name === "list_calendar_events") {
    return {
      events: [{ title: "Existing meeting", start: "14:00", end: "15:00" }],
    };
  }
  throw new Error(`Unknown tool: ${name}`);
}

let response = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  tools,
  messages,
});

while (response.stop_reason === "tool_use") {
  const toolResults: Anthropic.ToolResultBlockParam[] = [];
  for (const block of response.content) {
    if (block.type === "tool_use") {
      try {
        const result = runTool(block.name, block.input as Record<string, unknown>);
        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: JSON.stringify(result),
        });
      } catch (err) {
        // Signal failure so Claude can retry or ask for clarification.
        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: String(err),
          is_error: true,
        });
      }
    }
  }

  messages.push({ role: "assistant", content: response.content });
  messages.push({ role: "user", content: toolResults });

  response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools,
    messages,
  });
}

Three details in that loop are worth memorizing. All results for one assistant turn go back together in a single user message. Each result carries the tool_use_id of its call. A failure becomes is_error: true rather than an exception that kills the agent; the tutorial notes that the flag is the only difference from a successful result. The formatting rules are in Returning tool results and errors.

Computer use and browser use toolsets add one dispatch rule. A member tool_use block also carries a toolset_name ("computer" or "browser"), and its name is the member being called, such as screenshot or navigate. Dispatch on the pair (toolset_name, name), because a custom tool in the same request can share a member's name, and echo the same toolset_name on the tool_result: a member result that omits it is rejected. CCAR-F lists computer use (browser automation, desktop interaction) as out of scope.

Tool Runner or a manual loop

The client SDKs ship a Tool Runner (beta, in all seven SDKs: Python, TypeScript, C#, Go, Java, PHP and Ruby) that runs your tools, handles the request and response cycle, and manages conversation state. It loops until Claude returns a message without a tool use, or until max_iterations if you set it. In Python, @beta_tool derives the JSON schema from the function's arguments and docstring. In TypeScript, betaZodTool() defines a type-safe tool from a Zod schema (Zod 3.25.0 or higher), and betaTool() takes JSON Schema instead. When a tool throws, the runner returns the error to Claude as an is_error: true result.

import json
from anthropic import Anthropic, beta_tool

client = Anthropic()

@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[get_weather],
    messages=[{"role": "user", "content": "What's the weather like in Paris?"}],
)
for message in runner:
    print(message)

import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const client = new Anthropic();

const getWeatherTool = betaZodTool({
  name: "get_weather",
  description: "Get the current weather in a given location",
  inputSchema: z.object({
    location: z.string().describe("The city and state, e.g. San Francisco, CA"),
    unit: z.enum(["celsius", "fahrenheit"]).default("fahrenheit").describe("Temperature unit")
  }),
  run: async (input) => {
    return JSON.stringify({ temperature: "20°C", condition: "Sunny" });
  }
});

const finalMessage = await client.beta.messages.toolRunner({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  tools: [getWeatherTool],
  messages: [{ role: "user", content: "What's the weather like in Paris?" }]
});

for (const block of finalMessage.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Decide. If some calls need human-in-the-loop approval, custom logging or conditional execution, write the manual loop, because the docs point to it for exactly those cases. Otherwise the Tool Runner removes the boilerplate. In Python and TypeScript you can still inspect results before they reach Claude with generate_tool_call_response() or generateToolResponse().

When a tool is the right design

The docs give a sharp test: "if you're writing a regex to extract a decision from model output, that decision should have been a tool call." (How tool use works)

When the existing system must also be reusable across several Claude applications and maintained independently of any one app, CCDV-F Sample 3 keys an MCP server that exposes the operations as tools; the item and its rationale are worked in How the official sample frames it. MCP is taught from MCP architecture onward.

Server tools run their own loop

Server tools run a loop inside Anthropic's infrastructure, so one request can trigger several searches or code runs before you see a response. That loop has an iteration limit, 10 iterations per request by default; a turn that hits it returns stop_reason: "pause_turn" instead of "end_turn", meaning the work is not finished, and you re-send the conversation (including the paused response) to let Claude continue. When Claude calls a server tool and a client tool in the same parallel group, control comes back to you with "tool_use" before the server tool runs. Both cases are covered in Anthropic-defined tools and Parallel tool calls.

How the exams frame it

Decide. CCAR-F 1.1-S1 asks for loop control that continues when stop_reason is "tool_use" and terminates when it is "end_turn". Objective 1.1-K3 tests the distinction between model-driven decision-making, where Claude reasons about which tool to call next based on context, and pre-configured decision trees or tool sequences. In the agentic loop Claude chooses the next tool. When critical business logic requires a specific sequence, enforce it in code with a programmatic prerequisite (1.4-S1 and sample question 1; see Controlling tool choice).

Traps. The guide names three anti-patterns (1.1-S3), and each is a wrong-answer shape:

• Parsing natural language signals, such as Claude saying it has finished, to decide when to stop.
• Arbitrary iteration caps as the primary stopping mechanism. A cap as a safety limit is normal: Anthropic's own agent guidance calls stopping conditions such as a maximum number of iterations common, the Tool Runner has max_iterations, and the Agent SDK has max_turns and max_budget_usd. The trap is using the cap instead of stop_reason.
• Treating assistant text as a completion signal. Claude often writes explanatory text before its tool_use blocks, so text in a response does not mean the work is finished.

Defining a tool

Tested in: CCAR-F 2.1-K2, 4.3-K1, 4.3-K3, 4.3-S1, 4.4-K4, EX3-STEP1, APPX-TECH-5, APPX-TECH-7, APPX-INSCOPE-13 · CCDV-F D8.1 Tool Implementation, D2.3 Claude API Mechanics, D6.3 Output Handling

Client tools go in the top-level tools parameter of the request. A user-defined tool is a name, a description and an input_schema. Optional properties compose on the same tool, so one definition can set defer_loading, cache_control and strict together. Anthropic-schema tools are declared differently, by a date-versioned type (see Anthropic-defined tools).

The core fields

A definition with a required parameter, an optional enum parameter and examples (the docs' own example):

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature"}
    },
    "required": ["location"]
  },
  "input_examples": [
    {"location": "San Francisco, CA", "unit": "fahrenheit"},
    {"location": "Tokyo, Japan", "unit": "celsius"},
    {"location": "New York, NY"}
  ]
}

The one-line description here is the docs' minimal example. A production description should be several sentences long, as the next section explains.

Optional properties on any tool

Strict tool use

strict: true is a top-level property of the tool definition, next to name, description and input_schema. It constrains token sampling to schema-valid output (grammar-constrained sampling). Without it, Claude can return an incompatible type ("2" instead of 2) or omit a required field. With it, the input always follows input_schema and the tool name is always valid.

{
  "name": "search_flights",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "destination": {"type": "string"},
      "departure_date": {"type": "string", "format": "date"},
      "passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}
    },
    "required": ["destination", "departure_date"],
    "additionalProperties": false
  }
}

Strict mode and JSON outputs (output_config.format) are the two structured-outputs features. They share the same JSON Schema limits and can be used together: JSON outputs control what Claude says, strict tool use validates how Claude calls your functions. JSON outputs are taught in Structured outputs.

Schema rules under strict mode

Per-request limits (as of September 2026)

When a design hits these limits, the docs list four strategies to try in order: mark only critical tools as strict; reduce optional parameters (make parameters required where possible); simplify nested structures; and split many strict tools across separate requests or subagents.

Behaviors to design around:

• Enum and const capitalization is not guaranteed, even under strict tool use: Claude may return a value that differs from your schema only in capitalization, with no error and no special stop_reason. Compare enum values case-insensitively and avoid values that differ only in case.
• Besides enum casing, the schema guarantee has two more documented exceptions. A refusal (stop_reason: "refusal", HTTP 200, billed) takes precedence over schema constraints, and a response cut off at max_tokens may be incomplete; retry the latter with a higher max_tokens.
• Required properties are emitted first, then optional ones, whatever order the schema lists them in.
• Strict tool use is HIPAA eligible, but protected health information must not appear in the schema itself (property names, enum or const values, patterns), because compiled schemas are cached separately.
• Strict tools cannot be called through programmatic tool calling, and the computer and browser toolset entries reject strict: true.

What strict mode does not fix. The CCAR-F guide tests (4.3-K3) "That strict JSON schemas via tool use eliminate syntax errors but do not prevent semantic errors (e.g., line items that don't sum to total, values in wrong fields)". The docs are consistent with this: strict mode guarantees the shape, not the truth of the values. If an answer choice claims a schema alone will catch a total that does not add up, it is wrong. The guide's own remedies are validation plus a retry that appends the specific validation error (4.4-K1), and self-check fields such as a calculated_total extracted alongside the stated_total so a discrepancy can be flagged (4.4-S4); both are taught in Validation, retry and feedback loops. Schema idioms for extraction (nullable fields, an "other" value plus a detail field) are in Structured output with tools and JSON schemas; in a large strict schema, budget them against the 24 optional and 16 union-typed parameter limits above.

Input examples

input_examples help most for complex tools with nested objects, optional parameters or format-sensitive inputs. They cost prompt tokens: roughly 20 to 50 per simple example and 100 to 200 for a complex nested object. In Anthropic's internal testing, tool use examples raised accuracy on complex parameter handling from 72% to 90%. Anthropic's guidance is realistic data (real city names, plausible prices), a mix of minimal, partial and full specification patterns, and 1 to 5 examples per tool, added only where correct usage is not obvious from the schema. The description still comes first: the docs' advice is to prioritize descriptions and consider input_examples for complex tools.

Extraction tools

For extraction (CCAR-F 4.3-S1), the tool is a schema rather than an action: define a tool whose input_schema is the record you want and read the structured data from the tool_use block's input. Anthropic's cookbook "Extracting Structured JSON using Claude and Tool Use" works this way, with tools such as print_summary and print_entities, and it also shows an open-ended input_schema for keys you cannot know up front, with the prompt explaining how to use the tool. To make sure the extraction call happens at all, pair the tool with a tool_choice of any or a forced tool on models that support forcing (the guide's answer, 4.3-S2 and 4.3-S3). The newest models reject forcing; the replacement is in Where forced tool use is rejected.

Reading what Claude sends back

• Claude often writes explanatory text before its tool_use blocks. Treat that text like any other assistant text and do not rely on its formatting.
• Never string-match serialized tool input: Unicode and forward-slash escaping differs between model versions. Parse it with json.loads() or JSON.parse().
• When streaming, a tool's input arrives as input_json_delta events carrying partial_json strings; the final tool_use.input is always an object. With eager_input_streaming the input is not validated before it streams, so you can receive partial or invalid JSON. Guard the parse, and if it fails, return the raw string wrapped as {"INVALID_JSON": "..."} in an is_error: true result. Details: Streaming.

The per-tool eager_input_streaming field replaces the legacy fine-grained-tool-streaming-2025-05-14 beta header. A request that still sends the header turns fine-grained streaming on for tools that leave the field unset, and an explicit false keeps buffered streaming for that tool. CCAR-F lists streaming API implementation as out of scope; CCDV-F D2.3 includes streaming.

Agent SDK custom tools are defined differently, as MCP tools on an in-process server; see The Claude Agent SDK below and Custom tools in the SDK.

Writing tool descriptions that steer selection

Tested in: CCAR-F 2.1, 2.4-S3, EX1-STEP1, APPX-INSCOPE-4 · CCDV-F D8.1 Tool Implementation

The CCAR-F guide treats tool descriptions as "the primary mechanism LLMs use for tool selection" and warns that minimal descriptions make selection among similar tools unreliable (2.1-K1). The Define tools page agrees, calling extremely detailed descriptions "by far the most important factor in tool performance." With the default tool_choice of auto, Claude calls a tool when the request maps to that tool's described capability and the answer is not already in context; it responds directly for stable knowledge, creative tasks and conversational turns. The description is therefore what Claude matches the request against (our inference from the docs' wording).

When you pass tools, the API builds a special system prompt from your tool definitions, the tool configuration and your own system prompt. The docs publish its template, below. Your tool definitions and your own system prompt land in the same system prompt; our reading is that this is one reason system prompt wording can change tool selection:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

What a description must say

The "Anthropic guidance" column combines the Define tools checklist with Building effective agents, which says "A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools."

Aim for at least 3 to 4 sentences per description, more for a complex tool. Anthropic's tool-design post suggests describing the tool as you would to a new hire on your team, making implicit context explicit (specialized query formats, niche terminology, relationships between resources), and naming parameters unambiguously: user_id rather than user.

The docs contrast a good and a poor definition of the same tool (both verbatim from Define tools):

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

The good version says what the tool does, when to use it, what it returns and what ticker means, and it states what the tool will not provide. In the docs' words, the poor one "is too brief and leaves Claude with many open questions about the tool's behavior and usage." (Define tools)

Separate similar tools by when, not only what

Writing about agents connected to many MCP servers, Anthropic's advanced tool use post reports that the most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names such as notification-send-user and notification-send-channel. The troubleshooting guide traces "Claude calls tool A when you wanted tool B" to description ambiguity, and its fix is: "Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do." (Troubleshooting tool use)

CCAR-F builds its objectives on the same idea, with three concrete moves:

• Diagnose overlap. Near-identical descriptions cause misrouting, as with analyze_content versus analyze_document (2.1-K3).
• Rename and re-describe. Remove functional overlap by renaming analyze_content to extract_web_results and giving it a web-specific description (2.1-S2).
• Split a generic tool. Break a generic analyze_document into extract_data_points, summarize_content and verify_claim_against_source, each with a defined input and output contract (2.1-S3). When to split and when to consolidate is covered in Designing a tool set.

The guide's first preparation exercise asks you to build this deliberately: 3 to 4 MCP tools, including at least two with similar functionality that need careful descriptions to avoid selection confusion (EX1-STEP1).

MCP tools competing with built-in tools. CCAR-F 2.4-S3 tests enhancing MCP tool descriptions to explain capabilities and outputs in detail, so the agent does not prefer a built-in tool such as Grep over a more capable MCP tool. Claude Code's default tool set now handles Grep and Glob differently from the guide (see the note under What each option is), but the objective's point still holds. Under Claude Code's tool search, MCP tool descriptions load on demand and are truncated at a default length; those rules, and how to answer the guide's related 2.4-K3 wording, are in What Claude sees once servers connect.

Worked case: CCAR-F sample question 2

In the guide's sample question 2 (scenario: Customer Support Resolution Agent), production logs show the agent calling get_customer when users ask about orders instead of lookup_order; both tools have minimal descriptions ("Retrieves customer information" / "Retrieves order details") and accept similar identifier formats. The keyed answer, B, is to expand each description with the input formats it handles, example queries, edge cases, and boundaries explaining when to use it versus similar tools. Anthropic's rationale: "Tool descriptions are the primary mechanism LLMs use for tool selection. When descriptions are minimal, models lack the context to differentiate between similar tools." (CCAR-F guide) The full item is reproduced on the CCAR-F page.

The same rationale explains each distractor, and those explanations generalize (CCAR-F guide):

Decide. If Claude picks the wrong tool and the descriptions are thin, fix the descriptions first: the rationale in the CCAR-F guide says option B "directly addresses this root cause" with a low-effort fix. If the descriptions are already complete and misrouting persists, restructure the tool set: the rationale calls consolidation "a valid architectural choice", and renaming or splitting overlapping tools is what 2.1-S2 and 2.1-S3 test. A keyword routing layer and few-shot routing examples are the shapes the rationale rejects (our rule, derived from that rationale and those objectives).

System prompt wording steers selection too

The CCAR-F guide warns (2.1-K4) that "keyword-sensitive instructions can create unintended tool associations", and 2.1-S4 asks you to review system prompts for keyword-sensitive instructions that might override well-written descriptions. The docs show how strongly wording moves tool use (Tool use overview):

The same page adds that to require a tool call rather than rely on prompting, you set tool_choice (next section).

Anthropic's prompting best practices say Claude Opus 4.5 and Claude Opus 4.6 are more responsive to the system prompt than previous models: "If your prompts were designed to reduce undertriggering on tools or skills, these models may now overtrigger. The fix is to dial back any aggressive language." Where you might have written "CRITICAL: You MUST use this tool when...", the page suggests more normal prompting such as "Use this tool when...". Phrasing also decides whether Claude acts at all: "Can you suggest some changes to improve this function?" can get suggestions only, while "Change this function to improve its performance." gets Claude to make the change with its tools.

Stale instructions cost money on newer models: a newer model follows over-specific instructions to the letter, adding tool rounds. Anthropic's cost guide describes a support-desk prompt whose mandatory procedure forced four tool calls on a simple ticket, and reports that, on a support-desk evaluation, prompts written for Claude Opus 4.8 cost 36% more per ticket on Claude Opus 5 with no change in accuracy. The same patterns tend to appear in tool descriptions and skills, so the cost guide advises auditing prompts against the model you run now and again whenever you change models, with descriptions and skills included.

Missing and guessed parameters

When a required parameter is missing from the prompt, Claude Opus is much more likely to recognize that and ask for it; Claude Sonnet might ask, especially when prompted to think before outputting a tool request, but it might also infer a reasonable value. The docs show a get_weather call where Claude guessed "New York, NY" for a location the user never gave, and say the behavior is not guaranteed, especially for more ambiguous prompts and less capable models. Anthropic's sample prompt for parallel calls also tells Claude never to use placeholders or guess missing parameters. Our rule: if a wrong guess is costly, say so in the description and the system prompt, and validate the input in code before acting on it.

Symptom and first fix

What tool-call metrics (invalid-parameter errors, redundant calls) say about a description is covered in Evaluate the tool set.

Anthropic's own results show the payoff. Claude Sonnet 3.5 reached state-of-the-art SWE-bench Verified performance after precise refinements to tool descriptions. In the multi-agent research system, a tool-testing agent that rewrote a flawed MCP tool's description produced a 40% decrease in task completion time for later agents using the new description. When Claude's web search tool launched, Claude was needlessly appending 2025 to the query parameter until Anthropic improved the tool description.

Controlling tool choice

Tested in: CCAR-F 2.3-K4, 2.3-S4, 2.3-S5, 4.3-K2, 4.3-S2, 4.3-S3, 1.4-S1 (contrast with enforced order), Q1, APPX-TECH-5, APPX-INSCOPE-13 · CCDV-F D2.3 Claude API Mechanics, D8.1 Tool Implementation, D5.3 Model Selection and Tradeoffs, D5.4 Cost and Token Management

tool_choice decides whether Claude may, must, or must not call a tool on a request. The API accepts four values.

The request forms, including the parallel-call switch covered in Parallel tool calls:

{"tool_choice": {"type": "auto"}}
{"tool_choice": {"type": "any"}}
{"tool_choice": {"type": "tool", "name": "get_weather"}}
{"tool_choice": {"type": "none"}}
{"tool_choice": {"type": "auto", "disable_parallel_tool_use": true}}
{"tool_choice": {"type": "any", "disable_parallel_tool_use": true}}

A forced call on a model that supports it. This is the docs' own example, and it uses claude-opus-5: the newest models reject forcing (see below).

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  tools: [
    {
      name: "get_weather",
      description: "Get the current weather in a given location",
      input_schema: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA"
          }
        },
        required: ["location"]
      }
    }
  ],
  tool_choice: { type: "tool", name: "get_weather" },
  messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
});

What forcing changes

• No preamble. With any or tool, the API prefills the assistant message to force a tool call, so Claude writes no natural-language explanation before the tool_use block, even if explicitly asked to (the docs say testing shows this should not reduce performance). If you want an explanation and a specific tool, keep auto and put an explicit instruction in the user message, as in the docs' example What's the weather like in London? Use the get_weather tool in your response.
• Guarantee a call and its shape. On models that support forced tool use, any plus strict: true on your tools guarantees both that a tool is called and that its input follows your schema. any alone guarantees the call, not the shape.
• Caching. Changing tool_choice invalidates cached message blocks; tool definitions and the system prompt stay cached. If tool_choice must change mid-conversation, place cache breakpoints before the change.

Where forced tool use is rejected (as of September 2026)

Where forced tool use is unsupported, any and tool fail while auto and none keep working.

The Claude Opus 5.5 migration guide shows the replacement for a forced call: strict tools, auto, and the instruction moved into the user message. The snippet assumes an existing tools list that contains a get_weather tool, like the forced example above.

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # strict tool use: every call matches the tool's input_schema
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

The release notes date the change: Claude Fable 5.1 and Claude Mythos 5.1 on September 1, 2026, and Claude Opus 5.5, which launched on September 22, 2026. Manual extended thinking itself is deprecated on Claude Opus 4.6 and Claude Sonnet 4.6 and rejected with a 400 by Claude 4.7 and later models; Claude Sonnet 4.5, Claude Opus 4.5 and Claude Haiku 4.5 support only extended thinking. On the newest models thinking is already on and needs no configuration. Thinking modes are taught in Extended thinking, adaptive thinking and effort.

Other places a forced choice is refused:

• A tool choice cannot name the computer use or browser use toolset or one of its members; use auto, any or none.
• tool_choice cannot name a tool whose allowed_callers omits "direct". The fix the docs give is to add "direct" to that tool's allowed_callers, or remove the tool from tool_choice and let Claude invoke it from code. Nor can you force programmatic calling of a specific tool through tool_choice.
• An on-demand compaction request must leave out a tool_choice of any or tool, and a max_tokens: 0 request is rejected when combined with any or tool.

What each choice costs

Supplying tools makes the API add a tool-use system prompt, whose size depends on the model and on tool_choice (the table assumes at least one tool is provided). Those tokens come on top of the other tool tokens: the tools parameter (names, descriptions and schemas), tool_use blocks and tool_result blocks, all billed as normal input and output tokens. Server tools can add usage-based charges as well (web search, for example, charges per search). With no tools, none adds 0 system prompt tokens.

Our reading of the models in this table: forcing adds about 90 to 130 system prompt tokens per request (406 minus 286 is 120 on Claude Opus 5; 588 minus 496 is 92 on the 4.5 models; our arithmetic). The docs' table also lists older retired models, not shown here: Claude Opus 4.1, Claude Sonnet 4 and Claude Haiku 3.5 (retired except on Bedrock and Google Cloud) and Claude Opus 4 (retired except on Google Cloud). This table serves CCDV-F D5.4 Cost and Token Management; CCAR-F lists rate limiting, quotas and API pricing calculations as out of scope.

Recipes the exams test

Traps.

• auto does not guarantee a tool call; the model may return text instead (4.3-K2). On the exam, and on models that support forcing, if the task needs a call every time the answer is any or a forced tool, not stronger prompt wording: the docs say a system prompt line steers triggering, and that to require a tool call rather than rely on prompting you set tool_choice. On Claude Opus 5.5, Claude Fable 5.1 and Claude Mythos 5.1, use auto with strict tool use and say in the prompt when the tool applies (table above).
• any does not pick the tool for Claude. To make a particular tool run, force it by name.
• A forced call arrives with no explanatory text, so code that expects prose before the tool call will not find any.
• Forcing a tool while manual extended thinking is on is an error, not a silent downgrade.

Forcing a first call is not the same as enforcing an order. tool_choice is set per request, so forcing extract_metadata makes it run on that request, and the guide has you process the later steps in follow-up turns (2.3-S4). When a sequence must hold for critical business logic, CCAR-F sample question 1 keys a programmatic prerequisite that blocks lookup_order and process_refund until get_customer has returned a verified customer ID because, in Anthropic's rationale for that question in the CCAR-F guide, "programmatic enforcement provides deterministic guarantees that prompt-based approaches cannot". The objective behind it is 1.4-S1. Our rule: use tool_choice to make one step happen on one request; use a code gate or hook when a rule must hold across the whole conversation (see Hooks in the SDK).

Parallel tool calls

Tested in: CCAR-F 1.3-S3, EX4-STEP2 · CCDV-F D8.1 Tool Implementation, D2.3 Claude API Mechanics

By default, Claude may call several tools in a single response, and Claude 4 and later models make parallel calls by default when a request benefits from more than one tool. The response then has stop_reason: "tool_use" and can contain several tool_use blocks in one assistant turn.

Running the calls

The API does not prescribe an execution order. You can run the calls concurrently (asyncio.gather, Promise.all), one by one in the order they appear, or in any mix that suits your tools.

Decide. Independent, read-only operations are usually safe to run in parallel for lower latency. Tools with side effects, shared state or ordering requirements may be better run sequentially. Whatever you choose, the reply format below does not change.

The Agent SDK makes this choice for you: read-only tools such as Read, Glob, Grep and MCP tools marked read-only can run concurrently, while state-modifying tools such as Edit, Write and Bash run sequentially. SDK custom tools run sequentially unless you set readOnlyHint: true in their annotations (the fifth argument to tool() in TypeScript, the annotations keyword of @tool in Python). The annotation is metadata, not enforcement: a tool marked read-only can still write if its handler does, so keep the hint accurate.

from claude_agent_sdk import tool, ToolAnnotations

@tool(
    "get_temperature",
    "Get the current temperature at a location",
    {"latitude": float, "longitude": float},
    annotations=ToolAnnotations(readOnlyHint=True),  # Lets Claude batch this with other read-only calls
)
async def get_temperature(args):
    return {"content": [{"type": "text", "text": "..."}]}

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

tool(
  "get_temperature",
  "Get the current temperature at a location",
  { latitude: z.number(), longitude: z.number() },
  async (args) => ({ content: [{ type: "text", text: `...` }] }),
  { annotations: { readOnlyHint: true } } // Lets Claude batch this with other read-only calls
);

Returning the results

Return one tool_result for each tool_use block, all together in the next user message, matched by tool_use_id and placed before any text in that message. The docs name incorrect result formatting as the most common reason Claude stops making parallel calls: sending each result in its own user message "teaches" Claude to avoid parallel calls (Parallel tool use).

// Wrong: separate user messages reduce parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]
// Correct: one user message with all results maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]

If you decide not to run one of the calls, for example because you ran the batch sequentially and an earlier call failed, you still owe it a result: is_error: true and a short explanation.

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "Not executed: the preceding write_file call failed."
}

The loop in How tool use works already follows both rules: it collects every result for a turn into one list, including is_error results for calls that failed, and sends one user message.

Encouraging, limiting and disabling parallel calls

To encourage parallel calls, the parallel tool use docs suggest this system prompt line for Claude 4 and later models: "For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially." Anthropic's prompting best practices say parallel calling is steerable and that their sample prompt can boost it to about 100%. That longer version also tells Claude to keep dependent calls sequential and never to guess missing parameters:

<use_parallel_tool_calls>
If you intend to call multiple tools and there are no dependencies between the tool
calls, make all of the independent tool calls in parallel. Prioritize calling tools
simultaneously whenever the actions can be done in parallel rather than sequentially.
For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into
context at the same time. Maximize use of parallel tool calls where possible to increase
speed and efficiency. However, if some tool calls depend on previous calls to inform
dependent values like the parameters, do NOT call these tools in parallel and instead
call them sequentially. Never use placeholders or guess missing parameters in tool
calls.
</use_parallel_tool_calls>

If dependent calls still show up in the same batch, the parallel tool use docs suggest adding "Only batch tool calls that are independent of each other." to the system prompt. If a parallel call fails because its prerequisite had not run yet, return is_error: true with the natural error message and Claude reissues the call on the next turn. To tone parallel execution down in general, the best-practices sample is "Execute operations sequentially with brief pauses between each step to ensure stability."

To turn parallel calls off, set disable_parallel_tool_use: true inside the tool_choice object. It is not a top-level request parameter.

The second row needs forced tool choice to be accepted: as of September 2026, Claude Opus 5.5, Claude Fable 5.1 and Claude Mythos 5.1 reject any and tool, and so does any request with manual extended thinking (thinking: {type: "enabled"}) (see Controlling tool choice).

Three rules catch people out:

• The flag must be set on the request that returns the tool_use. Setting it on a later request has no effect on calls already made.
• Changing it invalidates the messages cache.
• Programmatic tool calling does not support disable_parallel_tool_use: true.

Model behavior varies (as of September 2026): Claude Fable 5.1 may issue fewer parallel calls than earlier models in long agent loops, such as custom coding agents, bash or text editor harnesses and computer use, where the next reads are only implied. Standard function calling is unaffected. For that case the best-practices page says to send the parallel-calls instruction as a turn-scoped system message after each round of tool results (turn-scoped system messages are in beta and need the mid-conversation-system-clear-at-2026-08-21 header).

Toolsets are stricter

When Claude returns several computer use or browser use member calls in one turn (a batch action), run them sequentially in the order they appear and stop at the first failure. Every block still gets a result, and each member result echoes its toolset_name: the normal result for each action that succeeded, is_error: true with a description for the one that failed, and is_error: true with the exact text the tool defines for each skipped call: Not executed: an earlier computer action in this turn failed. for computer use, Not executed: an earlier action in this turn failed. for browser use. A request that leaves any block in the batch unanswered is rejected. If a person must confirm consequential actions, check before each block runs, because one batch can complete a multistep action within a single turn.

A server tool and a client tool in one group

When Claude calls a server tool and a client tool in the same parallel group, the API does not run the server tool yet. The response comes back with stop_reason: "tool_use", not "pause_turn", and the server tool appears as a server_tool_use block with no matching result block. The docs say there is no other marker: detect the state by that unmatched id. An mcp_tool_use block from the MCP connector behaves the same way.

{
  "stop_reason": "tool_use",
  "content": [
    {"type": "text", "text": "I'll fetch the article and check your system at the same time."},
    {"type": "server_tool_use", "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA", "name": "web_fetch", "input": { "url": "https://example.com/article" }},
    {"type": "tool_use", "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk", "name": "run_command", "input": { "command": "uname -a" }}
  ]
}

The only valid follow-up is a user message containing nothing but the client tool_result blocks, one per client tool_use, sent with the same tools array; the API then runs the deferred server tool at the start of that request. Text after those results ends the assistant turn and fails with a 400 that names the unresolved server tool. To give Claude more input, send it as a separate user message after the turn completes.

{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk", "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"}
  ]
}

Parallel subagents

The same mechanism drives multi-agent fan-out. The CCAR-F guide tests (1.3-S3) spawning parallel subagents "by emitting multiple Task tool calls in a single coordinator response rather than across separate turns", and preparation exercise 4 asks you to measure the latency gain against sequential execution (EX4-STEP2). In Anthropic's multi-agent research system, two kinds of parallelism (the lead agent starting 3 to 5 subagents at once, and each subagent using 3 or more tools at once) cut research time by up to 90% for complex queries. Orchestration design is in Multi-agent orchestration.

Traps. The plausible wrong answers follow from the rules above:

• Spawning independent subagents one per turn. 1.3-S3 wants multiple Task calls in a single coordinator response.
• Returning parallel results in separate user messages. The docs say this teaches Claude to avoid parallel calls.
• Putting disable_parallel_tool_use at the top level of the request, or on a later request. It belongs inside tool_choice on the request that returns the tool_use.
• Running a computer use or browser use batch concurrently. Those batches run in order and stop at the first failure.

Returning tool results and errors

Tested in: CCAR-F 1.1-K2, 1.1-S2, 2.2, 5.1-K3, 5.1-S3, 5.3-K2, 5.3-K4, 5.3-S2, APPX-INSCOPE-7, EX1-STEP3, Q8 · CCDV-F D8.1 Tool Implementation, D4.1 Debugging and Error Handling, D7.1 AI Application Security

A client tool's output goes back to Claude as a tool_result content block inside a new message with role user. Why that growing history matters (CCAR-F 1.1-K2 and 1.1-S2) is covered in The client-tool round trip; this section covers the result's fields, the ordering rules the API enforces, how to report a failure, and what a result should contain.

Ordering rules the API enforces

1. Adjacent. tool_result blocks must immediately follow their tool_use blocks in the message history. No message may sit between the assistant's tool_use message and your tool_result message.
2. Results first. In that user message, the docs put it bluntly: tool_result blocks "must come FIRST in the content array. Any text must come AFTER all tool results." (Handle tool calls) Text before a result returns a 400.
3. Results only, in mixed turns. If the same assistant turn also called a server tool that has no result yet, the user message may contain only tool_result blocks (the full case is in A server tool and a client tool in one group).

Skip a result, put content before the results, or send a next message with no tool_result blocks at all, and the API answers with tool_use ids were found without tool_result blocks immediately after. The fix is one result per tool_use, placed before any text.

Text after the results is accepted for a client-only turn, but Anthropic's stop-reason guide lists "Never add text blocks immediately after tool results" as a best practice: it teaches Claude to expect user input after every tool use, and it is a common cause of empty end_turn responses. Programmatic tool calls and mixed server and client turns forbid the text entirely.

Two more continuation rules:

• Thinking blocks. When thinking is on, send the whole assistant message back unchanged and then append your tool_result. The whole tool-use loop counts as one assistant turn, and within it passing thinking blocks back is required; a modified thinking block gets a 400.
• Truncated calls. If a response hits max_tokens with an incomplete tool_use block, retry the request with a higher max_tokens to get the full call.

Reporting a failure with is_error

For an execution error such as a network failure, put the error message in content and set is_error: true. Claude folds it into its reply, and can retry with corrected input, ask the user for clarification, or explain the limitation.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Write the message for Claude, not for a log file. The Handle tool calls page says: "Instead of generic errors like "failed", include what went wrong and what Claude should try next (for example, "Rate limit exceeded. Retry after 60 seconds.")." Anthropic's tool-design post makes the same point: "you can prompt-engineer your error responses to clearly communicate specific and actionable improvements, rather than opaque error codes or tracebacks."

When a call is invalid, for example missing a required parameter, you can answer it with an is_error result such as Error: Missing required 'location' parameter; Claude retries 2 to 3 times with corrections before apologizing to the user. During development, an invalid call usually means the description lacked information, so the docs' best bet is a more detailed description. To eliminate invalid calls, the docs point to strict: true, which prevents missing parameters and type mismatches; the caveats on that guarantee are in Defining a tool.

Who sets the flag depends on the layer, and the spelling changes with it:

Decide. Catch the error yourself whenever the raw exception text would not tell Claude what to do next; the Agent SDK docs recommend exactly that, and the example under Structured error metadata: the exam guide's convention shows how.

Error categories the exam expects

CCAR-F 2.2 asks you to return errors the agent can act on. The guide distinguishes four kinds of error (2.2-K2), wants retryable and non-retryable errors told apart so the agent does not waste retries (2.2-K4), and rejects uniform responses such as a generic "Operation failed", which leave the agent unable to choose a recovery (2.2-K3).

The metadata the guide asks for in 2.2-S1 (errorCategory, isRetryable and a human-readable description) is its own convention, not a field of the Claude API or the MCP spec, and it goes inside the error content. The guide is also inconsistent about how many categories there are and how the retry flag is spelled. Both points, with worked examples, are in Structured error metadata: the exam guide's convention.

Access failure or valid empty result

A query that ran and matched nothing is a success; a query that could not run is a failure. CCAR-F names the difference in three places (2.2-S4, 5.3-K2, 5.3-S2): an access failure needs a retry decision, while a valid empty result is a successful query with no matches, and reporting them differently lets the coordinator decide what to do.

For your own search tools, Anthropic's search results guide says that when a search fails or returns nothing, you should return a plain text block describing the outcome, such as No results found., instead of raising an error. That advice covers both cases and is about the content format, so the text itself must say which case happened; for an execution failure the Messages API still expects is_error: true (our reading of the two pages together).

MCP writes the same principle into its resources spec; see A failure is not an empty answer.

Traps. CCAR-F sample question 8 has a web search subagent that times out. The correct option (A) returns structured error context to the coordinator: the failure type, the attempted query, any partial results and potential alternative approaches. Catching the timeout and returning an empty result marked as successful (option C) is wrong; the guide's rationale: "Option C suppresses the error by marking failure as success, which prevents any recovery and risks incomplete research outputs." (CCAR-F guide) Retrying and then returning only a generic "search unavailable" status (option B) hides the context the coordinator needs, and terminating the whole workflow (option D) is the opposite anti-pattern, which 5.3-K4 also names. How errors travel between agents is taught in Error propagation in multi-agent systems.

Results carry untrusted content

Content that tools return (files, web pages, search results) is untrusted data and can carry an indirect prompt injection. Anthropic's guidance:

• Deliver third-party content inside tool_result blocks, never in system prompts or plain user text blocks.
• Tell Claude in the system prompt that content returned from tools, documents or searches is untrusted data and must never override the system prompt or the user's original request.
• Do not put your own instructions in tool results. The jailbreak mitigation guide explains: "Because Claude treats tool-result content as untrusted data, instructions you place there may be ignored or flagged as a potential injection." Send them in a user turn that follows the tool_result block or, on models that support it (as of September 2026, not Claude Sonnet 5), in a mid-conversation system message.
• JSON-encode untrusted strings inside the result, so escaping gives unambiguous delimiters between the payload and the surrounding structure.
• Screen tool output with a small classifier call, for example Claude Haiku 4.5 with structured outputs, before returning it.

The defenses around this (least privilege, guardrail layers) are in Prompt injection.

Keep results small

The API does not truncate tool results; an oversized request is rejected, so truncate large outputs in your application. Anthropic's tool-design post says Claude Code restricts tool responses to 25,000 tokens by default, and the current Claude Code docs give the same 25,000-token default maximum for MCP tool output (the controls are in Output size, timeouts and reconnection). Results also pile up: CCAR-F 5.1-K3 describes order lookups returning 40+ fields when only 5 are relevant, and 5.1-S3 asks you to trim verbose outputs to the relevant fields before they accumulate in context. Designing lean responses is covered in Shape tool responses; managing what is already in a long conversation is covered in Preserving critical information in long conversations.

Anthropic-defined tools

Tested in: CCDV-F D8.1 Tool Implementation (client-side vs. server-side tools), D2.3 Claude API Mechanics · CCAR-F 4.5-K3, APPX-TECH-6; computer use is out of scope for CCAR-F (APPX-OUTSCOPE-8)

Anthropic provides two kinds of ready-made tools. Anthropic-schema client tools have a published schema, but your application executes them. Server tools run on Anthropic's infrastructure, and you never build a tool_result for them. Most tools of both kinds carry a _YYYYMMDD suffix in their type string, and older versions stay available so existing integrations keep working.

The catalog (as of September 2026)

Server tools

Anthropic-schema client tools (your application executes every call)

Declaring them is one short entry each:

{"type": "web_search_20260318", "name": "web_search", "response_inclusion": "excluded"}
{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 10, "citations": {"enabled": true}, "max_content_tokens": 100000}
{"type": "code_execution_20260120", "name": "code_execution"}
{"type": "bash_20250124", "name": "bash"}
{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000}
{"type": "memory_20250818", "name": "memory"}
{"type": "computer_toolset_20260801", "configs": {"zoom": {"enabled": false}}, "cache_control": {"type": "ephemeral"}}
{"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"}

With web_search_20260209, web_fetch_20260209 or later, you do not need to declare code execution: the API provisions it for dynamic filtering. If you do declare it, use code_execution_20260120 or later, because the API rejects older code execution versions alongside those web tool versions. Those web tool versions also change the allowed_callers default; see Programmatic tool calling.

Why prefer an Anthropic-schema tool. When you need memory, shell commands, file editing, or desktop or browser control, prefer the Anthropic-schema tool over defining your own equivalent. Its schema is trained in: Claude has been optimized on thousands of successful trajectories that use those exact signatures, so it calls them more reliably and recovers from errors more gracefully than it would with a custom tool that does the same thing.

How a server-tool turn comes back

A server tool call appears as a server_tool_use block whose id starts with srvtoolu_, followed in the same assistant turn by its result block (for example web_search_tool_result), paired by tool_use_id. You do not answer it with a tool_result. Claude handles server tool errors itself; for web search, web fetch and tool search the API still returns HTTP 200 with the error inside the result block. One exception to watch: if an administrator has disabled web search for the organization in the Console, the request fails with a 400 invalid_request_error instead of an in-result error code.

On a long-running turn the server-side loop can pause and return stop_reason: "pause_turn". Pass the paused response back as-is in a follow-up request, include the same tools (a paused turn can end on a server tool call that has not run yet), and cap the number of continuations like any retry loop, because a continued turn can pause again. Any agent loop that uses server tools should handle pause_turn.

def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
    messages = [{"role": "user", "content": user_query}]

    for _ in range(max_continuations):
        response = client.messages.create(
            model="claude-opus-5-5", max_tokens=4096, messages=messages, tools=tools
        )

        if response.stop_reason != "pause_turn":
            # Claude finished processing - return the final response
            return response

        # pause_turn: replace the full message list to maintain alternating roles
        messages = [
            {"role": "user", "content": user_query},
            {"role": "assistant", "content": response.content},
        ]

    # Reached max continuations - return the last response
    return response

Do not confuse the two stops. A pause_turn response never leaves a client tool_use waiting; you continue it by re-sending the content. A tool_use stop is continued by sending tool_result blocks, including the mixed case where a server tool is still pending (see Parallel tool calls). In both cases the API runs the pending server tool at the start of the next request.

Batches. All server tools, including MCP connectors, the advisor and tool search, work in Message Batches requests, and the batch loop runs more iterations per turn than a synchronous request before it returns pause_turn. A paused batch result is continued by a follow-up request, batch or synchronous.

Server tool details worth knowing

Two security notes. Enabling web fetch where Claude reads untrusted input alongside sensitive data creates an exfiltration risk; mitigations include disabling the tool, capping max_uses, and restricting allowed_domains. And if you give Claude both server-side code execution and your own client-side bash tool, Claude can confuse the two environments, so make clear in the system prompt that state does not carry over between them.

Client tools you execute: your security job

Anthropic publishes the schema, but the blast radius is yours:

• Bash. Validate commands with an allowlist, not a blocklist, and treat that check as a tripwire: the real control is running the session isolated, in a container or VM, as a least-privileged user, treating every command as untrusted input. The session cannot run interactive programs such as vim, less or password prompts.
• Text editor. Make each str_replace match exactly one location, validate paths against traversal, and keep backups. text_editor_20250429 removed undo_edit.
• Memory. Validate every path in every command so a request like /memories/../../secrets.env cannot escape the directory. The API adds a memory protocol to the system prompt when the tool is present, and the tool works on all Claude 4 and later models.
• Output size. Truncate large command output yourself; see Keep results small.

Computer use and browser use. The current toolsets are single tools entries with no name; each member call carries a toolset_name, which your tool_result must echo. Claude Opus 5.5 on the Claude API and Google Cloud accepts only computer_toolset_20260801 and rejects computer_20251124. The toolset entries reject strict, input_examples, entry-level defer_loading, code execution callers, the legacy fine-grained streaming header, and a tool_choice of type tool that names the toolset or a member. Declaring the computer use toolset with its default members adds about 4,500 input tokens. Anthropic's precautions: a dedicated minimal-privilege VM or container, no sensitive data, domain allowlists, and human confirmation for consequential actions; Anthropic also runs classifiers over what the tools return, such as screenshots, to flag potential prompt injections. CCAR-F lists computer use as out of scope.

Programmatic tool calling

Programmatic tool calling (PTC) lets Claude write code that calls your tools inside a code execution container, instead of a round trip through the model for every call. It needs code_execution_20260120 or later; you opt a tool in with allowed_callers: ["code_execution_20260120"], choosing that or ["direct"] per tool rather than both. "code_execution_20260521" is also accepted in allowed_callers and is interchangeable with "code_execution_20260120"; response blocks always tag the caller as code_execution_20260120. For your own tools and the earlier web tool versions, omitting allowed_callers means ["direct"]. The _20260209 and later web search and web fetch tools instead default to the code execution caller only. On models that do not support programmatic tool calling, such as Claude Haiku 4.5, they need "allowed_callers": ["direct"], or the request returns a 400.

"tools": [
  {"type": "code_execution_20260120", "name": "code_execution"},
  {
    "name": "query_database",
    "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
    "input_schema": {
      "type": "object",
      "properties": {"sql": {"type": "string", "description": "SQL query to execute"}},
      "required": ["sql"]
    },
    "allowed_callers": ["code_execution_20260120"]
  }
]

When Claude's code calls the tool, execution pauses and the API returns an ordinary tool_use block whose caller field says {"type": "code_execution_20260120", "tool_id": "srvtoolu_..."} (a direct call says {"type": "direct"}). Your result resumes the code, and the intermediate results never enter Claude's context. Tools are exposed to the code as async Python functions, so Claude can fan out with asyncio.gather.

Decide. PTC pays off for fan-out across many items, large results that code can filter, and agentic search. It does not help strictly sequential calls where each depends on Claude's reasoning, a few small calls, or calls that need user feedback in between. Anthropic's measurements: roughly 38% fewer billed input tokens on a 75-tool project-management agent benchmark with no change in accuracy; typical token savings of 20% to 40% across production traffic for requests with 10 to 49 tool definitions; but on τ²-bench, where each turn makes one or two sequential calls, unchanged scores at roughly 8% more cost. Because Claude parses the results in code, document each tool's output format (JSON structure and field types) in its description.

allowed_callers is not a security boundary: be ready to handle a direct tool_use for any tool you define.

The think tool: prefer extended thinking

An Anthropic engineering post introduced a "think" tool that obtains no new information and only appends a thought to a log. The post now carries a December 15, 2025 update recommending extended thinking instead of a dedicated think tool in most cases, so reach for extended thinking first and do not present the think tool as current best practice.

Designing a tool set

Tested in: CCAR-F 2.1-S3, 2.3-K1, 2.3-K2, 2.3-K3, 2.3-S1, 2.3-S2, 2.3-S3, APPX-INSCOPE-4 · CCDV-F D8.1 Tool Implementation (tool set construction, approval patterns), D7.2 Guardrails and Safe Deployment · CCAR-P 3.1, 3.8, 5.1

Anthropic calls tools "a new kind of software which reflects a contract between deterministic systems and non-deterministic agents" (Writing effective tools for agents). Its Building effective agents post adds a rule of thumb: plan to invest as much effort in the agent-computer interface (ACI) as teams put into human-computer interfaces. Designing a tool set means making the ACI decisions: how many tools an agent sees, how they overlap, what they are called, what they return and what they are allowed to do.

Fewer, higher-level tools

More tools do not always mean better results. A common error Anthropic reports is tools that merely wrap existing software functions or API endpoints, whether or not those suit an agent. Its recommendation is "building a few thoughtful tools targeting specific high-impact workflows", then scaling up from there. Anthropic's own before-and-after examples (Writing effective tools for agents, plus the define-tools docs for the last row):

Anthropic's post on building agents that reach production systems with MCP sums it up: "Fewer, well-described tools consistently outperform exhaustive API mirrors." For very large APIs it points to a thin surface that accepts code; its example is Cloudflare's MCP server, where two tools (search and execute) cover about 2,500 endpoints in roughly 1K tokens.

Split or consolidate

The advice can look contradictory. CCAR-F 2.1-S3 splits a generic analyze_document into extract_data_points, summarize_content and verify_claim_against_source, while the docs group create_pr, review_pr and merge_pr into one tool. Both rest on the same principle: every tool needs a clear, distinct purpose, because overlapping or vague tools confuse agents.

Decide. Our reconciliation of the guide and the docs (neither rule is absolute):

• Consolidate when several low-level calls or CRUD variants serve one purpose: fewer, higher-level tools.
• Split when one vague tool hides several jobs with different inputs and outputs, or overlaps another tool.
• Constrain when a tool is more general than the job: CCAR-F 2.3-S2 replaces a generic fetch_url with load_document, which validates document URLs. Anthropic's Building effective agents post names the general practice poka-yoke: change the arguments so mistakes are harder. In its SWE-bench agent, changing the tool to always require absolute file paths fixed the model's relative-path errors.

Namespacing

When tools span services or resources, prefix their names: by service (asana_search, jira_search) or by resource (asana_projects_search, asana_users_search). The docs' examples are github_list_prs and slack_send_message, and they stress it for tool search, where one consistent prefix lets a single search match the whole group. Anthropic found that choosing prefix or suffix namespacing had non-trivial effects on its tool-use evaluations, and that the effects vary by model, so choose by your own evaluations. Claude Code and the Agent SDK namespace MCP tools for you; the pattern is in Names, permissions and hooks.

How many tools per agent

Several numbers circulate. They are different claims, not one threshold:

For the exam, carry the guide's lesson, which is about selection reliability rather than a numeric cutoff: each agent should see the few tools its role needs.

Scope tools to each agent's role

The CCAR-F guide builds 2.3 around role-scoped access:

• Agents with tools outside their specialization tend to misuse them, as when a synthesis agent attempts web searches (2.3-K2).
• Give each agent only the tools its role needs, with limited cross-role tools for specific high-frequency needs (2.3-K3, 2.3-S1).
• For example, give the synthesis agent a scoped verify_fact tool, while complex cases still route through the coordinator (2.3-S3).

CCAR-F sample question 9 tests exactly this. A synthesis agent hands every verification back to the coordinator, which adds 2 to 3 round trips per task and 40% latency, although 85% of the verifications are simple fact-checks. The keyed answer (A) gives it a scoped verify_fact tool for simple lookups while complex verifications still go through the coordinator; the rationale: "Option A applies the principle of least privilege by giving the synthesis agent only what it needs for the 85% common case (simple fact verification) while preserving the existing coordination pattern for complex cases." Option C, access to all web search tools, is the over-provisioning trap: "Option C over-provisions the synthesis agent, violating separation of concerns." (CCAR-F guide)

In the Agent SDK, the scope lives in each subagent's definition:

• AgentDefinition.tools lists the allowed tools. If you omit it, the subagent inherits every tool available to subagents, so (our inference) leaving it out over-provisions by default.
• A tool left out of the list is simply absent from the subagent's session: no permission prompt, no error.
• The docs' common combinations: read-only analysis gets Read, Grep, Glob; test execution gets Bash, Read, Grep; code modification gets Read, Edit, Write, Grep, Glob.
• A bare-name deny rule such as "Bash" in disallowed_tools removes the tool definition so Claude cannot even attempt it; a scoped rule such as "Bash(rm *)" only denies matching calls. allowed_tools does not constrain bypassPermissions mode, so block tools there with disallowed_tools. (These are the Python option names; TypeScript uses allowedTools and disallowedTools.)

Mechanics are in Subagents in the SDK and Permissions and enforcement. Specialization that improves tool selection or task focus is also one of the three situations where Anthropic finds multiple agents consistently outperform a single agent, alongside context pollution and work that can run in parallel (Building multi-agent systems); the same post's advice to consider tool search before splitting is in the table above.

Least privilege: remove before you guard

CCAR-P sample question 1 describes a support agent that can read tickets, draft replies, issue refunds and delete user accounts, when staff only ever need the first two. The keyed answer removes the refund and delete tools. The rationale from the CCAR-P guide: "Least privilege means removing capabilities the role does not require, eliminating the attack surface rather than monitoring or guarding it. Logging (A) and confirmations (C) are detective/compensating controls, not removal of unnecessary privilege; model size (D) is unrelated to authorization scope."

Anthropic's injection guidance gives the same reason from the security side: apply least privilege so a successful injection does minimal damage, by withholding secrets Claude does not need, sandboxing tools, and scoping permissions as narrowly as possible.

Decide. Our ordering, derived from the CCAR-P rationale and the guide's constrained-tool example. Start at the top; the lower rungs are for capabilities the role genuinely keeps, and they add to the upper rungs rather than replace them:

1. Remove tools the role never needs.
2. Constrain the tools it keeps: narrower inputs, validated arguments, typed purpose-built tools.
3. Gate hard-to-reverse actions behind a confirmation or a hook.
4. Log for audit.

The rationale calls logging and confirmations "detective/compensating controls", so an answer that keeps an unneeded capability and adds either one is the trap. The wider treatment is in Least privilege for tools and agents.

Approval patterns for consequential actions

When an agent keeps a risky capability, the harness decides when a person must approve it. Anthropic's agent harness design post covers this under its third pattern, "Set boundaries carefully in your harness design", in the subsection on declarative tools. Three of its points bear on approvals:

• Promote actions to dedicated tools. A generic bash tool hands the harness only a command string; a dedicated, typed tool gives it an action-specific hook it can intercept, gate, render or audit. Actions that require a security boundary are natural candidates.
• Gate by reversibility. Hard-to-reverse actions, such as external API calls, can be gated by user confirmation.
• Let a tool ask. A tool can render as a modal that shows the user a question, offers options, or blocks the agent loop until the user responds.

The MCP spec sets the same human-in-the-loop expectation for clients; its list is under MCP primitives.

Where the gate lives:

The SDK checks permissions in a fixed order: hooks, deny rules, ask rules, permission mode, allow rules, then the canUseTool callback. Details: Permissions and enforcement and Hooks in the SDK.

Shape tool responses

What a tool returns is part of its design:

• High signal, meaningful names. Anthropic advises prioritizing contextual relevance over flexibility and avoiding low-level technical identifiers such as uuid, 256px_image_url and mime_type; fields like name, image_url and file_type are more likely to inform the agent's next action. Resolving arbitrary alphanumeric UUIDs to meaningful language, or even a 0-indexed ID scheme, significantly improved Claude's retrieval precision by reducing hallucinations. The define-tools docs still want stable, semantic identifiers (slugs or UUIDs) rather than opaque internal references, so (our reconciliation) keep the IDs Claude needs for follow-up calls and make the rest readable.
• Let the agent choose verbosity. A response_format enum with "concise" and "detailed" lets the agent control detail; in Anthropic's Slack example, concise responses used about a third of the tokens (72 versus 206).
• Bound the size. Use some combination of pagination, range selection, filtering and truncation with sensible default parameter values. If you truncate, steer the agent with helpful instructions, for example to make several small targeted searches instead of one broad one. The default output limits are in Keep results small and Output size, timeouts and reconnection.
• Pick the format by evaluation. XML, JSON or Markdown can each score differently; there is no one-size-fits-all format.
• Label risk. For MCP servers, tool annotations disclose which tools need open-world access or make destructive changes; see MCP primitives.

Progressive discovery with tool search

CCAR-P asks you to "Evaluate progressive discovery vs. monolithic context strategy" (3.8) and to evaluate tool and agent configuration for capability bloat (3.1) (CCAR-P guide). In our mapping of the guide's terms onto the docs, monolithic means every tool definition is loaded into Claude's context window up front, and progressive discovery means tool search. A typical five-server setup (GitHub, Slack, Sentry, Grafana, Splunk) can take about 55K tokens of definitions, and Anthropic has seen definitions consume 134K tokens before optimization. With tool search, Claude searches your catalog and loads only the tools it needs; the current docs say the search covers tool names, descriptions, argument names and argument descriptions (Anthropic's November 2025 advanced tool use post mentioned names and descriptions only). Tool search typically cuts that definition load by over 85 percent, loading only the 3 to 5 tools Claude needs for a given request.

A deferred tool alongside the regex tool search tool (definition as in the tool search docs):

{
  "tools": [
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
        },
        "required": ["location"]
      },
      "defer_loading": true
    }
  ]
}

The rules, as of September 2026:

In Anthropic's internal MCP evaluations, enabling tool search raised Claude Opus 4 from 49% to 74% and Claude Opus 4.5 from 79.5% to 88.1%.

Decide. The tool search docs list when to use it: 10 or more tools, more than 10K tokens of definitions, selection accuracy dropping as the tool set grows, several aggregated MCP servers (200+ tools), or a library that grows over time. They say standard tool calling (monolithic, in our mapping) fits better when you have fewer than 10 tools, every tool is used in every request, or the definitions are small (under 100 tokens total).

Context levers by bottleneck

Tool definitions and accumulated results both consume context. Anthropic's guidance matches each lever to a bottleneck and suggests an order for a high-volume agent:

Tools sit at the front of the cached prefix (tools, then system, then messages), so modifying a tool definition invalidates the entire cache; Anthropic's agent harness design post puts it plainly: "Tools sit in the cached prefix. Adding or removing one invalidates it." To add tools without that cost, defer them and let tool search append them inline instead of modifying the head of the tools array, or use the beta mid-conversation tool changes (mid-conversation-tool-changes-2026-07-01). Declare the full tool set in tools up front, marking tools that are not yet needed defer_loading: true, then offer or withdraw them with tool_addition and tool_removal blocks in a system message, so the tools array never changes. A tool_addition that names a tool not declared in tools returns a 400; carrying a tool's full definition inside a tool_addition block needs a separate beta header, inline-tools-2026-09-15. Caching mechanics are in Prompt caching; context editing is in Compaction, context editing and memory.

Evaluate the tool set

Test tools the way the agent will use them: realistic, multi-step tasks, measured on accuracy plus runtime per call and per task, number of tool calls, total tokens and tool errors. Read the metrics as design feedback: many redundant calls suggest adjusting pagination or token limits, and many invalid-parameter errors suggest clearer descriptions or better examples. Evaluation design is in Evaluating agents.

MCP architecture

Tested in: CCAR-F 2.4-K3, APPX-TECH-2, APPX-INSCOPE-6 · CCDV-F D8.2 MCP Server Development (client vs. server) · CCAR-P 3.7 · CCAO-F D5.2 (connectors)

The Model Context Protocol is an open standard for connecting AI applications to external data and actions, meant to replace fragmented, per-source integrations with a single protocol. Anthropic open-sourced it on November 25, 2024, calling it "a new standard for connecting AI assistants to the systems where data lives" (Anthropic announcement). The current protocol revision is 2026-07-28 (MCP versioning); the one before it was 2025-11-25 (2026-07-28 changelog).

Hosts, clients and servers

The MCP specification defines three roles that exchange JSON-RPC 2.0 messages. Hosts are "LLM applications that initiate connections", clients are "Connectors within the host application", and servers are "Services that provide context and capabilities".

An illustrative host with three servers (the transports and fan-out follow the architecture overview's typical cases):

+------------------------------ Host (for example Claude Code) ------------------------------+
|  full conversation history . consent prompts . one merged tool list for the model          |
|                                                                                            |
|     MCP client A                  MCP client B                    MCP client C             |
+--------|-----------------------------|-----------------------------------|-----------------+
         | stdio                       | Streamable HTTP                   | Streamable HTTP
         v                             v                                   v
   filesystem server             GitHub server (remote)             Sentry server (remote)
   (local subprocess)            typically serves many clients      typically serves many clients

Five facts from the architecture explain most exam questions:

1. One client per server. Each client "Communicates with exactly one server" (MCP architecture specification), and the host creates a separate client for each server it connects to (MCP architecture overview).
2. The host owns the conversation. The full conversation history stays with the host. Servers receive only the context they need, and by the spec's design principles they should not be able to read the whole conversation or "see into" other servers.
3. The host merges tools. The application fetches tools from every connected server and combines them into one registry the model can use. This matches the CCAR-F exam guide wording that tools from all configured MCP servers are "discovered at connection time and available simultaneously to the agent" (2.4-K3). Claude Code now defers full definitions by default; how that squares with the guide's wording is in What Claude sees once servers connect.
4. Fan-out differs by transport. Local stdio servers typically serve one client; remote Streamable HTTP servers typically serve many.
5. MCP stops at context exchange. The protocol does not dictate how the application uses the model or manages the context it provides.

Two layers: data and transport

MCP separates a data layer (the JSON-RPC protocol: discovery, primitives and notifications) from a transport layer (connection establishment, message framing and authorization). The transport layer abstracts communication details from the data layer, so the same JSON-RPC 2.0 message format is used across all transports; transports are covered in MCP transports.

All MCP messages MUST follow JSON-RPC 2.0 and be UTF-8 encoded. Three message kinds exist:

Each primitive follows the same method pattern: */list for discovery, a retrieval method (prompts/get, resources/read), and for tools an execution method (tools/call). The full method list is in MCP primitives.

Two protocol eras

MCP versions are date strings (YYYY-MM-DD) marking the last backwards-incompatible change. The 2026-07-28 versioning rules call the handshake-based revisions (2025-11-25 and earlier) "Legacy", the per-request-metadata revisions (2026-07-28 and later) "Modern", and an implementation that speaks both "Dual-era". The two eras differ in ways that exam items and real configurations both touch:

A legacy connection opens with this handshake (trimmed from the 2025-11-25 lifecycle page, which also shows tasks capabilities and extra clientInfo/serverInfo fields such as title, description and icons). Client to server:

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-11-25",
              "capabilities": { "roots": { "listChanged": true }, "sampling": {}, "elicitation": { "form": {}, "url": {} } },
              "clientInfo": { "name": "ExampleClient", "version": "1.0.0" } } }

Server to client, then the client's notification:

{ "jsonrpc": "2.0", "id": 1,
  "result": { "protocolVersion": "2025-11-25",
              "capabilities": { "logging": {}, "prompts": { "listChanged": true },
                                "resources": { "subscribe": true, "listChanged": true },
                                "tools": { "listChanged": true } },
              "serverInfo": { "name": "ExampleServer", "version": "1.0.0" },
              "instructions": "Optional instructions for the client" } }

{ "jsonrpc": "2.0", "method": "notifications/initialized" }

A modern request needs no handshake because it describes itself (MCP architecture overview):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "weather_current",
    "arguments": { "location": "San Francisco", "units": "imperial" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": { "elicitation": {} }
    }
  }
}

Security principles the host enforces

The spec puts consent and safety on the host, because the protocol cannot enforce them itself:

• Users must explicitly consent to and understand all data access and operations. Hosts must obtain explicit user consent before exposing user data to servers and before invoking any tool.
• Tools represent arbitrary code execution and must be treated with appropriate caution. Descriptions of tool behavior, such as annotations, should be considered untrusted unless obtained from a trusted server.
• MCP "cannot enforce these security principles at the protocol level" (MCP specification); implementors SHOULD build consent and authorization flows.
• clientInfo and serverInfo are self-reported by the sender and not verified by the protocol. They are meant for display, logging and debugging, and implementations SHOULD NOT rely on them for security decisions.

Prompt injection through tool results and malicious servers is covered in Security, Safety and Governance.

Where MCP runs in Claude products

The same protocol appears across Claude's surfaces, with different ways to add a server and different transport limits (as of September 2026):

For the CCAO-F objective on connectors (D5.2 names Google Drive and Gmail), the facts that matter are these: connectors inherit each person's permissions from the connected service, and they work across Claude, Claude Desktop, Claude Code and the API through the MCP connector. On Team and Enterprise plans, Owners can restrict connector actions organization-wide by setting each permission category or individual permission to Always allow, Needs approval, or Blocked. The day-to-day workflow is in Claude Apps for Work. Choosing MCP versus an API or CLI, or agent-to-agent (CCAR-P 3.7), is in Built-in tools, custom tools, Skills or MCP.

Decide and avoid

Our decision rules, derived from the spec's roles and security principles:

• If an item asks who obtains the user's consent before a tool runs, choose the host; not the server, because the spec puts consent on the host and the server sees only the context the host sends, and not the protocol, because MCP cannot enforce these principles at the protocol level.
• If an item describes several servers, expect several clients inside one host; not one client multiplexing servers.
• If an item says a server can read the whole conversation or see into another server, it contradicts the spec's design principles: the full conversation history stays with the host, and servers get only the context they need.
• If an item uses serverInfo or clientInfo to authorize access, reject it: both are self-reported and unverified.

MCP primitives

Tested in: CCAR-F 2.4-K4, 2.4-S5, APPX-INSCOPE-5, APPX-TECH-2 · CCDV-F D8.2 MCP Server Development (MCP resources, tools, and prompts) · CCAR-P 3.7

A server primitive is a kind of thing a server offers (clients offer primitives too; see below). The question that sorts the three server primitives is who decides when each one is used: the model, the application, or the user.

The MCP architecture overview gives one server all three: a database server "can expose tools for querying the database, a resource that contains the schema of the database, and a prompt that includes few-shot examples for interacting with the tools." The CCAR-F in-scope list compresses the same rule to "resources for content catalogs, tools for actions" (CCAR-F exam guide, Appendix).

Tools

A server that offers tools declares the tools capability (with listChanged if it will announce list changes). Clients discover tools with a paginated tools/list and run one with tools/call.

Because names are unique only within a server, a client that aggregates servers should apply its own disambiguation, such as prefixing tool names with a server identifier. Claude Code and the Agent SDK name MCP tools mcp__<server>__<tool> (plugin-bundled servers get mcp__plugin_<plugin-name>_<server-name>__<tool-name>), which is also the string you use in permission rules, allowedTools entries and hook matchers. How to write the description itself is covered in Writing tool descriptions that steer selection.

Annotations describe behavior to the client. Besides an optional title, they carry four hints:

An illustrative tool definition (our example, not from the spec) using only the spec's field names:

{
  "name": "delete_file",
  "description": "Delete a file from the project workspace",
  "inputSchema": { "type": "object", "properties": { "path": { "type": "string" } }, "required": ["path"] },
  "annotations": {
    "title": "Delete file",
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

Annotations are not a security control. Clients MUST treat them as untrusted unless the server is trusted, and the schema says "Clients should never make tool use decisions based on ToolAnnotations" received from untrusted servers (MCP schema). In the Agent SDK, readOnlyHint: true has one practical effect: the tool can run in parallel with other read-only tools; the other hints are informational, and the SDK docs call annotations "metadata, not enforcement" (Agent SDK custom tools). Anthropic's desktop extension guide lists mandatory tool annotations for all tools among its directory submission requirements.

For safety the spec says there SHOULD always be a human in the loop able to deny a tool invocation, and clients SHOULD prompt for confirmation on sensitive operations, show tool inputs before calling the server, validate tool results before passing them to the model, implement timeouts, and log tool use for audit. Servers, for their part, MUST validate all tool inputs, implement proper access controls, rate limit invocations, and sanitize outputs.

Stateful tools under a stateless protocol. In 2026-07-28 a server keeps cross-call state by returning an explicit handle from a creation tool (the spec's example is basket_id) and accepting it as an argument on later calls; the model carries the handle forward. A call with an expired or unknown handle should return a tool execution error so the model can recover. The MCP security best practices add that servers MUST NOT treat possession of a state handle as authentication, and SHOULD bind handles to the authenticated user.

Resources

Resources are application-driven: the host decides how to bring them into context, whether by selecting portions, searching them with embeddings, or passing everything to the model. Each resource is identified by a URI.

A resource template (one entry of a resources/templates/list result), then a read of one concrete URI, trimmed from the MCP resources spec. Like the spec's own examples, the request omits the _meta fields (protocol version, client info, client capabilities). Every 2026-07-28 request MUST carry the required ones, protocol version and client capabilities, and clients SHOULD also include client info:

{ "uriTemplate": "file:///{path}", "name": "Project Files", "description": "Access files in the project directory", "mimeType": "application/octet-stream" }

{ "jsonrpc": "2.0", "id": 2, "method": "resources/read", "params": { "uri": "file:///project/src/main.rs" } }

How the exam frames resources. CCAR-F Task 2.4 treats resources as the way to expose content catalogs, with the guide's examples "issue summaries, documentation hierarchies, database schemas", so an agent can see what data exists "without requiring exploratory tool calls" (CCAR-F exam guide). In Claude Code a user references a resource with an @ mention in the form @server:protocol://resource/path, and Claude Code automatically gives Claude tools to list and read resources when servers support them; see MCP in Claude Code.

Prompts

Prompts are user-controlled: a server exposes them so the user can pick one explicitly, typically as a slash command, a command palette entry, a button or a context-menu item. The spec is precise about the word: user-controlled "refers to who decides when the prompt is used, not who authors its content" (MCP prompts spec). The server writes the prompt; the user triggers it.

• prompts/list (paginated) returns what is available; prompts/get takes a name and arguments and returns messages, each with a role of "user" or "assistant".
• Servers SHOULD answer an invalid prompt name or a missing required argument with -32602 (Invalid params), and an internal failure with -32603 (Internal error).
• Prompt arguments can be auto-completed with completion/complete, which returns at most 100 values per response.
• Claude Code lists each server prompt as a command /servername:promptname (MCP); typing /mcp__servername__promptname also runs it.

Client primitives: elicitation, sampling and roots

Clients offer primitives to servers too. Two of the three are deprecated in 2026-07-28, with removal no earlier than the first revision released on or after 2027-07-28.

The MCP client concepts page is explicit that roots serve as "a coordination mechanism between clients and servers, not a security boundary." As of September 2026, Claude Code still answers roots/list with the session's launch directory plus every additional working directory you have granted, and it shows elicitation dialogs in both form and URL modes (an Elicitation hook can auto-respond instead).

Utilities

Decide and avoid

Our decision rules, derived from the guide's resource objectives and the spec's control model:

• If the agent keeps calling list or search tools only to learn what exists (open issues, the documentation tree, table schemas), publish that catalog as a resource; not another tool, because the guide ties resources to fewer exploratory calls.
• If the operation changes state or needs parameters the model chooses at run time, make it a tool.
• If a user should trigger a canned workflow on demand, make it a prompt; prompts are designed for the user to select explicitly.
• Do not rely on annotations or roots for security. Annotations are untrusted hints and roots are informational guidance, not access control; enforce access in the server and in the host's permission system.
• The Messages API MCP connector currently supports only tool calls, not resources or prompts (as of September 2026); see MCP in the API and the Agent SDK.

MCP transports

Tested in: CCDV-F D8.2 MCP Server Development (communication patterns: stdio, sockets, client vs. server) · CCAR-P 3.2, 3.7 · CCAR-F background only (deploying or hosting MCP servers is out of scope, APPX-OUTSCOPE-4)

A transport carries JSON-RPC messages between a client and a server. The spec defines two standard transports, stdio and Streamable HTTP, and allows custom ones as long as they preserve the JSON-RPC message format, the message patterns and the per-request metadata model. Protocol semantics are identical on every transport; the transport only defines framing, delivery, how request metadata travels, and how cancellation and termination are signaled.

Two other options exist. The old HTTP+SSE transport has been deprecated since 2025-03-26 and should be migrated to Streamable HTTP. A custom transport may run over any channel that supports bidirectional messages; one that runs over a reliable byte stream, such as a Unix domain socket or a TCP connection, SHOULD reuse the stdio framing rather than invent its own.

stdio

The client starts the server as a subprocess. The server reads JSON-RPC messages from stdin and writes them to stdout, one message per line; messages MUST NOT contain embedded newlines (stdio transport spec).

• stdout is reserved. The server MUST NOT write anything to stdout that is not a valid MCP message. Logs go to stderr, which the client may capture, forward or ignore, and clients should not treat stderr output as an error. A stray print() or console.log() corrupts the stream; see Building an MCP server.
• Environment. What a stdio server inherits depends on the client. The MCP debugging guide says servers launched over stdio inherit only a limited, platform-dependent subset of environment variables (its examples use Claude Desktop). Claude Code passes stdio servers its own environment minus the variables it strips from subprocesses, or only a safe baseline when CLAUDE_CODE_MCP_ALLOWLIST_ENV=1. Either way, pass what the server needs through the env key of its configuration. Use absolute paths, because the working directory may be undefined.
• Lifecycle. If the server exits unexpectedly the client SHOULD restart it; in-flight requests are lost and can be retried. Shutdown uses no protocol message in either era: the client SHOULD close the server's stdin, wait for it to exit, and only then force termination (on POSIX, typically SIGTERM escalating to SIGKILL; on Windows, TerminateProcess or Job Objects). Servers SHOULD exit promptly when stdin closes.
• Security. A server meant to run locally SHOULD guard against use by other local processes: use stdio, which limits access to the MCP client, or, if it listens on HTTP, require an authorization token or use Unix domain sockets or another IPC mechanism with restricted access.

Streamable HTTP

The server exposes a single MCP endpoint. Every JSON-RPC message from the client MUST be a new HTTP POST whose Accept header lists both application/json and text/event-stream. For a request, the server answers with one JSON object or with an SSE stream, and clients must handle both; an accepted notification gets 202 Accepted with no body (transport mechanics only: the 2026-07-28 core protocol defines no client-to-server notifications over Streamable HTTP).

A 2026-07-28 tools/call over Streamable HTTP, as the Streamable HTTP spec shows it (the spec's example leaves out the Accept header listing application/json and text/event-stream, which a real client MUST also send):

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "Seattle, WA" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "ExampleClient", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Rules from the 2026-07-28 Streamable HTTP spec. The Origin, local-binding and authentication rules also appear in 2025-11-25, which already required MCP-Protocol-Version on requests after initialization; the Mcp-Method, Mcp-Name and Mcp-Param-{name} headers and the header-to-body match (HeaderMismatch) are new in 2026-07-28.

What changed between the eras on HTTP

A dual-era client talking to an unknown stdio server SHOULD probe with server/discover and fall back to initialize on any error that is not a recognized modern error, or on a timeout; a recognized modern error such as UnsupportedProtocolVersion means the server is modern, so the client picks a supported version instead of falling back. Over Streamable HTTP, a dual-era client MAY send a modern request first; on a 400 it inspects the body and falls back to initialize only if the body is empty or not a recognized modern error. For very old HTTP+SSE servers, a client that gets 400, 404 or 405 without a modern error body issues a GET and expects an SSE stream whose first event is endpoint.

Authorization on HTTP transports

Authorization is optional in MCP. When an HTTP server uses it, the server is an OAuth 2.1 resource server and the MCP client is an OAuth 2.1 client; a separate or co-hosted authorization server issues tokens (MCP authorization spec). The points that decide architecture questions (CCAR-P 3.2):

Confused deputy, token passthrough, SSRF and state handle hijacking, with their mitigations, are covered in Security, Safety and Governance.

Transports on Claude surfaces (as of September 2026)

Reachability trips people up. A custom connector connects from Anthropic's cloud, not from the user's device, on every Claude client (claude.ai, Claude Desktop, Cowork and the mobile apps), so the server must be reachable from the public internet (or allowlist Anthropic's IP ranges). The Messages API connector documentation likewise requires a publicly exposed HTTP server and rules out local stdio servers. For a server inside a private network, MCP tunnels (research preview) carry traffic over an outbound-only connection, so no inbound firewall ports are opened; you attach a tunnel hostname to a Claude Managed Agents session (Managed Agents declare MCP servers by name and URL) or pass it to the Messages API through the MCP connector.

Decide and avoid

• If the server needs the local filesystem, local tools, or must work offline, choose stdio (or a .mcpb extension in Claude Desktop); not a remote server, which runs on your servers rather than on the user's machine (as a remote connector in claude.ai, Claude Desktop or Cowork, it is also reached through Anthropic's infrastructure).
• If several applications, users or cloud agents must share one server, choose Streamable HTTP with OAuth; not stdio, which typically serves a single client on the same machine.
• If a Messages API application must call the server, it has to be reachable over HTTP (publicly, or from a private network through an MCP tunnel); a local stdio server will not work with the MCP connector.
• If an item offers HTTP+SSE for a new build, it is the deprecated option.
• If a Claude Code server must push events to Claude unprompted, a WebSocket ("type": "ws") server fits; if it only responds to requests, use HTTP, which supports OAuth and the --transport flag.
• If a stdio server breaks its connection for no visible reason, suspect writes to stdout.

MCP errors and structured results

Tested in: CCAR-F 2.2 (2.2-K1 to 2.2-S4), APPX-TECH-2, APPX-INSCOPE-7, Exercise 1 step 3 · CCDV-F D8.1 Tool Implementation (error handling), D4.1 Debugging and Error Handling (error type identification, recovery strategy selection)

A tool can fail in two ways in MCP, and the choice decides whether Claude reliably sees what went wrong and can act on it. CCAR-F Task 2.2 is built on this: its first knowledge bullet is "The MCP isError flag pattern for communicating tool failures back to the agent" (CCAR-F exam guide).

Two error channels

The MCP tools spec says tool execution errors "contain actionable feedback that language models can use to self-correct and retry with adjusted parameters". isError defaults to false, and the MCP schema explains why errors from inside the tool belong in the result: otherwise "the LLM would not be able to see that an error occurred". Revision 2025-11-25 clarified that input validation errors should be returned as tool execution errors rather than protocol errors, to enable model self-correction.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Invalid departure date: must be in the future. Current date is 08/08/2025." }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": { "code": -32602, "message": "Unknown tool: invalid_tool_name" }
}

Both examples come from the 2026-07-28 spec. The resultType field is new in that revision: every result MUST carry one, and the core protocol defines "complete" and "input_required" (extensions MAY add values). A client MUST treat a missing resultType from an older server as "complete", so a 2025-11-25 server, which never sends it, still works.

JSON-RPC error codes

A failure is not an empty answer

CCAR-F skill 2.2-S4 separates access failures from valid empty results; the general rule, with the Q8 anti-pattern, is in Returning tool results and errors. MCP writes the same rule into the protocol for resources: a server MUST NOT return an empty contents array for a resource that does not exist, because "An empty array is ambiguous" (MCP resources spec); it returns a JSON-RPC error instead (-32602 in 2026-07-28, -32002 in earlier revisions). For tools, the equivalent is to return a normal result that says nothing matched when the query ran, and isError: true when it could not run.

The same thinking covers a stateful tool called with an expired or unknown handle: it returns a tool execution error, as described under MCP primitives.

Structured error metadata: the exam guide's convention

The spec defines one flag, isError, plus free-form content. The CCAR-F guide asks for more structure inside that content: "errorCategory (transient/validation/permission), isRetryable boolean, and human-readable descriptions" (2.2-S1), and "retriable: false flags and customer-friendly explanations for business rule violations" (2.2-S2) (CCAR-F exam guide). The reason is 2.2-K3: a uniform "Operation failed" leaves the agent unable to choose a recovery, and 2.2-K4: a retryable flag prevents wasted retries.

The guide's knowledge bullet 2.2-K2 names four error types (transient, validation, business, permission); the recovery each one calls for is tabulated in Returning tool results and errors. What matters at the MCP layer is where the metadata goes.

The payload travels as text in the content of an isError: true result. A business-rule refusal at the protocol level (illustrative; the category value "business" is the fourth type from 2.2-K2, which 2.2-S1's list of errorCategory values leaves out):

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "resultType": "complete",
    "content": [
      {
        "type": "text",
        "text": "{\"errorCategory\": \"business\", \"isRetryable\": false, \"description\": \"This order is outside the return window, so a refund cannot be issued. Explain the return policy to the customer and offer a human agent.\"}"
      }
    ],
    "isError": true
  }
}

In the Agent SDK, a custom tool is served by an in-process MCP server, and the flag is spelled differently in each language. Adapted from the error-handling example in the Agent SDK custom tools docs; the order-service URL is a placeholder and the field names are the guide's:

import json
from typing import Any

import httpx
from claude_agent_sdk import tool

@tool("lookup_order", "Look up one order by its order number", {"order_id": str})
async def lookup_order(args: dict[str, Any]) -> dict[str, Any]:
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(f"https://orders.example.com/orders/{args['order_id']}")
    except Exception as e:
        # A network error or timeout would otherwise reach Claude as the raw message.
        error = {
            "errorCategory": "transient",
            "isRetryable": True,
            "description": f"Could not reach the order service: {e}. Retry the same call once.",
        }
        return {"content": [{"type": "text", "text": json.dumps(error)}], "is_error": True}
    if response.status_code == 503:
        error = {
            "errorCategory": "transient",
            "isRetryable": True,
            "description": "The order service is temporarily unavailable. Retry the same call once.",
        }
        # is_error marks this as a failed call rather than odd-looking data.
        return {"content": [{"type": "text", "text": json.dumps(error)}], "is_error": True}
    if response.status_code == 404:
        error = {
            "errorCategory": "validation",
            "isRetryable": False,
            "description": f"No order {args['order_id']} exists. Ask the customer to confirm the order number.",
        }
        return {"content": [{"type": "text", "text": json.dumps(error)}], "is_error": True}
    if response.status_code != 200:
        # Any other failure status is still a failed call, never a normal result.
        return {
            "content": [{"type": "text", "text": f"Order service error: {response.status_code} {response.reason_phrase}"}],
            "is_error": True,
        }
    return {"content": [{"type": "text", "text": response.text}]}

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const lookupOrder = tool(
  "lookup_order",
  "Look up one order by its order number",
  { order_id: z.string() },
  async (args) => {
    let response: Response;
    try {
      response = await fetch(`https://orders.example.com/orders/${args.order_id}`);
    } catch (error) {
      // A network error or timeout would otherwise reach Claude as the raw message.
      const reason = error instanceof Error ? error.message : String(error);
      const failure = {
        errorCategory: "transient",
        isRetryable: true,
        description: `Could not reach the order service: ${reason}. Retry the same call once.`
      };
      return { content: [{ type: "text", text: JSON.stringify(failure) }], isError: true };
    }
    if (response.status === 503) {
      const error = {
        errorCategory: "transient",
        isRetryable: true,
        description: "The order service is temporarily unavailable. Retry the same call once."
      };
      // isError marks this as a failed call rather than odd-looking data.
      return { content: [{ type: "text", text: JSON.stringify(error) }], isError: true };
    }
    if (response.status === 404) {
      const error = {
        errorCategory: "validation",
        isRetryable: false,
        description: `No order ${args.order_id} exists. Ask the customer to confirm the order number.`
      };
      return { content: [{ type: "text", text: JSON.stringify(error) }], isError: true };
    }
    if (!response.ok) {
      // Any other failure status is still a failed call, never a normal result.
      return {
        content: [{ type: "text", text: `Order service error: ${response.status} ${response.statusText}` }],
        isError: true
      };
    }
    return { content: [{ type: "text", text: await response.text() }] };
  }
);

If a handler throws instead, the SDK's in-process server converts the exception into an error result carrying the raw message, and the agent loop continues. In both cases Claude can retry, try another tool, or explain the failure. Catch errors yourself when the raw message would not tell Claude what to do next: the try/except (try/catch) block above is what gives a network failure or timeout the full metadata.

Where the retry happens is a design decision of its own. CCAR-F skill 2.2-S3 asks for local recovery of transient failures inside a subagent, and for propagating to the coordinator only what cannot be resolved locally, with partial results and what was attempted. How the coordinator uses that is covered in Evaluation, Debugging and Reliability.

Structured results: outputSchema and structuredContent

A successful result can carry machine-readable data as well as text. A tool that declares an outputSchema MUST return structuredContent that conforms to it, and clients SHOULD validate it. In 2026-07-28 structuredContent can be any JSON value (object, array, string, number, boolean or null); the 2025-11-25 text described it as a JSON object, the 2026-07-28 changelog lists the loosening, and the Agent SDK custom tools page still calls it an optional JSON object. For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a text block.

{
  "name": "get_weather_data",
  "title": "Weather Data Retriever",
  "description": "Get current weather data for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": { "type": "number", "description": "Temperature in celsius" },
      "conditions": { "type": "string", "description": "Weather conditions description" },
      "humidity": { "type": "number", "description": "Humidity percentage" }
    },
    "required": ["temperature", "conditions", "humidity"]
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}" }
    ],
    "structuredContent": { "temperature": 22.5, "conditions": "Partly cloudy", "humidity": 65 }
  }
}

Three details decide questions about structured results:

• It is not "structured outputs". The spec says structuredContent "is server-produced result data and is unrelated to LLM" structured outputs, which it glosses as schema-constrained model generation (MCP tools spec). Constraining Claude's own response format is a different feature; see Structured outputs.
• Claude may not see the text copy. In the Agent SDK, when structuredContent is set, Claude receives the JSON plus any image or resource blocks, and text blocks in content are not forwarded because they are assumed to duplicate it. The Python @tool decorator forwards only content and is_error, so returning structuredContent from Python needs a standalone MCP server.
• Other content types. Unstructured content can hold text, images and audio (base64 data with a mimeType), resource_link items (not guaranteed to appear in resources/list), and embedded resources, whose servers SHOULD implement the resources capability.

How an MCP failure reaches Claude

The flag changes spelling by layer (isError in MCP, is_error on a Messages API tool_result); the full list is in Returning tool results and errors. Two MCP-specific cases complete it. With the Messages API MCP connector, a failed call comes back as an mcp_tool_result block with is_error, paired with the mcp_tool_use block that names the server_name. In Claude Code, whether Claude hears about a server that failed to connect depends on tool search, which is on by default: with it, Claude Code tells Claude which server failed and its connection error, so Claude reports the connection failure in its response; in any configuration without tool search, Claude Code does not report failed server connections to Claude.

When the server needs input: not an error

In 2026-07-28 a server that needs input from the client mid-call (an elicitation from the user, an LLM completion through sampling, or the client's roots) returns a result with resultType: "input_required" instead of failing or sending its own request. This is allowed only on tools/call, resources/read and prompts/get. The client collects the input and retries with inputResponses under a new JSON-RPC id, echoing the opaque requestState exactly; the server MUST treat requestState as attacker-controlled.

Server reply to tools/call with id 2, then the client's retry (MCP tools spec):

{ "jsonrpc": "2.0", "id": 2,
  "result": { "resultType": "input_required",
    "inputRequests": { "github_login": { "method": "elicitation/create",
      "params": { "mode": "form", "message": "Please provide your GitHub username",
        "requestedSchema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] } } } },
    "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..." } }

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "get_weather", "arguments": { "location": "New York" },
    "inputResponses": { "github_login": { "action": "accept", "content": { "name": "octocat" } } },
    "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..." } }

Decide and avoid

• If the input was invalid, return an isError result that says what was wrong and how to fix it; not a JSON-RPC protocol error, which the model is less able to act on.
• If a timeout or an unavailable service caused the failure, mark it transient and retryable and recover locally; if that fails, propagate structured context (the failure type, the attempted query, any partial results, possible alternatives) so the coordinator can decide. Not a generic "search unavailable" status after exhausted retries, which is option B of CCAR-F sample question 8 in the CCAR-F exam guide and hides that context.
• If a business rule blocked the action, mark it non-retryable and include a customer-friendly explanation; retrying cannot change a policy (our reasoning from 2.2-S2 and 2.2-K4).
• If the query succeeded with no matches, return a normal result; not isError, which would send the agent into a retry decision it does not need. The reverse is the sample-question trap: a timeout returned as an empty result marked successful (option C of question 8) prevents any recovery.
• If a stateful call names an expired or unknown handle, return a tool execution error that says so.
• If the tool name does not exist or the request is malformed, a JSON-RPC error (-32602 for an unknown tool) is correct.
• Do not describe errorCategory or isRetryable as MCP spec fields, and do not confuse structuredContent with structured outputs.

Building an MCP server

Tested in: CCDV-F D8.2 MCP Server Development (server authoring, deployment, integration with Claude applications), Sample 3 · CCAR-F 2.4-S4, Exercise 1 step 1 (hosting is out of scope, APPX-OUTSCOPE-4) · CCAR-P 3.7

CCDV-F D8.2 covers server authoring, deployment and integration with Claude applications, and CCAR-F 2.4-S4 asks the question that comes first: whether to build a server at all. This section follows that order: build or reuse, the official SDKs, a minimal server, testing with the MCP Inspector, connecting to a Claude host, and a design checklist.

Build or reuse?

Before writing a server, check whether one exists. CCAR-F skill 2.4-S4 prefers "existing community MCP servers over custom implementations for standard integrations (e.g., Jira), reserving custom servers for team-specific workflows" (CCAR-F exam guide). Where to look, and what each source does and does not promise:

The quoted phrase is from the servers repository README. Build your own when the capability is specific to your team, or when the CCDV-F Sample 3 situation applies: an internal service that several Claude applications must share and that should be "maintained independently" of any one app (CCDV-F exam guide).

SDKs

Official MCP SDKs exist in three tiers (2026-07-28 docs): Tier 1 TypeScript, Python, C#, Go and Rust; Tier 2 Java and Ruby; Tier 3 Swift, PHP and Kotlin. Every SDK can build servers that expose tools, resources and prompts, build clients, and use local and remote transports.

A minimal server in each language

Both servers below run over stdio, which is what Claude Desktop and a local Claude Code configuration launch. The Python version is the SDK README's 15-line server plus the stdio entry point from the official tutorial; the TypeScript version is the TypeScript SDK README's example.

from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="stdio")

uv add "mcp[cli]"
uv run mcp dev server.py                               # open the server in the MCP Inspector
uv run mcp run server.py --transport streamable-http   # serve it over Streamable HTTP instead

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

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

server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => ({
        content: [{ type: 'text', text: `Hello, ${name}!` }]
    })
);

async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
}

main();

npm install @modelcontextprotocol/server zod
npx @modelcontextprotocol/inspector node build/index.js   # after compiling with tsc

What the Python version did not need is the point of the SDK: "no JSON Schema (a: int, b: int is the schema)", in the words of the Python SDK README, and no request parsing, validation code or protocol handling. The SDK builds the tool definition from the type hints and the docstring, so write the docstring for the model.

The stdout rule

For a stdio server, stdout belongs to the protocol. The official tutorial is blunt: "Writing to stdout will corrupt the JSON-RPC messages and break your server" (build-server tutorial). In Python keep print() out of the server and use the logging module, which writes to stderr; in TypeScript use console.error(), never console.log(). HTTP servers may log to stdout. The MCP debugging guide says the host application captures a stdio server's stderr automatically; a Streamable HTTP server's stderr is not captured by the client, so use your own server-side log aggregation or OpenTelemetry. Logging over the protocol itself (notifications/message) is deprecated as of 2026-07-28.

Test it with the MCP Inspector

The MCP Inspector is the reference tool for testing and debugging servers. One npm package, @modelcontextprotocol/inspector, provides a web UI (the default, on port 6274), a scriptable CLI (--cli) and a TUI (--tui). It needs Node 22.19.0 or newer and runs through npx with no install, and it negotiates the legacy or modern protocol era the same way in all three clients.

npx @modelcontextprotocol/inspector node path/to/server/index.js            # web UI
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

Connect it to a Claude host

The Claude Desktop entries below are the official 2026-07-28 build-server tutorial's configurations for its weather server; substitute your own absolute path and file name. The Claude Code commands are our illustration: the documented stdio syntax claude mcp add [options] <name> -- <command> [args...] wrapped around the same launch command.

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather", "run", "weather.py"]
    }
  }
}

claude mcp add --transport stdio weather -- uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"]
    }
  }
}