A web search tool for AI agents that brings back the page text

Why does an agent need page text and not just snippets?

Because the answer is rarely in the snippet. A results page gives a title and one or two lines chosen by the search engine. The number, date or rule your user asked about sits further down the page.

An agent that only sees snippets has two bad options. It can answer from a fragment and risk being wrong, or it can call a second tool to fetch each page. The second option doubles the round trips and the tool definitions.

With LLMWebSearch, the first pages arrive already read. Navigation, ads and cookie banners are removed, so the model spends its tokens on content. The remaining results still carry their snippets, which help the model decide whether to search again.

How should the search tool be defined?

Keep the schema small: one required query and, at most, one or two switches. Models call simple tools more reliably. The example below exposes a recent flag that maps to time_range=month; everything else is fixed in your code.

The function returns plain text, not JSON. Each source starts with a number, a title and a URL, followed by its Markdown. That layout makes citations like [2] natural for the model.

If your agent already ships a tool called web_search, as Claude Code and OpenClaw do, give yours another name such as search_web. Two tools with one name confuse the model.

When should an agent search, and how often?

Search when the answer depends on facts that change or that the model cannot know. Prices, versions, laws, schedules and recent events qualify. Definitions and stable knowledge usually do not.

Write that rule into the system prompt, and add a budget. Three habits help:

• Plan before searching. Ask the model to write its queries first. Two precise queries beat five vague ones.
• Cap the calls. Allow, say, four searches per user turn. Raise the cap only for research tasks.
• Stop when sources agree. If three independent pages say the same thing, the agent can answer.

How do I keep the context window under control?

Three parameters decide how much text reaches the model. read sets how many pages are read, from 0 to 10. max_chars caps each page, from 500 to 50,000 characters. max_results sets how many results are listed, from 1 to 20.

For a chat agent, read=3 with max_chars=4000 returns about 12,000 characters of page text per search. That leaves room for several searches in one conversation. For a research job that summarises as it goes, longer pages are fine.

The word_count field tells you how long the full page was before the cut. The agent can use it to decide whether to fetch more with the extract endpoint.

What happens when a page cannot be read?

The result still comes back, with its title, URL and snippet, but without content. A content_status field says why.

• blocked_by_robots: the site's robots.txt does not allow our reader.
• blocked_by_site_policy: A site that sets Content-Signal: ai-input=no in its robots.txt keeps its pages out of your results' content.
• target_refused: the site answered with a refusal; its status is in target_status.
• fetch_failed or fetch_timeout: the page did not load in time.

When a site turns our reader away, the result comes back without content and with the site's status: we never solve CAPTCHAs, sign in to accounts or work around a block or a paywall. Tell the agent to use the snippet, or another source, when a page comes back empty. The search itself is still one credit, whatever happened to each page.

Why not use the search tool built into the model?

Built-in tools are convenient but give you less control. As of October 22, 2026, OpenAI's web_search tool costs $10 per 1,000 calls plus the search content billed as input tokens. Anthropic's Claude web search also costs $10 per 1,000 searches plus token costs. Gemini 3 grounding includes 5,000 free searches a month on the paid tier, then costs $14 per 1,000.

These tools mostly return a written answer with citations, not the raw pages. They also tie your search to one model vendor. A standalone tool works with any model and lets you set the length of every page. The built-in tools comparison has the full table.

What does it cost to run an agent on LLMWebSearch?

One credit per search when read is 3 or less. An assistant used by a team, answering 100 questions a day with 4 searches each, runs about 12,000 searches a month. 25,000 searches at $41.25 covers that month and most of the next.

A coding agent used by one developer may search 20 times a day, or about 600 times a month. 5,000 searches at $9.25 then lasts several months, because credits never expire. The cost guide shows the arithmetic for larger workloads.