BrowserAttach

Overview Schema Source Related Servers Discussions Admin

browser_upload_file

Assigns absolute browser-host file paths to a file input or pending chooser, supports clearing/canceling selections, and verifies the retained FileList count; multiple files require a multiple input.

Instructions

Set browser-host absolute file paths on one file-input/label ref/selector, or omit target for the pending chooser. [] clears/cancels; multiple files need a multiple input; directories unsupported. assignment_acknowledged confirms the command, not event delivery/upload. count_verified compares retained FileList count (null if unreadable); mismatch is not assignment failure. Observe before uploading again.

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.
`files`	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.

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

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

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

A4/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 does substantial work: it distinguishes assignment_acknowledged from event delivery and from actual upload, and explains that count_verified compares the retained FileList and that a mismatch is not an assignment failure. Still missing: whether paths must exist/be readable by the host, and what happens on timeout or failure.

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-loads the action, then the target-omission case, then constraints and result-interpretation. Every clause carries information, but the ack/count_verified sentences are compressed into telegraphic fragments that take a second read.

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

Completeness4/5

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

For a 12-parameter, nested-object mutation tool with no annotations and no output schema, the description covers the essential semantics: targeting, clearing, multi-file eligibility, and how to interpret the acknowledgement and verification fields. Remaining gaps (error/timeout behavior, path validity preconditions) are secondary.

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 75%, and the description adds semantics the schema does not: files must be host-absolute paths, [] means clear/cancel, >1 file needs a multiple input, directories are rejected, and the target trio (ref/selector/omit) maps to specific behaviors. It says nothing about nth, name, frame/frame_id, timeout_ms or dialog_policy, leaving those 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?

Opens with a specific verb and resource: set browser-host absolute file paths on one file-input/label ref/selector, or on the pending chooser. That is unambiguous and clearly distinct from browser_click/browser_fill/browser_type siblings, though it never names those siblings to sharpen the boundary.

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

Usage Guidelines4/5

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

Gives concrete situational rules: omit target for the pending chooser, pass [] to clear/cancel, multiple files require a multiple input, directories unsupported, and 'observe before uploading again'. It stops short of stating the upstream trigger (e.g. that the chooser must first be opened by a click) or naming an alternative tool.

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

browser_upload_file

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools