Web Search and Web Fetch
Web search finds pages and returns cited results; web fetch reads the full text of a URL or PDF that already appeared in the conversation. Both are server tools: Anthropic runs them during the request and you never return a tool result for them.
When to Use
| Need | Tool |
|---|---|
| Current events, prices, recently changed facts | Web search |
| Answers that must cite sources | Web search (citations always on) or web fetch with citations enabled |
| Summarize or extract from a specific URL or PDF | Web fetch |
| "Read the README of project X" without a URL | Both: search locates it, fetch reads it |
When NOT to Use
- Stable knowledge the model already has
- Pages that require JavaScript rendering, login, or interaction: web fetch does not render JavaScript; use a browser-based tool
- Environments mixing untrusted input with sensitive data, unless you restrict domains (see Step 5)
Workflow
Step 1: Choose versions
Both tools have dated versions. As documented at the time of writing:
| Tool | Versions | Difference |
|---|---|---|
| Web search | web_search_20250305, web_search_20260209, web_search_20260318 |
Basic; adds dynamic filtering; adds response_inclusion |
| Web fetch | web_fetch_20250910, web_fetch_20260209, web_fetch_20260309, web_fetch_20260318 |
Basic; dynamic filtering; cache bypass (use_cache); response_inclusion |
Dynamic filtering lets Claude write code that filters results before they enter context. It runs on code execution that the API provisions automatically, so do not add the code execution tool yourself. Not every model or cloud platform supports the newer versions (some platforms offer only the basic ones); check the tool pages, or read capabilities.server_tools.web_search.supported from the Models API.
An organization admin can disable either tool in the Claude Console; requests then fail with a 400.
Step 2: Declare the tools
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const MODEL = process.env.ANTHROPIC_MODEL!; // a current model ID
const response = await client.messages.create({
model: MODEL,
max_tokens: 16000,
tools: [
{ type: "web_search_20250305", name: "web_search", max_uses: 3 },
{ type: "web_fetch_20250910", name: "web_fetch", max_uses: 5, citations: { enabled: true }, max_content_tokens: 50000 },
],
messages: [{ role: "user", content: "Find the current release notes for project X and summarize breaking changes." }],
});
Parameters worth setting:
| Parameter | Tool | Purpose |
|---|---|---|
max_uses |
Both | Hard cap per request; exceeding it returns a max_uses_exceeded error result |
allowed_domains or blocked_domains |
Both | Domain filtering; never both in one tool (400) |
user_location |
Search | Localize results (type: "approximate" plus city/region/country/timezone) |
citations |
Fetch | Off by default for fetch; always on for search |
max_content_tokens |
Fetch | Truncates large text content to control cost |
Step 3: Read results and errors
Search results arrive as web_search_tool_result blocks whose content is a list of web_search_result items; fetch results arrive as web_fetch_tool_result with a web_fetch_result document. Errors do not raise: the API returns 200 and the result block's content is a single error object.
for (const block of response.content) {
if (block.type === "web_search_tool_result") {
if (Array.isArray(block.content)) {
for (const r of block.content) console.log(r.title, r.url);
} else {
console.warn("search error:", block.content.error_code); // e.g. max_uses_exceeded, too_many_requests
}
}
}
Web fetch error codes include url_not_in_prior_context, url_not_allowed, url_not_accessible, unsupported_content_type, and content_too_large. A search that succeeds with no matches returns an empty list, not an error.
Step 4: Continue conversations correctly
- Send assistant content back exactly as received. Search results carry
encrypted_content(and citations carryencrypted_index) that the API needs on later turns; modified or missing values cause a 400 - Long server-tool turns can end with
stop_reason: "pause_turn". Send the paused assistant message back unchanged to continue - If Claude calls a server tool and one of your client tools in the same parallel group, the response stops with
tool_use; return your client results and the server tool runs on the next request
Step 5: Limit exfiltration risk
Web fetch can only fetch URLs that already appeared in user messages, client tool results, or earlier search/fetch results, never URLs that appear only in Claude's own output or only in the system prompt. It also refuses URLs that look like they contain credentials. Residual risk remains when untrusted content and sensitive data share a conversation, so:
- Use
allowed_domainsfor fetch wherever the set of sites is known - Set
max_uses - Use
url_sourcesto stop specific client tool results from counting as URL sources - Disable fetch entirely on routes that handle secrets
Step 6: Display citations
The docs require citations to the original source when you show API output directly to end users, and advise consulting legal counsel if you rework the output. Render cited_text, title, and url next to the claims they support.
Cost
Web search is billed per search plus tokens for the results that enter context (results count as input tokens on later turns too). Web fetch has no per-call charge beyond the tokens for fetched content, which can be large for long pages and PDFs. Check current rates on the tool and pricing pages, set max_uses, and set max_content_tokens on fetch.
Anti-Patterns
- Treating a 200 response as success without checking for error objects in result blocks
- Stripping
encrypted_contentor rebuilding assistant messages from text only - Expecting fetch to retrieve a URL the model invented
- Unlimited
max_useson user-facing routes - Declaring code execution next to dynamic-filtering web tools
Best Practices
- Pick versions per model and platform from the tool pages
- Cap usage and content size on every route
- Restrict domains for fetch whenever possible
- Preserve assistant blocks verbatim across turns and handle
pause_turn - Show citations to users
- Log
usage.server_tool_useto track search and fetch counts
References
- Web search tool: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
- Web fetch tool: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool
- Server tools (pause_turn, domain filtering): https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools
- Pricing: https://platform.claude.com/docs/en/about-claude/pricing