BrowserAttach

Overview Schema Source Related Servers Discussions Admin

browser_click

Click a single page element by ref, selector, or coordinates, with auto-scroll and hit verification. Use it to activate buttons, links, or controls in an attached browser tab.

Instructions

Click exactly one ref/selector/x+y; elements auto-scroll and may recenter once before dispatch, with hit checks. Unmodified left single clicks may target inactive tabs. Native target_verified requires an element; coordinates return null and verify trusted delivery to the hit only. Native select requires select_option.

Input Schema

Name	Required	Description	Default
`x`	No
`y`	No
`nth`	No	Selector only: zero-based DOM index, AX tree order for role.
`ref`	No
`mode`	No	DOM: ref/selector, left single click, no modifiers.	native
`name`	No	role only: exact AX name; empty allowed.
`frame`	No	Child frame: at least one of url/title/path. url/title exact; path=unique nested CSS iframe steps (e.g. ["#frame"]); exclusive with frame_id.
`button`	No		left
`offset`	No	Native element only: ratios within its content quad; hit checks still apply.
`observe`	No	Read this explicit control after the action within its remaining budget; observation is separate from delivery. No assertion or automatic replay.
`frame_id`	No	Selector frame; default main.
`selector`	No	Query by selector_type; role example: selector="link", name="Claim".
`modifiers`	No
`settle_ms`	No	After preparation, before dispatch: ms or uniform [min,max]; min<=max.
`tab_handle`	Yes
`timeout_ms`	No	Total preparation/dispatch/verification and optional observation budget.
`click_count`	No
`dialog_policy`	No	accept/dismiss auto-handle dialogs and return their messages.	ask
`selector_type`	No	Default css. label: exact associated HTML label, whitespace normalized. placeholder: exact attribute.
`coordinate_space`	No	x+y only; document scrolls the top-level page first.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.28.2Oct 29, 2026

addedInput schema / properties / observe

Added value: +{
+  "additionalProperties": false,
+  "description": "Read this explicit control after the action within its remaining budget; observation is separate from delivery. No assertion or automatic replay.",
+  "properties": {
+    "frame": {
+      "additionalProperties": false,
+      "description": "Child frame: at least one of url/title/path. url/title exact; path=unique nested CSS iframe steps (e.g. [\"#frame\"]); exclusive with frame_id.",
+      "properties": {
+        "path": {
+          "items": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "maxItems": 16,
+          "minItems": 1,
+          "type": "array"
+        },
+        "title": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "url": {
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "frame_id": {
+      "description": "Selector frame; default main.",
+      "type": "string"
+    },
+    "max_chars": {
+      "default": 16000,
+      "maximum": 64000,
+      "minimum": 1000,
+      "type": "integer"
+    },
+    "max_options": {
+      "default": 30,
+      "maximum": 100,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "name": {
+      "description": "role only: exact AX name; empty allowed.",
+      "maxLength": 10000,
+      "type": "string"
+    },
+    "nth": {
+      "description": "Selector only: zero-based DOM index, AX tree order for role.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "popup_selector": {
+      "description": "Optional unique CSS popup in the control frame; otherwise use browser-resolved controls/owns relations and control descendants.",
+      "maxLength": 10000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "ref": {
+      "type": "string"
+    },
+    "selector": {
+      "description": "Query by selector_type; role example: selector=\"link\", name=\"Claim\".",
+      "maxLength": 10000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "selector_type": {
+      "description": "Default css. label: exact associated HTML label, whitespace normalized. placeholder: exact attribute.",
+      "enum": [
+        "css",
+        "xpath",
+        "label",
+        "placeholder",
+        "role"
+      ],
+      "type": "string"
+    },
+    "timeout_ms": {
+      "default": 1000,
+      "maximum": 5000,
+      "minimum": 100,
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}

changedInput schema / properties / timeout_ms / description

Previous value: -"Total preparation/dispatch/verification budget."New value: +"Total preparation/dispatch/verification and optional observation budget."

Changed12 schema fields changedv0.24.2Oct 27, 2026

changedInput schema / properties / coordinate_space / description

Previous value: -"Coordinates only; document scrolls the top-level page first."New value: +"x+y only; document scrolls the top-level page first."

changedInput schema / properties / dialog_policy / description

Previous value: -"accept/dismiss returns handled dialog messages."New value: +"accept/dismiss auto-handle dialogs and return their messages."

changedInput schema / properties / frame / description

Previous value: -"Exact child-frame URL/title or CSS iframe path (e.g. [\"#content_iframe\"]); alternative to frame_id. Each path entry uniquely selects an iframe in the preceding document."New value: +"Child frame: at least one of url/title/path. url/title exact; path=unique nested CSS iframe steps (e.g. [\"#frame\"]); exclusive with frame_id."

changedInput schema / properties / frame_id / description

Previous value: -"Selector scope; defaults to main frame."New value: +"Selector frame; default main."

changedInput schema / properties / mode / description

Previous value: -"DOM click requires an element target and a left single click without modifiers."New value: +"DOM: ref/selector, left single click, no modifiers."

changedInput schema / properties / name / description

Previous value: -"role only: exact accessible name; may be empty."New value: +"role only: exact AX name; empty allowed."

changedInput schema / properties / nth / description

Previous value: -"Zero-based match index: DOM order, or AX tree order for role."New value: +"Selector only: zero-based DOM index, AX tree order for role."

changedInput schema / properties / offset / description

Previous value: -"Native element only: ratios within its content quad; offscreen/covered points fail."New value: +"Native element only: ratios within its content quad; hit checks still apply."

changedInput schema / properties / selector / description

Previous value: -"CSS/XPath query, HTML label text, exact placeholder or AX role (e.g. selector=\"link\", name=\"Claim\"), according to selector_type."New value: +"Query by selector_type; role example: selector=\"link\", name=\"Claim\"."

changedInput schema / properties / selector_type / description

Previous value: -"Default css. label matches associated HTML labels with whitespace normalized; role uses browser AX semantics."New value: +"Default css. label: exact associated HTML label, whitespace normalized. placeholder: exact attribute."

changedInput schema / properties / settle_ms / description

Previous value: -"Pause after target preparation, before dispatch: fixed ms or uniform [min, max]."New value: +"After preparation, before dispatch: ms or uniform [min,max]; min<=max."

changedInput schema / properties / timeout_ms / description

Previous value: -"Covers preparation, dispatch and verification."New value: +"Total preparation/dispatch/verification budget."

Changed1 schema field changedv0.24.1Oct 26, 2026

changedInput schema / properties / selector / description

Previous value: -"CSS/XPath query, HTML label text, exact placeholder or AX role, according to selector_type."New value: +"CSS/XPath query, HTML label text, exact placeholder or AX role (e.g. selector=\"link\", name=\"Claim\"), according to selector_type."

First observedv0.24.0Oct 26, 2026

TDQS

B3.3/5.0

Behavior3/5

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

With no annotations, the description carries the full disclosure burden. It usefully describes auto-scrolling, recentering once before dispatch, hit checks, inactive-tab targeting, and trusted-delivery verification for coordinates. But it omits behavior for many of the 20 parameters, such as `dialog_policy`, `observe`, `modifiers`, `click_count`, and `settle_ms`, leaving substantial behavioral gaps.

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?

The description is compact and front-loads the core action and target selection. Sentences are dense but most earn their place; however, the 'target_verified' sentence is jargon-heavy and could be clearer, slightly reducing readability.

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

Completeness2/5

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

This is a complex 20-parameter tool with no annotations and no output schema. The description covers some important behaviors but leaves major gaps around return values, dialog handling, observation semantics, modifier behavior, click_count, and frame targeting, which are needed for correct invocation.

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

Parameters3/5

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

Schema coverage is 65%, in the middle range. The description adds meaningful constraints: exactly one of ref/selector/x+y, coordinates return null verification, and native select must use `select_option`. It does not explain the semantics of most other parameters (modifiers, click_count, dialog_policy, settle_ms, observe, frame nesting, coordinate_space), so it only partially compensates for the schema gaps.

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

Purpose4/5

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

The description states a specific verb ('Click') and the three accepted target forms ('ref/selector/x+y'), and explicitly routes native select interactions to the sibling `browser_select_option`. It does not clearly differentiate from other sibling actions like `browser_hover` or `browser_drag`, so sibling differentiation is only partial.

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

Usage Guidelines3/5

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

It gives some usage constraints (exactly one target, unmodified left single clicks may target inactive tabs, native select requires `select_option`), implying when this tool is appropriate. However, it never states when to prefer hover, drag, double-click, or other alternatives, so guidance is implied rather than explicit.

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

browser_click

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools