# Web Search And Fetch

> Give Claude live web access with the Claude API web search and web fetch server tools — choosing tool versions, domain filtering, max_uses, citations, dynamic filtering, handling errors that arrive inside a 200 response, multi-turn requirements, cost, and data-exfiltration safeguards. Use this skill when an application needs current information, cited answers, or the contents of a specific URL or PDF, or when debugging web tool errors, missing citations, or unexpected cost. Activate when: Claude web search, web_search tool, web fetch, web_fetch tool, browse the web API, citations, allowed_domains, blocked_domains, max_uses, dynamic filtering, pause_turn.

- Skill: `latestaiagents/web-search-and-fetch` (Agent Skill)
- Install (CLI): `npx get-skill add latestaiagents/web-search-and-fetch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/latestaiagents/web-search-and-fetch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: latestaiagents (https://skillmd.com/u/latestaiagents)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/latestaiagents/web-search-and-fetch

---


# 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

```ts
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.

```ts
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 carry `encrypted_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:

1. Use `allowed_domains` for fetch wherever the set of sites is known
2. Set `max_uses`
3. Use `url_sources` to stop specific client tool results from counting as URL sources
4. 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

1. Treating a 200 response as success without checking for error objects in result blocks
2. Stripping `encrypted_content` or rebuilding assistant messages from text only
3. Expecting fetch to retrieve a URL the model invented
4. Unlimited `max_uses` on user-facing routes
5. Declaring code execution next to dynamic-filtering web tools

## Best Practices

1. Pick versions per model and platform from the tool pages
2. Cap usage and content size on every route
3. Restrict domains for fetch whenever possible
4. Preserve assistant blocks verbatim across turns and handle `pause_turn`
5. Show citations to users
6. Log `usage.server_tool_use` to 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

