Files
paseo/public-docs/browser-tools.md
T
Mohamed Boudra 157abbbbda Let agents choose which desktop opens a browser tab (#10189)
* fix(browser): let agents choose which desktop opens a tab

Registration order sent new tabs to the wrong desktop window. Let the agent discover and select the intended window by name, and require a choice when several windows can open tabs.

* test(desktop): run browser host selection in a fresh app session

Closing the second window can leave the existing browser journey in a different renderer state. Give both journeys their own windows and daemon so the routing test does not change the old test setup.

* fix(browser): keep window names visible and stable across reconnects

Frameless desktop windows need an in-app place to see and copy their name. Give each window one browser host identity so a reconnect replaces a lingering connection without creating a duplicate choice.

* test(desktop): cover host selection in the browser journey

Open the second window after the existing browser checks finish so their setup remains isolated within one CI run.
2026-11-19 13:01:34 +07:00

6.9 KiB

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_hosts — List connected browser hosts by name and ID, including hosts with no tabs.
browser_list_tabs — List workspace tabs and their browser hosts.
browser_new_tab url?, browserHostId? Open a background tab and return its browserId and browser host.
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.

With one host that can open tabs, omit browserHostId. With several, pass an ID from browser_list_hosts. In Paseo Desktop, search for Copy browser host name in the Command Center. The result shows the same name the agent sees. Select it to copy the name. If the selected host is unavailable, list hosts again.

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 entries: URL, timing, size and HTTP status.
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 There is no connected browser host, or the selected host disconnected.
browser_host_ambiguous Several hosts can open tabs. Choose one from the error and retry with its ID.
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.