Web Research

New in v2.5.0. The AI can search the web and read pages while it works. When a model hits an API it does not know, a library quirk, a version-specific change, or an error message it has never seen, it can look it up instead of guessing.

This closes the single biggest reason a generation used to get stuck: a model that was out of its depth had nowhere to go but its own training data. Now it does not need to be smarter. It needs to be connected.

The two tools

The AI sees two tools:

Tool	What it does
web_search(query, max_results=10)	Runs a search and returns ranked results: title, URL, and a snippet for each. Capped at 20 per call.
web_fetch(url, max_chars=20000)	Fetches a page and returns its text with scripts, styles and markup stripped. Long pages are truncated at max_chars.

The default search backend is DuckDuckGo. There is no account to create and no API key to paste. Requests go out with a short timeout, so a slow site cannot stall a generation.

When the tools are available

Web research is part of Agent Mode. The tools are offered to the model only when:

• Agent Mode is on, and
• the model is one that can use tools at all (tier-S or tier-A; see the tier table on the Agent Mode page), and
• the web_search_enabled setting is on (it is by default).

Outside Agent Mode the tools are simply not in the list the model sees, the same rule that gates the bash tool.

What you see in chat

Each call shows up as a short line while the model works:

→ Searching the web: "PySide6 QMediaPlayer setSource deprecated"
→ Reading: https://doc.qt.io/qtforpython-6/PySide6/QtMultimedia/QMediaPlayer.html

The results themselves are not dumped into the chat. The model reads them and moves on; you see what it looked up, not the raw pages.

The per-session budget

Each session gets a research budget, 20 calls by default, shared between searches and page reads. When it is spent the tools stop responding with results and tell the model so, and the model has to work with what it has. The budget resets when you start a new session for the project.

Twenty is deliberately generous. In field testing, a research-heavy session on an unfamiliar library used nine calls; most sessions use none.

Telling the AI to research first

The models do not always decide to search on their own, particularly the cheaper ones. If you already know a task involves something the model is likely to be shaky on, say so in the prompt:

Research the current wger API before writing the client. Do not guess the endpoints.

Look up how PySide6 6.11 handles fullscreen requests in QtWebEngine, then implement it.

That one sentence reliably turns a guess-then-crash cycle into a read-then-write one. It also pairs well with the test gate: research, implement, prove.

Settings

These live in settings.json under your Whittl data directory. They are not yet surfaced in the Preferences dialog.

Key	Default	Meaning
web_search_enabled	true	Offer the tools at all (still requires Agent Mode).
web_search_backend	"duckduckgo"	Search backend. DuckDuckGo is the one that ships; it needs no key.
web_search_max_per_session	20	Combined budget for searches and page reads per session.

Privacy

Search queries go to DuckDuckGo, and page reads go directly to the site being read, from your machine. Neither goes through Whittl's author. Queries are written by the model, and they usually contain the library name, the API, or the error text it is investigating; they do not contain your project's source unless the model quotes a line of it into a query, which it is instructed not to do. See Privacy & Data Flow.

Limitations

• HTML only. web_fetch reads what the server sends. Pages that render their content with JavaScript come back mostly empty.
• DuckDuckGo's HTML results. Some queries return few results or none. The model can rephrase and try again; the budget covers that.
• No images, no PDFs. Only page text.
• Budget is per session, not per project. Switching projects starts a fresh count.

What's next

• Agent Mode — the mode that unlocks these tools and the bash tool
• Test Gate — the other half of "research, implement, prove"
• The AI's Tools — every tool the model can call, and when