Server-side tools

1 · What a server-side tool is essential

Picture the two ways a restaurant can get you a glass of water. In the first, the waiter brings you an empty glass and a note: "the tap is down the hall, third door, mind the step" — and you get up, walk down, fill it, and carry it back. In the second, you just ask, and a full glass arrives at your table; the fetching happened in the kitchen and you never saw it. Client-side tools are the first restaurant. Server-side tools are the second. That single difference — who gets up to do the work — is what this whole lesson turns on, and getting it wrong is the most common reason people either write a pointless while loop around a server tool or wait forever for a "tool call" that already happened.

Here's why the distinction earns its own section instead of a footnote. When you first meet tools, everything looks like the first restaurant: the model asks, you run, you reply. So your instinct — a good instinct, honestly — is to reach for the loop every time. But some capabilities aren't yours to run at all; there's no tap down your hall. Live web search needs a search engine you don't host; a Python sandbox needs an execution environment you'd have to build and secure. Anthropic already runs those, so you don't write the function, you don't spin up the sandbox, and you don't drive a loop — you just tick a box in your request. The trap is treating a server tool like a client tool and hunting for a tool_use block to answer; there isn't one, and the code sits waiting on a reply that will never come.

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

If you remember one thing from this lesson, make it this: who owns the loop. Everything else — how you read results, how errors surface, how you budget cost — falls out of that one fact. People who skip this section end up writing code that either double-loops a server tool (harmless but confused) or, worse, tries to intercept a server tool that already ran and can't be stopped. The bug isn't a typo; it's a wrong mental model, and it's expensive to debug because the code looks reasonable.

The cleanest way to feel the difference is to think about who is holding the phone during the call. With a client-side tool, the model calls you, says "I need the weather in Paris — go find it," and then holds the line while you look it up; nothing continues until you speak the answer back. You are the runtime, and the conversation is a series of these back-and-forths. With a server-side tool, the model makes the call, does the lookup itself in the back office, and only rings you once — when the whole thing is finished and the answer is already written down. One conversation, one hang-up. The word "loop" is literal in the first case (you genuinely write a while that keeps going) and absent in the second.

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

A model's knowledge has a freeze date, and that gap is exactly where confident-sounding wrong answers come from. Ask it about a release from last week and it will either admit it doesn't know or, worse, invent something plausible. Web search closes that gap: the model runs a live search, reads real pages, and cites them — so instead of guessing from stale memory it answers from what's on the web right now. Turning it on is almost insultingly easy, which is the point of this section — the hard part isn't enabling it, it's remembering that you don't then write a loop.

Think of enabling a server tool as flipping a switch on a request rather than installing a machine. For your own tools you hand over a full instruction manual — a name, a description, a JSON input_schema spelling out every argument — because your code has to know how to run the function. A server tool needs none of that; Anthropic already knows how to run it. So you just name the kind of tool with a type string (plus its fixed name), and that's the entire declaration. The one wrinkle that trips people is the version suffix: the type is dated (web_search_20260209), the right date depends on the model, and pasting an old one against a new model — or a new one against an old model — is a quiet mismatch. Pin it, and re-check the docs when you change models.

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

A response with a server tool in it is not a flat string — it's a small transcript, and if you only read the text you throw away half the value. The citations that let you fact-check the answer, the URLs a user might click, the very query the model chose to run: all of that lives in extra blocks alongside the prose. Teams that treat the response as "just .text" ship agents that sound grounded but can't show their work, and then can't explain to a reviewer where a claim came from. Reading the whole transcript is what turns web search from a party trick into something you can defend.

The mental model is a reporter's notebook, not a finished article. As the model works, it jots things down in order: "I searched for this" (a server_tool_use block), "here's what came back" (a web_search_tool_result block holding the list of hits), "here's my sentence" (a text block) — and pinned to that sentence, "…and I got it from these pages" (a citations array). Your job when the call returns is simply to walk that notebook page by page and pick out what you need, branching on each block's type. There's no loop and no callback — the notebook is already complete when you get it; you're a reader, not a participant. The common mistake here is assuming the blocks come in a tidy fixed order and indexing blindly; instead, iterate and switch on type, because text and tool blocks interleave however the model reasoned.

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

