Tool reference

Twenty-nine tools. The arguments come from tools/list at runtime — what is here is the shape, and the four rules that bound it.

Four rules first

These decide more about what an agent can do than the tool list does.

An agent reaches only tabs it opened. create_tab is the only way to get a workable tab. The tabs you opened yourself are never listed, cannot be read and cannot be acted on — not a permission you can grant, a property of the design. The tab you are looking at right now is out of reach even to a session that owns it.
Element refs go stale on navigation. read_page and find hand back refs; they stay valid until the tab navigates, then answer STALE_REF. An element the page has since removed answers ELEMENT_NOT_FOUND. Both mean read the page again.
Two tools are switched off unless your organization switched them on. evaluate_js and upload_file answer POLICY_DISABLED by default, and an admin enables each on the Policy page. upload_file additionally prompts the person at the browser on every single call, naming the file and the destination — no remembered answer satisfies it, so expect a pause rather than reading one as a hang.
A tool failure is a successful response. Browser shut, tab not yours, ref stale — these come back as a normal result carrying isError: true, so the model reads the code and the remediation rather than the client swallowing a protocol fault. Only a malformed envelope or an unknown method is a JSON-RPC error.

`list_browsers`	The browsers you can drive, with state. Call this first.
`select_browser`	Pin one to this session; every later call goes to it — by id, by name, or by a tag its owner gave it in the dashboard.
`get_browser_status`	Which is selected, whether it is connected, and its consent mode.

`create_tab`	Open a tab and take ownership of it. The only way to get one.
`list_tabs`	The tabs opened through this integration — never the user's own.
`close_tab`	Close a tab this session owns.
`activate_tab`	Bring an owned tab to the front, where the person can see it.

`navigate`	Load a URL in an owned tab.
`go_back` · `go_forward`	One history entry, and wait for the load.
`reload`	Reload and wait for the load.
`wait_for`	Wait for a selector, text, a navigation or network idle.

`read_page`	The content, as markdown or an accessibility tree, with refs for what is clickable.
`find`	Elements by CSS selector or visible text. Returns refs.
`get_page_info`	The current URL and title. Cheap.
`screenshot`	Capture the tab as an image.
`read_console`	Console output and browser log entries.
`read_network`	The requests the tab has made.

`click`	By ref, or by coordinates.
`type`	Text into an element, optionally submitting.
`press_key`	A key or a chord — `"Enter"`, `"Control+Shift+Tab"`.
`hover`	Move the pointer onto an element.
`drag`	Press, move, release. Real mouse events, not HTML5 drag-and-drop.
`scroll`	Scroll the tab, or bring an element into view.
`select_option`	Choose in a `<select>`.

`set_viewport`	Lay the tab out at another size, or emulate a device.
`set_zoom`	Page zoom.

`evaluate_js`	Evaluate an expression in the page. The widest thing here — an admin enables it per organization.
`upload_file`	Attach a file from the browser's own machine to a file input. Enabled per organization, and consented per call.

Consent. On confirm_every or allow_local, the first command to a new site asks the person at the browser and the call waits for the answer.
Your organization's host lists. An allowlist or denylist set on the Policy page answers a navigate or create_tab with BLOCKED_ORIGIN, and the extension applies them again to where the tab actually ends up.
A paused browser. Its owner stopped it; every driving tool answers BROWSER_PAUSED until they resume it.
A read-only grant. If a browser was shared with you to look at, the tools that change anything answer PERMISSION_DENIED.

Is something here wrong, or missing? Tell us.