Server-side tools

1 · What a server-side tool is essential

A tool is a capability the model can invoke instead of just writing text. In C2 you built client-side tools: you describe a function, the model asks to call it, and your code runs it and feeds the result back in a loop. A server-side tool is different — it's a capability Anthropic has already built and runs on its own infrastructure. You just switch it on; the model calls it and the result comes back inside the same response. There is no function for you to write and no loop for you to run.

Two of the most useful ones ship today: web search (the model searches the live web and cites its sources) and code execution (the model writes Python and runs it in a sandbox). A close cousin, web fetch, pulls the full text of a specific URL. All three execute on Anthropic's side — you never see the search engine or the sandbox, only the results.

2 · Client-side vs server-side: the two loops essential

The single most important idea in this lesson is the difference in control flow. With a client-side tool, you are the runtime: the model pauses, hands you a request, and waits for you to run the function and send the answer back — round-trip after round-trip until it's done (the while True loop from C2). With a server-side tool, Anthropic is the runtime: it runs the tool for you and only returns when the answer is already folded into the response.

So the client-side path is request → tool_use → you run it → tool_result → answer, looping as many times as the task needs. The server-side path collapses to request → answer (with the tool already run). You trade control (you can't intercept or gate a server tool) for simplicity (no loop, no execution environment to build).

3 · Enabling the web search tool intermediate

You enable a server-side tool by adding its spec to the tools=[...] list — the same list you'd use for your own tools, but instead of a name + schema you give a type (and the tool's fixed name). For web search the current dynamic-filtering variant is web_search_20260209 on Opus 4.8/4.7/4.6 and Sonnet 4.6; older models use the basic web_search_20250305. Optional keys let you cap uses or restrict domains.

The block below is real anthropic SDK code. It needs an API key and network — and web search has its own per-search pricing on top of tokens (see §6).

web_search.py# needs: pip install anthropic + ANTHROPIC_API_KEY; server tools have their own pricing
import anthropic

client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user",
               "content": "What did Anthropic announce most recently? Cite your sources."}],
    tools=[{
        # Server-side tool: a `type` + fixed `name`, NOT a custom input_schema.
        # web_search_20260209 = dynamic-filtering variant (Opus 4.8/4.7/4.6, Sonnet 4.6).
        # Older models use "web_search_20250305".
        # check the current tool type/version in the docs before shipping.
        "type": "web_search_20260209",
        "name": "web_search",
        "max_uses": 3,                     # optional: cap how many searches
        # "allowed_domains": ["anthropic.com"],   # optional allow/block lists
    }],
)

# You do NOT run a tool loop. Anthropic already searched and folded the
# results into this one response. Just read stop_reason + content.
print("stop_reason:", resp.stop_reason)
for block in resp.content:
    if block.type == "text":
        print(block.text)

4 · Reading search results & citations intermediate

When a server tool runs, its output arrives as extra content blocks in the response, interleaved with the model's text. For web search you'll see a server_tool_use block (the query the model chose) followed by a web_search_tool_result block whose content is a list of results. The model's answer text then arrives in normal text blocks, and cited sentences carry a citations array pointing back at the sources it used.

The block below is real anthropic SDK code that walks the response and prints the results and citations. It needs an API key and network.

read_results.py# needs: pip install anthropic + ANTHROPIC_API_KEY; server tools have their own pricing
import anthropic

client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize the latest on X. Cite sources."}],
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
)

for block in resp.content:
    if block.type == "server_tool_use":
        # The query the model chose to run, server-side.
        print("SEARCHED:", block.input.get("query"))

    elif block.type == "web_search_tool_result":
        # On success .content is a LIST of results; on error it is a single
        # error object (e.g. {"error_code": "max_uses_exceeded"}) — branch on that.
        results = block.content
        if isinstance(results, list):
            for r in results:
                print("  -", r.title, "->", r.url)
        else:
            print("  search error:", getattr(results, "error_code", results))

    elif block.type == "text":
        print(block.text)
        # Cited sentences carry a citations array pointing at the sources used.
        for c in (block.citations or []):
            print("    cited:", getattr(c, "url", None), getattr(c, "title", None))