Language models are famously bad at arithmetic — ask one to average eight numbers and it may fudge the last digit. Not because it's dumb, but because it's predicting the answer, not computing it. Code execution fixes this by letting the model stop guessing and actually run the numbers: it writes real Python, a real interpreter runs it, and the real output comes back. The same trick turns "I think the CSV has about a thousand rows" into a counted, exact answer. If web search grounds the model in facts, code execution grounds it in computation.

The instinct that makes this section feel hard is a false alarm: "surely running code needs a callback — I have to hand the program somewhere and get output back?" You don't. The sandbox is a pop-up kitchen Anthropic sets up and tears down — the model writes the recipe and cooks it in there, and you're only handed the finished plate. Nothing runs on your machine, so there's no container to build, no dependency to install (data-science libraries are pre-loaded), and no security surface of your own to worry about. The flip side, and the thing to internalize: because it's their kitchen with no internet, the code can't reach your files, your database, or the web unless you explicitly upload data — which is exactly why it's safe to let run automatically. The one habit to build is reading the result like a shell command: check return_code first (0 means success, read stdout; anything else means it errored, read stderr) instead of assuming the run worked.

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

Here's the line item that ends up in a surprised postmortem: the model, not you, decides how many times to spend. With ordinary token billing you can reason about cost from the size of your prompt. With server tools that intuition breaks, because a single request can trigger three searches, or ten, or a two-minute sandbox session — and each of those has a price on top of tokens. An agent told to "research this thoroughly" and left uncapped is a metaphorical taxi with the meter running and no destination. This section is the seatbelt.

The mental shift is from a fixed-price ticket to a metered ride. Tokens are the ticket — priced by length, roughly predictable. Server tools are the meter — priced by use, and the model is driving. Web search bills per search; code execution bills by sandbox time (with a monthly free allowance). The fix is to bound what the driver can do: max_uses caps how many searches per request, max_tokens caps the length, and allow/block domain lists fence where web search may go. The safety story rhymes with the cost story — the two things that leave your control are the same two you should bound: web search reaches the live internet (fence it with domains) and code execution runs model-written code (but in Anthropic's sandbox, so it can't touch your machine). The common mistake is enabling a tool, watching it work beautifully on one demo query, and shipping without a cap — then discovering the bill after a week of real traffic. Estimate first; the helper below lets you do exactly that, offline, before you spend a cent.

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 wrong split here doesn't cause a bug — it causes an incident. Route "charge the customer's card" to a tool that runs automatically with no veto from your code, and one confused model turn can move real money before a human ever sees it. Route "summarize today's news" to a hand-built client-side tool, and you've spent a sprint reimplementing a search engine Anthropic would have run for free. Both mistakes come from the same root: not asking the one question that actually decides it.

That question is whose house does the action happen in? Think of it as a trust boundary drawn around your systems, your credentials, and your data. Anything that stays outside that boundary — looking something up on the public web, doing a throwaway calculation, fetching a page anyone could fetch — is safe to let Anthropic run automatically, so it wins as a server-side tool: generic, no infra, nothing of yours at risk. Anything that reaches inside the boundary — your database, your billing API, an email sent as you, anything needing your secrets or a human's approval — must stay a client-side tool, because only your code can inject the credentials, gate the call, and log it for audit. When in doubt, keep it client-side: it's easy to move a safe capability out to a server tool later, but you can't un-spend money a server tool already spent. The mistake to avoid is deciding by convenience ("server tools are less work, so use them") instead of by boundary — the extra work of a client-side tool is the control you're paying for.

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

An individual contributor asks "does the tool work?"; a lead asks "what happens when it works ten thousand times a day, and what happens the day the tool version changes underneath us?" Server-side tools are seductive precisely because they're so easy to turn on — one type string and you're live — and that ease is exactly what makes them easy to get wrong at scale. The convenience hides real ownership: a cost meter you don't directly control, a data path that leaves your walls, an error model that never raises, and a version pin that silently depends on the model. None of these bite in a demo; all of them bite in production. The lead's job is to make each one a deliberate decision written down somewhere, not an accident discovered in an incident channel.

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