The web search tool

The text editor tool is a built-in tool where Anthropic owns the schema and you own the implementation. The web search tool takes it one step further — Anthropic owns both. You declare that you want web search enabled, and Claude handles the entire search flow server-side, returning results with citations. It's the lowest-effort production tool in the module, and the one you'll reach for whenever a user question is about the real, current world.

Opt-in at the organisation level

Before you can use web search, your Anthropic organisation must enable it in the console. It's turned off by default for privacy reasons. Head to console.anthropic.com/settings/privacy, find the Web Search setting, and toggle it on. The setting applies to your whole organisation — once enabled, any API call from any key in that org can use the tool.

This is one of the few Claude features that requires configuration outside your code. If you get a "tool not enabled" error when you run your first web search call, this is almost certainly why.

The schema

The web search schema is short — you just declare the tool exists and cap how often it can be used:

web_search_schema = {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
}

Three fields:

• type — a version string pinned to a specific release of the web search tool. Like the text editor tool, the version evolves over time and you'll update it when you upgrade models.
• name — always "web_search".
• max_uses — the ceiling on how many searches Claude can perform in a single conversation. Claude may do follow-up searches based on initial results, so this is a hard cap on search volume, not a target.

Add this schema to your tools=[...] list alongside any custom tools. That's it — you don't write a handler, because Claude performs the search itself and delivers the results.

The response structure

When Claude uses the web search tool, the response content has a richer block structure than anything you've seen so far. You may see:

• Text blocks — Claude's narration ("Let me search for current information on that.")
• ServerToolUseBlock — shows the exact query Claude ran. Useful for debugging and for displaying a "searched for: ..." indicator to the user.
• WebSearchToolResultBlock — contains the overall search results payload.
• WebSearchResultBlock — individual search results, each with a title, URL, and possibly snippets.
• Citation blocks — inline annotations that tie specific statements in the text back to the source they came from.

Rendering this response well in a UI typically means:

• Render text blocks as the main body of Claude's answer.
• Render WebSearchResultBlocks as a compact source list, usually at the top or bottom of the response.
• Render citations inline with the text, showing the source domain, page title, URL, and quoted source text that supports each claim.

The citation blocks are the part that makes this tool genuinely useful for production — users can see exactly which source supports each claim, and verify the answer themselves. That traceability is the difference between "AI says X" and "AI says X because this specific page says X, and here's the exact quote."

Restricting the domains Claude can search

For cases where you need authoritative sources, allowed_domains restricts search results to a whitelist:

web_search_schema = {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
    "allowed_domains": ["nih.gov", "pubmed.ncbi.nlm.nih.gov"],
}

Now Claude's searches only return results from those domains. Useful for:

• Medical or health information — restrict to peer-reviewed or government health sources (nih.gov, pubmed.ncbi.nlm.nih.gov, who.int) rather than random wellness blogs.
• Legal or regulatory content — restrict to .gov or specific regulator sites.
• Internal or partner knowledge — if your organisation has a known-good documentation site or wiki, restrict to that.
• Financial or investment topics — restrict to SEC filings, reputable analyst sites, or official company investor relations pages.

allowed_domains doesn't make the answer correct, but it does make the sources predictable and auditable, which is half the battle for anything compliance-adjacent.

Quick reference

| Field | Type | Required | Description | |---|---|---|---| | type | string | Yes | Version string, e.g. "web_search_20250305" | | name | string | Yes | Always "web_search" | | max_uses | int | Yes | Max number of searches per conversation | | allowed_domains | string[] | No | Whitelist — only these domains returned |

When to reach for web search

Use the web search tool when your user's question involves:

• Current events — news, recent releases, anything that happened after Claude's training cutoff
• Specialised or niche information — details of specific products, companies, papers, or standards that may not be in training data
• Fact-checking and verification — grounding claims in named, linkable sources
• Research tasks — the kind of "find me five articles about X" work you'd normally open a tab for

Skip it when the question is answerable from general knowledge or from data you already have in your own system — searching when you don't need to costs latency and tokens, and introduces variability into answers that could have been deterministic.

Minimum viable integration

The simplest possible integration:

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3,
    },
]

response = client.messages.create(
    model=model,
    max_tokens=2000,
    messages=messages,
    tools=tools,
)

No handler. No dispatch table. Claude decides whether to search, runs the search on its side, and returns the full response — text, sources, citations — in one call. For a huge category of "answer a question with current information" features, this is as close to zero-effort as tools get in the Claude API.