desktop-touch-mcp

Overview Schema Source Related Servers Discussions Admin

browser_navigate

Navigate a browser tab to a URL via CDP, with auto-guard that verifies tab readiness and returns status. For slow pages, follow with wait_until to confirm the page has finished loading.

Instructions

Navigate a browser tab to a URL via CDP Page.navigate — more reliable than clicking the address bar. Pass tabId+port so the server auto-guards (verifies tab readyState) and returns post.perception.status. lensId is optional for advanced pinned-tab workflows. Caveats: Does not block until page load completes — the Page.navigate ack confirms only that the navigation request was accepted (frameStoppedLoading / loaderId observation is internal). Follow with wait_until({condition:'ready_state' or 'element_matches'}) or repeated browser_eval polling for slow pages. Typed errors: code:'NavigateFailed' (Page.navigate rejected — DNS failure, malformed URL, network unreachable; check URL + connectivity), code:'BrowserNotConnected' (CDP disconnect — re-attach via browser_open), code:'AutoGuardBlocked' when the auto-guard refuses (e.g. tab still loading) — the error message preserves the guard's 1-sentence recommended next step (most often wait_until({condition:'ready_state'}) then retry).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`url`	Yes	URL to navigate to
`port`	No	Chrome/Edge CDP remote debugging port.
`tabId`	No	Tab ID from browser_open. Omit to use the first page tab.
`lensId`	No	Optional perception lens ID. Guards (target.identityStable) are evaluated before navigating, and a perception envelope is attached to post.perception on success.
`include`	No	Optional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients).
`narrate`	No	Narration level. rich includes UIA or browser state diff when supported, and is withheld with post.rich.diffDegraded when the diff cannot be shown to describe the window that was acted on.	minimal
`waitForLoad`	No	When true (default), wait for document.readyState === 'complete' before returning. Use waitForLoad:false for the legacy behavior (return immediately after Page.navigate). Accepts the strings "true"/"false".
`loadTimeoutMs`	No	Max milliseconds to wait for page load when waitForLoad=true (default 15000). On timeout, returns ok:true with readyState set to current state and hints.warnings=['NavigateTimeout'].

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.0.0Sep 24, 2026

changedInput schema / properties / narrate / description

Previous value: -"Narration level. rich includes UIA or browser state diff when supported."New value: +"Narration level. rich includes UIA or browser state diff when supported, and is withheld with post.rich.diffDegraded when the diff cannot be shown to describe the window that was acted on."

Addedv1.12.0Jul 8, 2026
Removedv1.10.4Jun 16, 2026
Addedv1.9.2May 25, 2026
Removedv1.8.0May 23, 2026
Addedv1.6.0May 16, 2026
Removedv1.5.1May 12, 2026
Addedv1.5.0May 12, 2026
Removedv1.4.3May 11, 2026
Addedv1.4.2May 10, 2026
Removedv1.4.0May 9, 2026

Changed1 schema field changedv1.2.1May 3, 2026

addedInput schema / properties / include

Added value: +{
+  "description": "Optional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Addedv1.0.3Apr 26, 2026
Removedv0.15.7Apr 20, 2026

Changed11 schema fields changedv0.10.0Apr 16, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

addedInput schema / additionalProperties
```
Added value: +false
```

removedInput schema / properties / _stub

Removed value: -{
-  "description": "Stub tool — arguments ignored."
-}

addedInput schema / properties / lensId

Added value: +{
+  "description": "Optional perception lens ID. Guards (target.identityStable) are evaluated before navigating, and a perception envelope is attached to post.perception on success.",
+  "type": "string"
+}

addedInput schema / properties / loadTimeoutMs

Added value: +{
+  "default": 15000,
+  "description": "Max milliseconds to wait for page load when waitForLoad=true (default 15000). On timeout, returns ok:true with readyState set to current state and hints.warnings=['NavigateTimeout'].",
+  "maximum": 30000,
+  "minimum": 500,
+  "type": "integer"
+}

addedInput schema / properties / narrate

Added value: +{
+  "default": "minimal",
+  "description": "Narration level. rich includes UIA or browser state diff when supported.",
+  "enum": [
+    "minimal",
+    "rich"
+  ],
+  "type": "string"
+}

addedInput schema / properties / port

Added value: +{
+  "default": 9222,
+  "description": "Chrome/Edge CDP remote debugging port.",
+  "maximum": 65535,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / tabId

Added value: +{
+  "description": "Tab ID from browser_connect. Omit to use the first page tab.",
+  "type": "string"
+}

addedInput schema / properties / url

Added value: +{
+  "description": "URL to navigate to",
+  "type": "string"
+}

addedInput schema / properties / waitForLoad

Added value: +{
+  "default": true,
+  "description": "When true (default), wait for document.readyState === 'complete' before returning. Use waitForLoad:false for the legacy behavior (return immediately after Page.navigate). Accepts the strings \"true\"/\"false\".",
+  "type": "boolean"
+}

addedInput schema / required
```
Added value: +[
+  "url"
+]
```

First observedv0.6.2Apr 14, 2026

TDQS

A4.1/5.0

Behavior3/5

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

The description discloses several valuable non-obvious traits: ack semantics, auto-guard behavior, post.perception.status, and three typed errors with remediation. However, it asserts 'Does not block until page load completes' while the schema's waitForLoad defaults to true and waits for readyState 'complete', a conflict that can mislead agents about default behavior. Since no annotations exist, the description carries the full burden, making this inconsistency more damaging.

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 front-loaded and information-dense, with a clear caveat label and a structured error taxonomy. It is slightly overstuffed—repeated wait_until advice and internal CDP jargon (frameStoppedLoading/loaderId) could be trimmed—but overall every sentence earns its place.

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?

Despite having no output schema or annotations, the description covers return perception status, error codes, auto-guard refusal, and recommended follow-ups for an 8-parameter CDP tool. The only serious omission is the waitForLoad/loadTimeoutMs behavior, which is contradicted by the caveat and leaves slow-page guidance incomplete.

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 100%, so the baseline is 3. The description adds useful context for tabId/port (auto-guard) and lensId (pinned-tab workflows), but it does not compensate for the waitForLoad inconsistency nor add semantics for include/narrate beyond what the schema already describes.

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?

The opening sentence names a specific verb (navigate), resource (browser tab to URL), and mechanism (CDP Page.navigate), and explicitly contrasts with clicking the address bar, which separates it from sibling browser tools. The lensId and perception-status details further clarify its scope.

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?

The description explicitly directs follow-up with wait_until or browser_eval polling for slow pages, and names browser_open for reconnection after BrowserNotConnected. It also frames the tool as more reliable than the address-bar alternative, giving an agent enough context to choose among siblings.

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

browser_navigate

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools