Claude's Web Search Tool Documentation: What It Reveals and What It Doesn't

The source is Anthropic's own documentation for the web search tool on the Claude Platform. A developer attaches the tool to an API request. Claude can then run web searches and answer with citations to what it found.

The page is undated. Our evidence base fetched it and recorded what it says on 22 August 2026. Treat every detail below as "as of that check" and confirm the live page before you build on it.

This is vendor documentation, not a study. It describes what the API returns and what it costs. It measures nothing about which sites Claude prefers or why. For how those pieces fit into Claude's answers more broadly, see how Claude picks sources.

The evidence base was built verification-first: an agent fetched the primary page and recorded its wording, and a second agent checked the first for errors. We then compared the response structure with what OpenAI and Perplexity expose for their own search APIs.

We also placed each field against the four stages of an AI answer:

• Parametric: what the model knows with no web access. The tool doesn't touch this.
• Access: whether a crawler can fetch your page at all. The tool doesn't touch this either.
• Retrieval: which pages enter Claude's context for a query. The search results show this.
• Generation: which retrieved pages Claude cites. The citations show this.

That split matters. The docs give you a window onto stages two and three. They give you no lever on any stage.

Each search result carries a small set of fields, and citations carry the quoted text.

Pricing

As verified on 22 August 2026, the tool costs $10 per 1,000 searches plus tokens. Each search counts as one use. Errored searches are not billed. Citation fields are not billed as tokens.

Search is Claude's call

Claude decides whether to search for a given request, and the integrator's system prompt steers that decision. Search is on by default at the organisation level on the API. The evidence base is clear that this default does not describe Claude.ai, where web search is a user toggle with no published default. More on that in whether Claude searches the web by default.

The practical point: the response separates the full retrieval set from the citation set. That is the most useful thing in the documentation.

Exposing page_age is not weighting it

The docs surface page_age. They never say it influences which results Claude selects or cites. No vendor in the evidence base states that it does. Seer reported in July 2026 that 75% of cited pages had been updated within a year, but the study had no control group of non-cited pages and read dates that publishers declare themselves. "Update your pages to get cited" is not supported by either source.

Span citations don't line up with whole-source citations

Claude cites a specific text span of up to 150 characters. Perplexity cites whole sources by integer index. One Claude answer quoting three sentences from your page and one Perplexity answer listing your page once are different units. There is no shared denominator, so any blended citation count across the two mixes them. The difference is explained in why Claude and Perplexity cite differently.

A citation is not proof of use

Mechanistic research (arXiv:2606.28358) repaired over 90% of missed citations by amplifying specific attention heads without changing the sources. Citation output is partly separable from which sources shaped the answer. Counts are a noisy proxy for influence.

Silent on ranking and on the consumer app

The docs don't explain how results are ordered or which sources get chosen. They describe API behaviour, not what a Claude.ai user sees.

Use the tool as a measurement instrument, not as a guide to optimisation.

1. Log retrieved and cited sources separately. For each test question, store every search result (url, title, page_age) and every citation (url, cited_text). The useful questions are which of your URLs get retrieved but never cited, and which sentences get quoted. The retrieved vs cited logging playbook walks through the setup.
2. Hold your conditions fixed. Use the same system prompt every run and record whether search actually fired. Without that, you can't tell a grounded answer from one built on the model's training data.
3. Budget by searches, not prompts. Billing is per search, so estimate cost from the searches you log.
4. Read cited_text against your facts. The quoted span is the sentence Claude relied on. If it's wrong or outdated, you know which page to fix. Stating a specific fact (a price, a number, a one-line definition) on a page Claude can fetch gives it a sentence it can quote.
5. Check access before anything else. Confirm robots.txt allows Claude-SearchBot and that your key facts are in the HTML before JavaScript runs. Vercel found Claude's crawlers fetched JavaScript files on 23.84% of requests but did not execute them. See Anthropic's crawler documentation for the agent names.
6. Record page_age as an observation. Don't feed it into a score or treat it as a lever.

If you want a snapshot before building a pipeline, the free checker on this site shows how AI platforms answer up to three buyer questions about you.

How much does the Claude web search tool cost? When our evidence base checked Anthropic's documentation on 22 August 2026, the tool cost $10 per 1,000 searches plus standard token costs. Each search counted as one use, errored searches were not billed, and citation fields were not billed as tokens. Pricing can change, so confirm it on the live documentation page before you budget a tracking project.

Does page_age affect which sources Claude cites? Nothing published says so. The documentation exposes page_age as when the site was last updated, but exposure is not weighting. No vendor states it influences selection, and the main freshness study had no control group of non-cited pages. Record page_age as an observation. Don't change dates expecting more citations, because a self-declared date proves nothing about what Claude rewards.

Why can't I compare Claude citation counts with Perplexity's? They count different things. Claude cites text spans, each with up to 150 characters of cited_text, so one page can produce several citations in one answer. Perplexity cites whole sources by integer index. Adding the two together mixes units with no shared denominator. Report each engine separately, and compare like with like over time on the same engine.

Does the API behave the same as Claude.ai? Not necessarily. On the API, search is on by default at the organisation level, Claude decides whether to search, and your system prompt steers it. On Claude.ai, web search is a user toggle with no published default, and the evidence base says the API default does not describe consumer behaviour. API logs are a controlled proxy, not a copy of what users see.

Which crawler should I allow so Claude search can reach my pages? Anthropic separates its agents: ClaudeBot collects training data, Claude-SearchBot supports search quality, and Claude-User handles user-triggered fetches. Allowing ClaudeBot alone isn't the search control. Also check your firewall or CDN, since Anthropic warns that IP blocking can stop it reading your robots.txt at all. Allowing a bot buys eligibility, not citations.