D2 · Tool Design & MCP › Cluster 1 · Tool Use Fundamentals

1.5 · Client Tools vs Server Tools

Who executes the tool

CONCEPT Tools differ by where the code runs

The single dividing line in the tool ecosystem is where execution happens.

Client toolsServer tools
Runs onYour infrastructureAnthropic's infrastructure
You execute?Yes — you run the code & return a tool_resultNo — Anthropic runs it for you
Loopstop_reason: "tool_use" → you reply with tool_resultResult arrives in the same response; no client round trip
ExamplesYour get_weather; Anthropic-schema bash, text_editor, memory, computerweb_search, web_fetch, code_execution, tool_search, advisor
🔑 Client tools include both your user-defined tools and Anthropic-schema tools like bash/text_editor — Anthropic publishes the schema, but you still execute the call. What makes a tool "server" isn't who wrote the schema; it's who runs the code.

CONCEPT Server tools skip the round trip

With a client tool you get stop_reason: "tool_use", execute in your code, and reply with a tool_result — the four-step loop from 1.1. A server tool collapses that: you just declare it in tools, and Anthropic runs it (e.g. performs the web search, executes the code) and returns the results inside the same response. There's no tool_result for you to send.

Declaring a server tool is just a type entry, e.g. {"type": "web_search_20260209", "name": "web_search"} — no input_schema, because Anthropic owns the schema and the execution.
⚠️ Long server-tool turns can pause with stop_reason: "pause_turn"; you resend the conversation to resume. And a server tool called in the same parallel batch as a client tool still surfaces the client tool for you to execute.

DIAGRAM Two execution paths

flowchart TD Q["Claude wants to use a tool"] --> K{"Client or server?"} K -->|"client
(your tool, bash, text_editor)"| C1["stop_reason: tool_use"] C1 --> C2["YOU execute in your app"] C2 --> C3["Reply with tool_result
(user turn)"] C3 --> DONE["Claude continues"] K -->|"server
(web_search, code_execution)"| S1["ANTHROPIC executes it"] S1 --> S2["Results returned in the
same response — no round trip"] S2 --> DONE classDef client fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; classDef server fill:#d4edda,stroke:#28a745,color:#155724; class C1 client; class C2 client; class C3 client; class S1 server; class S2 server;

CODE Declaring both kinds in one request

A server tool (web_search, executed by Anthropic) and a client tool (get_weather, executed by you) side by side. You only handle a tool_result for the client tool.

tools = [
    # SERVER tool: Anthropic runs the search; results come back inline.
    {"type": "web_search_20260209", "name": "web_search"},

    # CLIENT tool: YOU execute it and return a tool_result.
    {
        "name": "get_weather",
        "description": "Get the current weather for a location.",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"],
        },
    },
]

resp = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                               tools=tools,
                               messages=[{"role": "user",
                                          "content": "Latest Mars news, and weather in SF?"}])

for block in resp.content:
    if block.type == "tool_use":            # the CLIENT tool — you must run it
        run_and_return_tool_result(block)
    # web_search results are already in resp.content — nothing to execute.

TRADE-OFFS Client tools vs. server tools

✅ Client tools

  • Full control — any code, any system, your data & auth
  • You can gate, validate, and audit each call
  • Priced like a normal request

✅ Server tools (the other side)

  • Zero execution code — Anthropic runs & hosts it
  • Results inline; simpler loop
  • But: fixed capabilities + usage-based charges (e.g. per web search)
Rule of thumb: reach for a server tool when Anthropic already offers the capability (search, code sandbox) and you don't want to run it; write a client tool when the action touches your systems, data, or security boundary.

EXAM TRAPS

Trap: "Anthropic-schema tools like bash are server tools." → No — they are client tools. Anthropic publishes the schema, but you execute the call and return the tool_result. Server vs. client is about who runs the code.
Trap: Waiting to send a tool_result for a server tool. → Server tools (web search, code execution) run on Anthropic's side and return results inline — there's no tool_result for you to send.
Trap: Giving a server tool an input_schema. → You declare it by type (e.g. web_search_20260209). Anthropic owns the schema and the execution.
Trap: Ignoring pause_turn. → A long server-tool turn may stop with stop_reason: "pause_turn"; resend the conversation to let Anthropic resume.

PRACTICE

Q1 · What single question separates a client tool from a server tool?

"Where does the code run?" Client tools execute on your infrastructure (you return a tool_result); server tools execute on Anthropic's infrastructure (results come back inline, nothing to execute).

Q2 · Is the Anthropic-defined bash tool a client or server tool?

A client tool. Anthropic defines its schema and trains Claude on it, but your application still runs the shell command and returns the tool_result. Anthropic-schema ≠ server-executed.

Q3 · Name two server tools and describe how their results reach you.

e.g. web_search and code_execution (also web_fetch, tool_search). Anthropic runs them and returns the results as content blocks in the same response — you don't execute anything or send a tool_result.