web-router
One typed interface over many web backends, six methods. The tools describe
your install: their provider enums list only backends this machine holds
keys for, and search/extract work with no key at all. Read the
web-router://capabilities resource once to learn what is configured before
planning around a paid method.
Choose the cheapest method that answers
Work up this ladder and stop at the first rung that serves the task:
search— find pages. Ranked links with page text, about a second, free on the keyless tier. Most questions end here.extract— read pages you already have URLs for, about a second. Prefersearch+extractover anything below: two cheap calls that you compose beat one expensive call you wait on.live_datasits beside it: whenlive_data_sourceslists a vendor's ready-made scraper for the site and item at hand (passqueryto search the catalogue), one run fetches the site now and returns its fields as records, one billed run. All three live data tools needprovidernamed. Readlive_data_sourcefirst — itsinput_schemasays exactly whatinputsto pass, a URL for some sources and an id or a search term for others.research— an agentic run that searches, reads and cross-checks over many turns. Minutes, and it bills. Use only when the question genuinely needs synthesis across many sources that iterativesearch/extractcannot reach in a few calls.browse— a hosted browser agent drives a real browser through a task. Minutes, and it bills. Use when the answer is behind interaction — forms, pagination, dynamic pages — and you can state the task in one sentence.browser_*— you drive the browser yourself.localis free; a cloud session bills per minute until closed. Use when the interaction needs your judgment step by step rather than a delegated task.
Cost rules
- Never start a second
researchorbrowserun for a question whose first run is still going:research/browsereturn a handle after ~25 seconds — pollresearch_status/browse_status(free) instead of calling the method again, which starts and bills a second run. fetch_rawis free and instant: every result carries ahandle, and the backend's full payload is already held for it. Reach forfetch_rawbefore re-calling a tool for more detail.- Close every browser session with
browser_closethe moment you are done. Preferprovider="local"unless the task needs stealth, a proxy country or CAPTCHA solving, which only billed cloud vendors serve. - Leave
providerunset (auto) unless you have a reason: it prefers the backends configured here and falls back to the keyless tier. extractwithprovider="max"reads the page through every configured backend at once and returns the first answer -- the fastest read possible, at one fetch per backend. Use it only when the user has asked for speed over cost, never by default.
What the tools will and will not do
- A parameter a backend cannot serve is refused by name, never silently dropped — on a refusal, drop the option or pick another provider; do not retry the same call unchanged.
- Results are shaped to fit a context window and say when they were cut; the handle gets you the rest. Do not treat a truncation note as missing data.
- Browser tools open only
http:/https:pages andabout:blank; refs frombrowser_snapshotgo stale on the next snapshot or navigation — take a fresh snapshot after the page changes rather than retrying a stale ref. - The server never shows you a CDP URL, live-view URL or credential, and redacts them from every browse and browser output. Do not ask for them or try to reconstruct them.