paseo/public-docs/browser-tools.md

title, description, nav, order, category

title	description	nav	order	category
Browser tools	The browser_* MCP tools agents use to drive Paseo browser tabs.	Tools reference	37	Browser

Browser tools

The browser_* tools are injected into agents alongside the other Paseo MCP tools when browser automation is enabled.

Shared concepts:

• browserId identifies a tab. It comes from browser_new_tab or browser_list_tabs and is required by every tab-scoped tool.
• ref identifies an element, e.g. @e3. Refs come from the latest browser_snapshot of the same tab and expire when the page changes — stale refs return an error instead of acting on the wrong element.
• Every result reports dialogs the page opened during the command (alerts accepted; confirm/prompt/beforeunload dismissed).

Arguments marked ? are optional.

Tabs

Tool	Arguments	Purpose
browser_list_tabs	—	List open tabs in the agent's workspace across connected hosts.
browser_new_tab	url?	Open a tab in the background and return its browserId.
browser_close_tab	browserId	Close a tab and clean up its webview.
browser_resize	browserId, width, height	Resize the tab's viewport — check a layout at phone or tablet dimensions.

Reading the page

Tool	Arguments	Purpose
browser_snapshot	browserId	Return the page as an accessibility tree with element refs.
browser_screenshot	browserId, fullPage?	Capture a PNG of the viewport, or the full page with fullPage.
browser_logs	browserId, maxEntries?	Read recent console messages and network timing entries.
browser_wait	browserId, text? | url?, timeoutMs?	Wait until the page contains text or reaches a URL fragment (exactly one of the two).

Interacting

Tool	Arguments	Purpose
browser_click	browserId, ref, button?, doubleClick?, modifiers?	Click an element — left/right/middle, double-click, keyboard modifiers.
browser_fill	browserId, ref, value	Set the value of an input-like element.
browser_type	browserId, text, ref?	Type text into an element, or into the focused element when ref is omitted.
browser_keypress	browserId, key, ref?	Press a key (Enter, Escape, Tab, Space, …) on an element or the focused one.
browser_hover	browserId, ref	Hover an element — triggers real CSS :hover.
browser_select	browserId, ref, value	Choose an option in a <select>.
browser_drag	browserId, sourceRef, targetRef	Drag one element onto another.
browser_upload	browserId, ref, filePaths	Set files on a file input. Paths must be inside the agent's workspace.
browser_scroll	browserId, deltaX, deltaY, ref?	Scroll the page, or center the wheel input over an element with ref.

Navigation

Tool	Arguments	Purpose
browser_navigate	browserId, url	Go to an http(s) URL.
browser_back	browserId	Go back — errors when there is no history to go to.
browser_forward	browserId	Go forward — errors when there is no forward entry.
browser_reload	browserId	Reload the page.

Scripting

Tool	Arguments	Purpose
browser_evaluate	browserId, function, ref?	Run a JavaScript function in the page. With ref, the resolved element is passed as the first argument. Results return as bounded JSON.

Errors

Tools return structured errors rather than failing silently. The ones agents see most:

Code	Meaning
browser_disabled	Browser tools are turned off on this host.
browser_no_host	No browser host (desktop app) is connected. Retryable.
browser_stale_ref	The ref no longer matches the page — take a new snapshot.
browser_timeout	The element never became actionable, or the wait condition never held.
browser_denied	The action isn't allowed — e.g. a non-http(s) URL, or no history to navigate.