Skip to main content
Glama
Sign In
mobile-debug-mcp

mobile-debug-mcp

by clivejefferies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

wait_for_ui_change

Waits for in-place UI mutations or non-navigation updates to stabilize before continuing, using a snapshot revision as the synchronization point. Use for non-navigation changes, not screen navigation.

Instructions

Purpose: Wait for a non-navigation UI mutation or in-place update to become stable.

Inputs:

  • expected_change (optional): hierarchy_diff, text_change, or state_change

  • timeout_ms (optional)

  • stability_window_ms (optional)

  • scope (optional): screen or subtree

  • target (optional): element_id when scope=subtree

Guidance:

  • Prefer wait_for_screen_change for navigation transitions.

  • Prefer wait_for_ui_change for in-place mutations and non-navigation updates.

  • Use the returned snapshot_revision as the observed synchronization point when available.

  • Scoped waits return scope-aware stability metadata and a lightweight change summary.

Failure Handling:

  • TIMEOUT means the UI did not change in a stable way within the allotted time. Device-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit. Set requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.

Input Schema

NameRequiredDescriptionDefault
scopeNoSynchronization scope for the waitscreen
targetNoTarget element_id when scope is subtree
deviceIdNoOptional device id/udid to target
platformNoOptional platform override (android|ios)
timeout_msNoTimeout in ms to wait for change (default 60000)
requireReadyNo
expected_changeNoOptional type of UI change to wait for
stability_window_msNoHow long the change must remain stable before success (default 300)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.34.0
    • addedInput schema / allOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "expectedState"
+      ]
+    }
+  }
+]
    • addedInput schema / properties / requireReady
      Added value: +{
+  "default": false,
+  "type": "boolean"
+}
  2. First observedv0.31.0

TDQS

A4.1/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 mostly succeeds: it discloses that the returned snapshot_revision is the synchronization point, that scoped waits return scope-aware stability metadata plus a change summary, and that TIMEOUT means no stable change occurred. It never explicitly says the tool is non-mutating/read-only, and the trailing readiness sentences ('Device-readiness blockers prevent readiness success', 'Default predicate semantics are unchanged') read as borrowed boilerplate whose meaning is unclear.

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?

Labelled sections (Purpose, Inputs, Guidance, Failure Handling) make it skimmable and the purpose is front-loaded. Some sentences do not earn their place, particularly the readiness-blocker and 'Default predicate semantics are unchanged' lines, which are tangential to a UI-change wait.

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 an 8-parameter tool with no output schema and no annotations, the description covers return values (snapshot_revision, stability metadata, change summary) and failure semantics reasonably well. Gaps remain around whether waits block, how target/scope interact beyond the single clause, and the unexplained readiness semantics.

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 description coverage is 88%, so the schema already documents parameters; the description only restates the optional inputs and their roles via the Inputs list. It adds no semantics for the enum values (hierarchy_diff/text_change/state_change), and omits deviceId, platform, and requireReady from the Inputs list even though requireReady is discussed later in prose.

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?

States a specific verb and resource: 'Wait for a non-navigation UI mutation or in-place update to become stable', with the 'non-navigation' qualifier doing real disambiguating work. It names wait_for_screen_change as the contrasting sibling but never explains how it differs from the sibling wait_for_ui, leaving one overlap unresolved.

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?

Explicitly routes the agent: 'Prefer wait_for_screen_change for navigation transitions' and 'Prefer wait_for_ui_change for in-place mutations and non-navigation updates.' This is a clear when-to-use / when-to-use-something-else rule rather than implied guidance.

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