5 · The code execution tool advanced

Code execution lets the model write Python and run it in an Anthropic-hosted sandbox (no internet, data-science libraries pre-installed). You don't run anything — you declare the tool and the model's code, its stdout/stderr, and any files it produced come back in the response. The current type is code_execution_20250825; its result arrives as a bash_code_execution_tool_result block with stdout / stderr / return_code.

The block below is real anthropic SDK code. It needs an API key and network, and code execution is billed by sandbox time (see §6).

code_execution.py# needs: pip install anthropic + ANTHROPIC_API_KEY; server tools have their own pricing
import anthropic

client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user",
               "content": "Compute the mean and standard deviation of "
                          "[2, 4, 4, 4, 5, 5, 7, 9] with numpy."}],
    tools=[{
        # Server-side sandbox — the model writes AND runs the code.
        # check the current tool type/version in the docs before shipping.
        "type": "code_execution_20250825",
        "name": "code_execution",
    }],
)

for block in resp.content:
    if block.type == "text":
        print(block.text)                       # the model's explanation
    elif block.type == "server_tool_use":
        print("RUNNING:", block.name)           # what the model chose to do
    elif block.type == "bash_code_execution_tool_result":
        result = block.content
        if getattr(result, "return_code", 0) == 0:
            print("stdout:", result.stdout)     # the program's output
        else:
            print("stderr:", result.stderr)     # it errored — read stderr

6 · Cost & safety advanced

Server-side tools have their own pricing on top of tokens. Web search is billed per search; code execution is billed by sandbox time (with a monthly free allowance). Because the model decides how many times to invoke a tool, an unbounded task can run several searches or long sandbox sessions — so cap it. The offline helper below (pure stdlib, runs offline) estimates a per-request bill from your assumptions so you can sanity-check before enabling a tool in production.

server_cost.pydef server_tool_cost(searches, search_price, sandbox_minutes,
                     sandbox_price_per_min, tokens, token_price_per_1k):
    """Estimate one request's bill: search fees + sandbox time + tokens."""
    search_cost = searches * search_price
    sandbox_cost = sandbox_minutes * sandbox_price_per_min
    token_cost = tokens / 1000 * token_price_per_1k
    total = search_cost + sandbox_cost + token_cost
    return {
        "search_cost": round(search_cost, 4),
        "sandbox_cost": round(sandbox_cost, 4),
        "token_cost": round(token_cost, 4),
        "total_usd": round(total, 4),
    }

print(server_tool_cost(searches=3, search_price=0.01,
                       sandbox_minutes=0.5, sandbox_price_per_min=0.05,
                       tokens=4000, token_price_per_1k=0.005))

{'search_cost': 0.03, 'sandbox_cost': 0.025, 'token_cost': 0.02, 'total_usd': 0.075}

7 · When to use server-side vs your own tools professional

The choice is about who should run the action. Reach for a server-side tool when the capability is generic, safe to run automatically, and you'd rather not build it: live web info, ad-hoc computation, fetching a public URL. Reach for a client-side tool when the action touches your systems (your database, your API, sending an email), needs your credentials, or must be gated/approved/audited before it runs.

The helper below (pure stdlib, runs offline) encodes that decision so you can defend the choice by criteria rather than by taste.

choose_side.pydef choose_tool_side(touches_your_systems, needs_your_credentials,
                     must_gate_or_audit, is_generic_capability):
    """Decide whether an action belongs in a client-side or server-side tool."""
    if touches_your_systems or needs_your_credentials or must_gate_or_audit:
        return "client-side (your code runs it: control, credentials, approval)"
    if is_generic_capability:
        return "server-side (Anthropic runs it: web search / code exec, no loop)"
    return "client-side (default: keep control unless it's clearly generic)"

# a) live web info, nothing of yours involved -> server-side
print(choose_tool_side(False, False, False, True))
# b) charge a customer's card -> client-side (credentials + must gate)
print(choose_tool_side(True, True, True, False))
# c) query YOUR order database -> client-side (your systems)
print(choose_tool_side(True, False, False, False))

server-side (Anthropic runs it: web search / code exec, no loop)
client-side (your code runs it: control, credentials, approval)
client-side (your code runs it: control, credentials, approval)

8 · Tech-lead — owning server-side tools in production tech-lead

A lead owns four decisions. Cost governance: cap invocations (max_uses, max_tokens) and monitor the per-request server-tool bill, not just tokens — an agent that searches on every turn is a budget leak. Data boundary: web search reaches the public internet and code execution runs in Anthropic's sandbox — know what leaves and fence it with allow/block domain lists. Correct result-reading: server tools never raise; errors are result blocks, and success vs error content can be a list vs an object — the response-parsing code must branch on that or it breaks in production. The client/server split: keep anything that touches your systems or needs approval on the client side; let generic, safe capabilities run server-side. Pin the exact tool type/version and re-check it against the docs when you upgrade models, since the available variant depends on the model.

import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user",
               "content": "What are the latest Claude model releases?"}],
)
for block in resp.content:
    if block.type == "text":
        print(block.text)

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "Who won the 2024 Turing Award?"}],
)
for block in resp.content:
    if block.type == "text":
        print("ANSWER:", block.text)
    elif block.type == "web_search_tool_result":
        content = block.content
        if isinstance(content, list):            # success -> list of results
            for r in content:
                print("SRC:", r.title, r.url)
        else:                                    # error -> single object
            print("SEARCH ERROR:", content.error_code)

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=2048,
    tools=[{"type": "code_execution_20260120", "name": "code_execution"}],
    messages=[{"role": "user",
               "content": "Compute the mean and stdev of [1,2,3,4,5,6,7,8,9,10]."}],
)
for block in resp.content:
    if block.type == "text":
        print(block.text)
    elif block.type == "bash_code_execution_tool_result":
        r = block.content
        if r.type == "bash_code_execution_result":
            print("stdout:", r.stdout, "rc:", r.return_code)
        else:
            print("exec error:", r.error_code)

messages = [{"role": "user", "content": "Research X thoroughly and summarize."}]
for _ in range(5):                          # cap continuations
    resp = client.messages.create(
        model="claude-opus-4-8", max_tokens=2048,
        tools=[{"type": "web_search_20260209", "name": "web_search"}],
        messages=messages,
    )
    if resp.stop_reason != "pause_turn":
        break
    # Re-send: user query + assistant response. Do NOT append "Continue."
    messages = [messages[0], {"role": "assistant", "content": resp.content}]
print(next(b.text for b in resp.content if b.type == "text"))

resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    tools=[{
        "type": "web_search_20260209", "name": "web_search",
        "max_uses": 3,                              # cap searches per request
        "allowed_domains": ["docs.anthropic.com", "platform.claude.com"],
    }],
    messages=[{"role": "user", "content": "How do I enable prompt caching?"}],
)

def choose_tool(need):
    table = {
        "current web info":    ("server: web_search",
                                "Anthropic hosts search; no infra, citations included"),
        "run sandboxed code":  ("server: code_execution",
                                "Anthropic-hosted sandbox; no container to manage"),
        "internal billing API":("client-defined tool",
                                "your data/auth boundary — you must execute & gate it"),
        "private database":    ("client-defined tool",
                                "private data never leaves your infra; you run the query"),
    }
    return table.get(need, ("client-defined tool", "default: you own execution"))

for n in ["current web info", "run sandboxed code",
          "internal billing API", "private database"]:
    tool, why = choose_tool(n)
    print(f"{n:22} -> {tool:22} ({why})")

Knowledge check check yourself