Computer Use

Overview Schema Source Related Servers Discussions Admin

Snapshot page elements

browser_snapshot

Read-onlyIdempotent

Lists a tab's interactive elements, their click indices, page title and URL so you can choose the right control before clicking. Read-only; re-run after UI changes.

Instructions

List the interactive elements (links, buttons, inputs, tabs, checkboxes, table and grid rows listed as row with their cell text, and other clickable elements) on the page in one of the agent's tabs, with the index each one has for browser_click, plus the page title and URL. Inputs show their type, such as input[password], and text the page lets you edit in place shows as [editable], such as span[editable] (click it, or browser_fill it); checkboxes, radios and switches are named by their label and show their state, such as (checked) or (unchecked, disabled). Works on a background tab, so the user can be looking at something else. Use it before every browser_click, because indices change when the page changes; use browser_read for the page's text. Read-only. Automatically scopes to the topmost visible dialog when one is open, naming it on a dialog: line, excluding hidden/inert controls but retaining reachable offscreen controls. Results report scope, total and truncation. Continue with offset and limit on the same tab/session; indices stay global across pages of an unchanged UI. Snapshot again after UI changes. While the page has a JavaScript dialog open (alert, confirm, prompt), the snapshot shows the dialog's type, message and dialog_id instead, for browser_handle_dialog.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "tab_id": "<tab_id>"
    },
    "name": "browser_snapshot"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Maximum controls returned per page (default 250, maximum 250).
`offset`	No	Control offset for pagination (default 0). Use the continuation offset from the previous result on an unchanged UI.
`tab_id`	Yes	tab_id of one of the agent's tabs, from browser_open_tab or browser_list_tabs
`session_id`	No	Stable task or thread ID. Pass the same value on every browser call for this task. Different IDs isolate tabs and cleanup within one MCP process. Omit for the default process session.
`wait_timeout_ms`	No	Bound for wait_for_selector in milliseconds (default 8000, maximum 10000; 0 checks once). Requires wait_for_selector. Timeout preserves action success and returns current state. Use browser_snapshot with the same wait to re-observe without repeating an action.
`wait_for_selector`	No	Wait for any visible element matching this CSS selector in the page, including open shadow roots (web components); child frames are not searched, and a timeout says how many were visible. On actions requires return_state=true. Returns readiness met, timeout or error; only this condition is checked, not general app readiness. Prefer a selector specific to the expected new UI.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.11.2Nov 5, 2026

changedInput schema / properties / wait_for_selector / description

Previous value: -"Wait for any visible element matching this CSS selector in the top-level document (not frames or shadow roots). On actions requires return_state=true. Returns readiness met, timeout or error; only this condition is checked, not general app readiness. Prefer a selector specific to the expected new UI."New value: +"Wait for any visible element matching this CSS selector in the page, including open shadow roots (web components); child frames are not searched, and a timeout says how many were visible. On actions requires return_state=true. Returns readiness met, timeout or error; only this condition is checked, not general app readiness. Prefer a selector specific to the expected new UI."

Changed4 schema fields changedv0.7.1Oct 15, 2026

addedInput schema / properties / limit

Added value: +{
+  "description": "Maximum controls returned per page (default 250, maximum 250).",
+  "maximum": 250,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "Control offset for pagination (default 0). Use the continuation offset from the previous result on an unchanged UI.",
+  "maximum": 2147483647,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / wait_for_selector

Added value: +{
+  "description": "Wait for any visible element matching this CSS selector in the top-level document (not frames or shadow roots). On actions requires return_state=true. Returns readiness met, timeout or error; only this condition is checked, not general app readiness. Prefer a selector specific to the expected new UI.",
+  "maxLength": 2000,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / wait_timeout_ms

Added value: +{
+  "description": "Bound for wait_for_selector in milliseconds (default 8000, maximum 10000; 0 checks once). Requires wait_for_selector. Timeout preserves action success and returns current state. Use browser_snapshot with the same wait to re-observe without repeating an action.",
+  "maximum": 10000,
+  "minimum": 0,
+  "type": "integer"
+}

Changed1 schema field changedv0.4.3Sep 23, 2026

addedInput schema / properties / session_id

Added value: +{
+  "description": "Stable task or thread ID. Pass the same value on every browser call for this task. Different IDs isolate tabs and cleanup within one MCP process. Omit for the default process session.",
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}

Changed1 schema field changedv0.3.1Sep 16, 2026

changedInput schema / properties / tab_id / description

Previous value: -"From browser_open_tab or browser_list_tabs"New value: +"tab_id of one of the agent's tabs, from browser_open_tab or browser_list_tabs"

First observedv0.3.0Sep 16, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only/idempotent, but the description adds substantial non-structured behavior: works on a background tab, auto-scopes to the topmost visible dialog with a 'dialog:' line, excludes hidden/inert controls while retaining reachable offscreen ones, reports scope/total/truncation, and switches to dialog type/message/dialog_id when a JS dialog is open.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what it returns and the core reason to call it (indices for browser_click), and nearly every clause carries information. It is a dense single paragraph with many parentheticals, which slightly hurts scannability but avoids filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex observation tool with no output schema, the description covers output shape (control list, index, title, URL, state markers, truncation/scope metadata), pagination, dialog behavior, and background-tab operation. An agent has enough to call it correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents tab_id, offset, limit and wait parameters; the description still adds cross-call semantics the schema lacks — 'Continue with offset and limit on the same tab/session; indices stay global across pages of an unchanged UI.' Modest but genuine value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the interactive elements ... on the page in one of the agent's tabs') and enumerates what counts (links, buttons, inputs, tabs, checkboxes, grid rows), plus the key output value: the index used by browser_click. It also names the sibling it is not (browser_read) for page text, so an agent can distinguish it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use: 'Use it before every browser_click, because indices change when the page changes; use browser_read for the page's text.' Adds re-observe conditions ('Snapshot again after UI changes') and routes the dialog case to browser_handle_dialog. No major inference left to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.