name	browser-guidance
description	Use when operating websites or local web apps through the built-in browser tool.
allowed_tools	["browser","web_fetch","web_search"]

Browser Guidance

Use browser for JavaScript-capable pages. Choose the right web tool once, read with snapshot, act with current refs, then verify with wait/get.

Tool Routing

web_search: static facts, no known URL.
web_fetch: one known URL with readable server HTML.
browser: JavaScript-rendered pages, forms, clicks, login checks, live/interactive data, dashboards, seat maps — in browser's OWN managed instance, NOT the page/app the user has open on their screen.
computer_use: when the task is about the user's OWN live screen or a session they are watching (a page/app/game they already have open) — browser can't see or act on that (separate context; it desyncs). One carve-out: when the live state is SERVER-synced under the same account (a live game, a shared doc), driving the same page here acts on the very state the user is watching — the element rails then beat screen pixels; for anything not server-synced, a second copy silently desyncs from their view. Reserve computer_use for live-screen work; a nameable URL is still web_fetch/browser.
Never shell-scrape JavaScript sites. Empty/partial web_search or web_fetch output on dynamic content means switch to browser.
To wait for a page to change (a result to load, live content to update, the other side of a shared session to move), use the browser's act action with kind: "wait" (and a wait_until target) on THIS session — there is no top-level wait action; don't switch to computer_use to watch a page you are already driving here.

Operating Loop

Use the default profile unless login state, user observation, or a headless-only blocker requires another.
open/navigate, then snapshot; snapshot refs are valid only for that page state.
Pass the intended target when multiple tabs exist.
After page-changing actions, verify with wait/get; snapshot again only when refs or structure changed.

Actions

fill sets a field value; type appends.
submit uses a field ref from the form and clicks the primary submit/search control.
click/submit may return sampled url; fill/type may return sampled value. Receipts are immediate observations, not proof that async navigation or rendering finished.
Use wait for expected URL/text/element/load changes; use get for cheap URL/title/text/ready-state reads.

Tab And Ref Hygiene

Reuse one tab target per flow. If popups or retries create extras, use tabs, then focus or close.
On stale/missing refs: snapshot the same target, retry once with the new ref, then report the blocker.
Avoid snapshot churn; do not snapshot after every successful fill.
The screenshot action returns the page as an image the model actually sees — use it to inspect rendered/visual state. Treat PDFs and downloads as saved artifacts (a path, not seen); read them with file_read.

Stop Conditions

Stop and report for CAPTCHA, 2FA, payment confirmation, missing credentials, URL-policy blocks, unsafe dialogs, repeated launch/profile errors, or the same action failing twice with no new information.

Browser Guidance

Use browser for JavaScript-capable pages. Choose the right web tool once, read with snapshot, act with current refs, then verify with wait/get.

Tool Routing

web_search: static facts, no known URL.

web_fetch: one known URL with readable server HTML.

browser: JavaScript-rendered pages, forms, clicks, login checks, live/interactive data, dashboards, seat maps — in browser's OWN managed instance, NOT the page/app the user has open on their screen.

computer_use: when the task is about the user's OWN live screen or a session they are watching (a page/app/game they already have open) — browser can't see or act on that (separate context; it desyncs). One carve-out: when the live state is SERVER-synced under the same account (a live game, a shared doc), driving the same page here acts on the very state the user is watching — the element rails then beat screen pixels; for anything not server-synced, a second copy silently desyncs from their view. Reserve computer_use for live-screen work; a nameable URL is still web_fetch/browser.

Never shell-scrape JavaScript sites. Empty/partial web_search or web_fetch output on dynamic content means switch to browser.

To wait for a page to change (a result to load, live content to update, the other side of a shared session to move), use the browser's act action with kind: "wait" (and a wait_until target) on THIS session — there is no top-level wait action; don't switch to computer_use to watch a page you are already driving here.

Operating Loop

Use the default profile unless login state, user observation, or a headless-only blocker requires another.

open/navigate, then snapshot; snapshot refs are valid only for that page state.

Pass the intended target when multiple tabs exist.

After page-changing actions, verify with wait/get; snapshot again only when refs or structure changed.

Actions

fill sets a field value; type appends.

submit uses a field ref from the form and clicks the primary submit/search control.

click/submit may return sampled url; fill/type may return sampled value. Receipts are immediate observations, not proof that async navigation or rendering finished.

Use wait for expected URL/text/element/load changes; use get for cheap URL/title/text/ready-state reads.

Tab And Ref Hygiene

Reuse one tab target per flow. If popups or retries create extras, use tabs, then focus or close.

On stale/missing refs: snapshot the same target, retry once with the new ref, then report the blocker.

Avoid snapshot churn; do not snapshot after every successful fill.

The screenshot action returns the page as an image the model actually sees — use it to inspect rendered/visual state. Treat PDFs and downloads as saved artifacts (a path, not seen); read them with file_read.

Stop Conditions

browser-guidance