BrowserAttach

Overview Schema Source Related Servers Discussions Admin

browser_select_option

Sets the chosen option on an HTML select, including hidden selects, and verifies the retained selection after synthetic input/change events.

Instructions

Set an option on one ref/selector HTML select, including hidden selects, via synthetic input/change (events_trusted=false). Disabled/inert targets fail. Verifies retained selection only.

Input Schema

Name	Required	Description	Default
`nth`	No	Selector only: zero-based DOM index, AX tree order for role.
`ref`	No
`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.
`index`	No
`label`	No
`value`	No	Exactly one value/label/index; strings match exactly, index is zero-based.
`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".
`tab_handle`	Yes
`timeout_ms`	No	Total preparation/dispatch/verification and optional observation budget.
`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.

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."

Changed9 schema fields changedv0.24.2Oct 27, 2026

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 / 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 / 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 / timeout_ms / description

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

changedInput schema / properties / value / description

Previous value: -"Choose exactly one of value, label or zero-based index; value/label match exactly."New value: +"Exactly one value/label/index; strings match exactly, index is zero-based."

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

A3.6/5.0

Behavior4/5

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

With no annotations, the description carries the load and does disclose key traits: events are synthetic and untrusted (events_trusted=false), hidden selects are supported, disabled/inert targets fail, and it verifies only retained selection rather than an expected value. It omits what is returned and how failures are surfaced, but the disclosed behavior is substantive.

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?

Three dense sentences, front-loaded with the action and target, followed by constraints. No filler. Slightly terse in the verification clause, which is ambiguous, but the size is appropriate.

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

Completeness3/5

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

A 14-parameter tool with nested objects, no output schema, and no annotations needs more than this. The rich schema covers targeting, but the description does not say what the tool returns, whether an expected option can be asserted, or how the observe parameter relates to the result, leaving an agent to infer the outcome contract.

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 71%, so the schema documents most parameters. The description adds that the target is 'one' select addressed by ref or selector, but says nothing about how the option is identified (value/label/index) or how observe/timeout/dialog_policy interact with delivery — those are left entirely to the schema.

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?

States a specific verb and resource: set an option on one ref/selector HTML select. It adds scope detail (hidden selects supported, synthetic input/change) that makes the operation concrete. It does not name a sibling to distinguish from, e.g. browser_fill/browser_click, but the resource is unambiguous.

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?

Provides useful preconditions (disabled/inert targets fail) and notes hidden selects are handled, which implies 'use this when a <select> exists'. However, there is no explicit guidance on when to prefer this over browser_click or browser_fill, or on what to do if selection fails.

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

browser_select_option

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools