BrowserAttach

Overview Schema Source Related Servers Discussions Admin

browser_fill

Fill or replace text in an input, textarea, or contenteditable element, then verify the retained value, with safeguards that reject known editor proxy textareas.

Instructions

Replace one ref/selector input/textarea/contenteditable and verify retained text. Known Monaco/CM5 proxy textareas are rejected before focus/writes. verification_basis identifies the expectation; verification_source identifies DOM value, selected text or innerText. Native contenteditable readback temporarily selects/reads plain text, then restores selection. CR/CRLF count as LF; requested spaces may retain NBSP. No editor model write, paste, blur or dropdown commit.

Input Schema

Name	Required	Description	Default
`nth`	No	Selector only: zero-based DOM index, AX tree order for role.
`ref`	No
`mode`	No	native: focus/select and insert without character keydown. dom: write visible line breaks without focus, emit synthetic input/change.	native
`name`	No	role only: exact AX name; empty allowed.
`text`	Yes
`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.
`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.
`expected_value`	No	Expected retained text, default text. Verification only; insertion unchanged. No normalization or blur/async wait.

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

Changed10 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 / expected_value / description

Previous value: -"Explicit expected retained text after page formatting; default is text. Changes verification only, never the inserted text. No automatic numeric/date normalization or waiting for blur/async formatting."New value: +"Expected retained text, default text. Verification only; insertion unchanged. No normalization or blur/async wait."

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

addedInput schema / properties / mode / description

Added value: +"native: focus/select and insert without character keydown. dom: write visible line breaks without focus, emit synthetic input/change."

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

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.5/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and delivers substantial behavioral detail: proxy textareas are rejected before focus, native contenteditable readback temporarily selects and restores selection (a real side effect), CR/CRLF collapse to LF, and spaces may retain NBSP. The scoring drag is that it references 'verification_basis' and 'verification_source' as concepts the caller supposedly sets, yet no such parameters exist in the schema, which is a mild misleading signal about how the write is configured.

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

Conciseness3/5

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

The action is correctly front-loaded in the first sentence, but the passage is dense with unexplained jargon (Monaco/CM5, NBSP, ref) and one sentence is spent on verification_basis/verification_source, which map to no schema property. That sentence does not earn its place and inflates the description's cognitive load.

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?

For a 14-parameter tool with nested objects, no annotations, and no output schema, the description covers the core write-and-verify contract plus normalization edge cases, which is a reasonable foundation. It leaves the observe block, dialog_policy, frame targeting, and time budgeting entirely undocumented at the description level, and its dangling verification_* references create an inconsistency an agent must resolve by reading the schema.

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 79%, just below the high-coverage baseline, so the description should compensate somewhat and mostly does not. It adds normalization semantics relevant to text/expected_value (CR/LF collapse, NBSP retention, default expectation) but says nothing about mode, observe, dialog_policy, frame/frame_id, timeout_ms, or nth — all left entirely to the schema. Worse, the verification_basis/verification_source sentence describes behavior for parameters that do not exist in the input schema, adding confusion rather than meaning.

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 first clause states a specific verb and resource set: 'Replace one ref/selector input/textarea/contenteditable and verify retained text.' An agent can tell this writes text into a form control and verifies it, which implicitly separates it from browser_type (key-by-key) and browser_select_option. However, it never names a sibling or explicitly scopes the difference, leaving the distinction (insert without character keydown) to be inferred from the trailing negation.

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?

Usage is only implied through negatives: 'No editor model write, paste, blur or dropdown commit' and rejection of Monaco/CM5 proxy textareas tell the agent what this tool does NOT cover, but there is no positive statement of when to choose browser_fill over browser_type, browser_select_option, or browser_press_key. The reader must reconstruct the decision boundary from sibling names alone.

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

browser_fill

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools