Use Web Search Tools

Letting Claude Look Things Up

Everything in the model's knowledge has a date. Questions about prices, news, software versions, or the current holder of an office depend on information that may have changed since training. The web search tool lets Claude search the internet while it answers, and cite the pages it relied on. It is a server tool, which means the search runs on Anthropic's infrastructure rather than in your code. You enable it in the request, and the search happens inside the same API call.

That difference matters for how the feature is built. With a client tool (Lessons 86–90), your code runs the function and returns the result. With a server tool, your code does nothing during the search. The response you receive already contains the searches Claude made, the results it saw, and the answer it wrote with citations. Your job is to read those parts correctly, to decide what to trust, and to present sources to users.

This lesson explains how server tools differ from client tools, how the search appears in the response, how citations link answers to sources, and how to build a function that collects and checks the sources an answer used.

Server Tools and Client Tools

The two kinds of tool differ in where they run and who completes the work:

Lesson 88 introduced pause_turn. A server-side loop can run for several iterations, and the API may return a paused response partway through. The documentation's continuation pattern sends the paused assistant content back as it is, to let the search finish. A loop that treats pause_turn as an error will stop too early.

Enabling the Tool

The web search tool is declared in the request's tool list, with its type identifier. The type string carries a version, and the exact identifier for the current version is in the web search tool reference, which should be copied from there:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "What is the current Python release?"}],
)

The identifier shown is the one used in the examples in the search documentation at the time of writing. Versions change, and an out-of-date identifier can be rejected, so the reference is the place to confirm it before use.

What the Response Contains

A response that used web search has several kinds of content block, in order. Reading them in sequence explains how the answer was formed:

The text blocks may carry citations. Each citation names a source by URL and title, and quotes the passage it relied on. A citation of type web_search_result_location is the form used for web sources, and it lets an application link each claim to a page.

Citations are evidence, not proof. A citation shows that a page said something, which can be wrong, outdated, or biased. The application must decide how much weight the sources deserve, and whether the answer is consistent with them.

Collecting the Sources

An application that presents sources needs three things: the list of pages searched, the subset the answer cited, and a check that each citation points to a page that actually appeared in the results. The last check guards against malformed or mismatched data. The function below does all three, working from the content blocks:

"""web_sources.py: collect the sources an answer used, and check every citation against the results."""


def collect_sources(content: list[dict]) -> dict:
    searched, results = [], {}
    for block in content:
        if block.get("type") == "server_tool_use":
            searched.append(block["input"].get("query", ""))
        elif block.get("type") == "web_search_tool_result":
            for item in block.get("content", []):
                results[item["url"]] = item.get("title", "")

    cited, problems = {}, []
    for block in content:
        if block.get("type") != "text":
            continue
        for citation in block.get("citations") or []:
            url = citation.get("url")
            if url in results:
                cited[url] = results[url]
            else:
                problems.append(f"citation to a page that was not in the results: {url}")
    return {"queries": searched, "searched_pages": len(results),
            "cited": cited, "problems": problems}


if __name__ == "__main__":
    content = [
        {"type": "server_tool_use", "name": "web_search", "input": {"query": "latest Python release"}},
        {"type": "web_search_tool_result", "content": [
            {"type": "web_search_result", "url": "https://www.python.org/downloads/", "title": "Downloads"},
            {"type": "web_search_result", "url": "https://example.org/news", "title": "Unrelated news"},
        ]},
        {"type": "text", "text": "The newest release is listed on the official downloads page.",
         "citations": [{"type": "web_search_result_location",
                        "url": "https://www.python.org/downloads/", "title": "Downloads",
                        "cited_text": "Python release downloads"}]},
        {"type": "text", "text": " A blog post also mentions it.",
         "citations": [{"type": "web_search_result_location",
                        "url": "https://blog.invalid/post", "title": "Post",
                        "cited_text": "a mention"}]},
    ]
    sources = collect_sources(content)
    print("queries:", sources["queries"])
    print("pages searched:", sources["searched_pages"])
    print("cited:", sources["cited"])
    print("problems:", sources["problems"])

Output:

queries: ['latest Python release']
pages searched: 2
cited: {'https://www.python.org/downloads/': 'Downloads'}
problems: ['citation to a page that was not in the results: https://blog.invalid/post']

How It Works

1. The queries come from server_tool_use blocks, so the application can show what was searched, and can audit whether the searches fit the question.
2. The results are indexed by URL. Every page the search returned is recorded, along with its title, so citations can be matched against them.
3. Each citation is checked. The first is to a page in the results, so it is recorded as cited. The second points to a page that never appeared in the search, which is the kind of mismatch the check exists to catch.
4. The problem is reported, not hidden. An application that displays sources should either drop the unsupported citation, or flag the answer for review.
5. The result separates what was searched from what was cited. Two pages were searched, and only one was cited, which is a useful signal about how the answer was built.

Choosing What to Trust

Search results vary in quality, and the application's policy decides how to handle them. A reasonable policy checks the source's domain against a list of trusted publishers for high-stakes questions, asks for a second source when claims conflict, and labels answers that rest on a single page. The documentation describes options that restrict which domains the search can use, and the reference should be consulted for the exact parameters. Whatever the mechanism, the principle is that a search is a way of gathering evidence, and the application is responsible for judging it.

Cost and Limits

Each search has a cost in addition to the tokens, and the search results themselves are input to the model, so they count toward the token bill. The pricing and any usage limits for the tool are published with the tool's documentation. An application that allows users to trigger searches freely should monitor how often they run, using the same usage tracking as Lesson 125.

Summary

The web search tool is a server tool: Claude searches during the API call, and the response records the queries, the results, and the citations. Reading those blocks in order explains the answer, and checking each citation against the results keeps the sources honest. Search provides current information, but the application remains responsible for weighing it. The next lesson covers a different kind of server-side capability, computer use, in which Claude operates a graphical environment.