Skip to main content
Glama
Harusame64

desktop-touch-mcp

by Harusame64
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

wait_until

Wait for a specified UI, browser, or terminal condition (window, element, URL, output) to become true, replacing screenshot-polling loops with server-side polling.

Instructions

Purpose: Server-side poll for an observable condition — eliminates screenshot-polling loops when waiting for state changes. Details: condition selects what to watch: window_appears/window_disappears (target.windowTitle required), focus_changes (optional target.fromHwnd), element_appears/value_changes (target.windowTitle + target.elementName required, UIA; min 500ms interval), ready_state (target.windowTitle; visible + not minimized), terminal_output_contains (target.windowTitle + target.pattern required [+target.regex:true], needs terminal tools loaded), element_matches (target.by + target.pattern required, needs browser tools loaded), url_matches (target.pattern required [+target.regex:true]; matches the active tab's location.href via CDP — use for SPA route changes, redirects, OAuth flows). Returns {ok:true, elapsedMs, observed} on success, or WaitTimeout error with suggest hints. timeoutMs default 5000 (max 60000). Prefer: Use instead of run_macro({sleep:N}) + screenshot loops. Use terminal_output_contains to detect CLI command completion. Use element_matches for browser DOM readiness after navigation. Use url_matches when the URL is the most reliable signal (SPA routing / redirect cascades). Caveats: terminal_output_contains/element_matches/url_matches need a browser CDP connection (open --remote-debugging-port=9222 first). element_appears/value_changes spawn a UIA process per poll (interval floor 500ms). On timeout: {ok:false, code:'WaitTimeout', error, suggest:[...]}; suggest[] may open with a line earned by the last poll — read it, do not index. Those two also return context.lastLook: did the element resolve, why not, and for value_changes baseline/latest — the field's VALUE, so a masked credential arrives as mask characters. Other codes: 'ToolError' (validation / missing hook — read the message), 'BrowserNotConnected' (re-attach via browser_open), and 'WindowExcluded' for a target this server may not act through, answered at once rather than polled. Branch on code. Examples: wait_until({condition:'window_appears', target:{windowTitle:'Save As'}, timeoutMs:10000}) wait_until({condition:'terminal_output_contains', target:{windowTitle:'Terminal', pattern:'$ '}, timeoutMs:30000}) wait_until({condition:'element_matches', target:{by:'text', pattern:'Submit', scope:'#checkout-form'}}) wait_until({condition:'url_matches', target:{pattern:'/dashboard'}, timeoutMs:15000}) wait_until({condition:'url_matches', target:{pattern:'^https://app\\.example\\.com/orders/[0-9]+$', regex:true}})

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
targetNoTarget descriptor — fields used depend on condition. Accepts an object literal or a JSON-stringified object.
includeNoOptional 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).
conditionYesCondition to wait for. See per-condition target requirements.
timeoutMsNoMaximum time to wait (default 5000ms)
intervalMsNoPoll interval (default 200ms — terminal_output_contains uses 500 internally)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.9.2
  2. Removedv1.8.0
  3. Addedv1.6.0
  4. Removedv1.5.1
  5. Addedv1.5.0
  6. Removedv1.4.3
  7. Addedv1.4.2
  8. Removedv1.4.0
  9. Changed1 schema field changedv1.2.1
    • 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"
+}
  10. Addedv1.1.1
  11. Removedv1.1.0
  12. Addedv1.0.3
  13. Removedv0.15.7
  14. Changed8 schema fields changedv0.10.0
    • 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 / condition
      Added value: +{
+  "description": "Condition to wait for. See per-condition target requirements.",
+  "enum": [
+    "window_appears",
+    "window_disappears",
+    "focus_changes",
+    "value_changes",
+    "element_appears",
+    "ready_state",
+    "terminal_output_contains",
+    "element_matches"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / intervalMs
      Added value: +{
+  "default": 200,
+  "description": "Poll interval (default 200ms — terminal_output_contains uses 500 internally)",
+  "maximum": 5000,
+  "minimum": 50,
+  "type": "integer"
+}
    • addedInput schema / properties / target
      Added value: +{
+  "description": "Target descriptor — fields used depend on condition. Accepts an object literal or a JSON-stringified object."
+}
    • addedInput schema / properties / timeoutMs
      Added value: +{
+  "default": 5000,
+  "description": "Maximum time to wait (default 5000ms)",
+  "maximum": 60000,
+  "minimum": 100,
+  "type": "integer"
+}
    • addedInput schema / required
      Added value: +[
+  "condition"
+]
  15. First observedv0.6.2

TDQS

A5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses success/error response shapes, all relevant error codes, browser/CDP prerequisites, per-poll UIA process spawning, the 500ms interval floor, and context.lastLook behavior including masked credentials. This goes far beyond what the schema or annotations convey.

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

Conciseness5/5

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

The description is long but well-structured with Purpose, Details, Prefer, Caveats, and Examples sections, front-loading the most decision-relevant information. Each sentence earns its place given the nine-condition matrix, and the examples cover representative invocation patterns without becoming redundant.

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?

Given no annotations and no output schema, the description fully covers return values, error codes, prerequisites, condition-specific target requirements, and example calls. An agent can select and invoke this tool correctly for any of the nine conditions without needing additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds critical meaning: per-condition target field requirements, optional regex flags, the internal 500ms interval for terminal_output_contains, the minimum interval for UIA conditions, and URL/SPA matching semantics. The target property in the schema is only described as 'depends on condition', so this text is essential for correct invocation.

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 description opens with a specific verb and resource: 'Server-side poll for an observable condition', and immediately ties the purpose to eliminating screenshot-polling loops. It also differentiates itself from sibling tools such as run_macro and screenshot by explicitly contrasting those alternatives.

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 'Prefer' section explicitly states when to use this tool instead of run_macro({sleep:N}) + screenshot loops, and maps each condition to its intended use case (terminal completion, DOM readiness, SPA routing, redirects). The caveats further clarify when CDP prerequisites or UIA constraints apply.

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

Deploy Server

Other Tools