desktop-touch-mcp

Overview Schema Source Related Servers Discussions Admin

browser_search

Search the current page for elements by text, regex, role, ariaLabel, or CSS selector and get confidence-sorted selectors to pass to browser_click.

Instructions

Grep-like element search across the current page. by: 'text' (literal substring), 'regex', 'role', 'ariaLabel', 'selector' (CSS). Returns results[] sorted by confidence descending — pass results[0].selector to browser_click. Pagination via offset/maxResults. Caveats: Use browser_overview for broad discovery; use browser_search when you know specific text or role to target. Typed errors: code:'BrowserSearchNoResults' (broaden the by:'text' substring or relax the by:'regex' pattern; switch to browser_overview to enumerate selectors), code:'BrowserSearchTimeout' (reduce maxResults / narrow scope), code:'ScopeNotFound' (the scope CSS selector did not match — verify the selector or omit scope), code:'BrowserNotConnected' (call browser_open first, or browser_open({launch:{}}) to auto-spawn).

Input Schema

TableJSON Schema

Name	Required	Description
`by`	Yes	Search axis: text/regex/role/ariaLabel/selector
`port`	No	Chrome/Edge CDP remote debugging port (default 9222; configurable via desktop-touch-config.json)
`scope`	No	CSS selector to limit the search scope.
`tabId`	No	Tab ID from browser_open. Omit to use the first page tab.
`offset`	No	Offset into the result set (default 0).
`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).
`pattern`	Yes	Pattern to match against the chosen axis.
`maxResults`	No	Max results returned (default 50).
`visibleOnly`	No	Only visible elements (default true). Set false to include hidden ones with confidence penalty.
`caseSensitive`	No	Case-sensitive matching for text/regex (default false).
`inViewportOnly`	No	Only currently-in-viewport elements (default false).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv2.3.1Oct 13, 2026

addedInput schema / $schema

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

removedInput schema / additionalProperties
```
Removed value: -false
```
addedInput schema / properties / offset / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / port / description

Previous value: -"Chrome/Edge CDP remote debugging port."New value: +"Chrome/Edge CDP remote debugging port (default 9222; configurable via desktop-touch-config.json)"

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

Changed14 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 / by

Added value: +{
+  "description": "Search axis: text/regex/role/ariaLabel/selector",
+  "enum": [
+    "text",
+    "regex",
+    "role",
+    "ariaLabel",
+    "selector"
+  ],
+  "type": "string"
+}

addedInput schema / properties / caseSensitive

Added value: +{
+  "default": false,
+  "description": "Case-sensitive matching for text/regex (default false).",
+  "type": "boolean"
+}

addedInput schema / properties / inViewportOnly

Added value: +{
+  "default": false,
+  "description": "Only currently-in-viewport elements (default false).",
+  "type": "boolean"
+}

addedInput schema / properties / maxResults

Added value: +{
+  "default": 50,
+  "description": "Max results returned (default 50).",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Offset into the result set (default 0).",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / pattern

Added value: +{
+  "description": "Pattern to match against the chosen axis.",
+  "minLength": 1,
+  "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 / scope

Added value: +{
+  "description": "CSS selector to limit the search scope.",
+  "type": "string"
+}

addedInput schema / properties / tabId

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

addedInput schema / properties / visibleOnly

Added value: +{
+  "default": true,
+  "description": "Only visible elements (default true). Set false to include hidden ones with confidence penalty.",
+  "type": "boolean"
+}

addedInput schema / required

Added value: +[
+  "by",
+  "pattern"
+]

First observedv0.6.2Apr 14, 2026

TDQS

A4.8/5.0

Behavior5/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 so: it discloses result ordering ('sorted by confidence descending'), the chaining contract ('pass results[0].selector to browser_click'), pagination behavior, and a catalog of typed error codes with remediation. This is behavior an agent could not infer from the schema alone.

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-loaded with the core purpose and the distinguishing sibling comparison, then moves to output shape, pagination, and error handling. It is dense and mostly earns its length, though the error-code enumeration is long enough to risk burying the primary usage rule.

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

Completeness5/5

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

There is no output schema, so the description must characterize the return value — and it does ('results[] sorted by confidence descending', results[0].selector). For an 11-parameter tool, it covers purpose, alternatives, chaining, pagination, and failure modes without leaving gaps.

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 100%, so baseline is 3, but the description adds meaning beyond it — explaining the 'by' axes inline, the offset/maxResults pagination pair, and how results feed into browser_click. It does not add much detail on visibleOnly or caseSensitive beyond what the schema already states.

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?

Opens with a specific verb+resource: 'Grep-like element search across the current page', immediately conveying the operation and its scope. It explicitly positions itself against sibling browser_overview, so an agent can distinguish the two without opening either schema.

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?

States the selection rule directly: 'Use browser_overview for broad discovery; use browser_search when you know specific text or role to target.' It also prescribes fallback behavior per error (broaden substring, relax regex, switch to browser_overview to enumerate selectors), giving explicit when-to-use and when-to-switch guidance.

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

browser_search

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools