mobile-debug-mcp

Overview Schema Source Related Servers Discussions Admin

tap

Dispatch a touch at specific screen coordinates on Android or iOS, optionally verifying resulting UI changes to confirm navigation or local state.

Instructions

Purpose: Dispatch a tap at specific screen coordinates.

Inputs:

x, y coordinates
platform (optional)
deviceId (optional)

Output Structure:

action_id, timestamp (ISO 8601), action_type
lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
source_module: runtime source of the action envelope
target.selector = { x, y }
success = true when the tap was dispatched
failure_code/retryable when dispatch fails
ui_fingerprint_before/ui_fingerprint_after when available

Recommended Usage:

Resolve coordinates deterministically
Call tap
If needed, wait for transition using wait_for_*
Verify with expect_screen or expect_element_visible depending on the intended outcome

Verification Guidance:

Prefer tap_element over tap when an element can be resolved
Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
Use expect_screen for navigation and expect_element_visible for local UI changes
Do not use wait_for_* alone as final verification when an applicable expect_* tool exists

Failure Handling:

TIMEOUT → retry once
UNKNOWN → capture a snapshot and stop

Conditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery. Compact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged. Results include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.

Input Schema

Name	Required	Description	Default
`x`	Yes	X coordinate
`y`	Yes	Y coordinate
`deviceId`	No	Device Serial/UDID. Defaults to connected/booted device.
`platform`	No	Platform to tap on
`responseMode`	No		debug
`expectedState`	No
`actionTimeoutMs`	No	Dispatch budget in milliseconds, clamped to 100–30000.
`verificationMode`	No		full
`verificationTimeoutMs`	No	Light observation budget in milliseconds, clamped to 100–60000.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.34.0Oct 31, 2026

addedInput schema / allOf

Added value: +[
+  {
+    "if": {
+      "required": [
+        "expectedState"
+      ]
+    },
+    "then": {
+      "properties": {
+        "deviceId": {
+          "minLength": 1,
+          "not": {
+            "enum": [
+              "booted",
+              "default"
+            ]
+          },
+          "pattern": "\\S",
+          "type": "string"
+        },
+        "platform": {
+          "enum": [
+            "android",
+            "ios"
+          ]
+        }
+      },
+      "required": [
+        "platform",
+        "deviceId"
+      ]
+    }
+  }
+]

addedInput schema / properties / actionTimeoutMs

Added value: +{
+  "description": "Dispatch budget in milliseconds, clamped to 100–30000.",
+  "type": "integer"
+}

addedInput schema / properties / expectedState

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "snapshotRevision": {
+      "maximum": 9007199254740991,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "snapshotSessionId": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "timeoutMs": {
+      "default": 15000,
+      "maximum": 60000,
+      "minimum": 100,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "snapshotSessionId",
+    "snapshotRevision"
+  ],
+  "type": "object"
+}

addedInput schema / properties / responseMode

Added value: +{
+  "default": "debug",
+  "enum": [
+    "compact",
+    "debug"
+  ],
+  "type": "string"
+}

addedInput schema / properties / verificationMode

Added value: +{
+  "default": "full",
+  "enum": [
+    "none",
+    "light",
+    "full"
+  ],
+  "type": "string"
+}

addedInput schema / properties / verificationTimeoutMs

Added value: +{
+  "description": "Light observation budget in milliseconds, clamped to 100–60000.",
+  "type": "integer"
+}

First observedv0.31.0Jul 29, 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 behavioral burden and does: it discloses the pre-dispatch condition check that runs even with verification disabled, states that PRECONDITION_FAILED/PRECONDITION_UNAVAILABLE mean no input was dispatched, warns the operation is "not atomic with OS input delivery", and specifies the failure policy (TIMEOUT → retry once, UNKNOWN → snapshot and stop). It also flags that dispatch success does not establish app visibility or input readiness and that no automatic unlock/wake occurs — non-obvious operational facts an agent would otherwise get wrong.

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?

Headings (Purpose, Inputs, Recommended Usage, Verification Guidance, Failure Handling) make it skimmable and the purpose is front-loaded in one sentence. The conditional-input paragraph is dense and buries the precondition contract mid-block, and a few lines restate the same RESOLVE/WAIT/EXPECT idea, so it is not maximally tight — but the length is largely earned by the tool's real complexity.

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, yet the description supplies an Output Structure block (action_id, timestamp, lifecycle_state, target.selector, success, failure_code/retryable, UI fingerprints) and explains how to recover full results via get_interaction_diagnostics. For a 9-parameter tool with a nested conditional object and multi-mode verification, nothing an agent needs in order to call it safely is missing.

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 67%, and the description covers the semantically hard parts well: expectedState must come from a get_ui_tree on the same explicit platform/deviceId, it triggers an immediate pre-input tree check, and its timeout semantics are implied. "Compact results summarize observations ... within a byte budget" and "Debug output is unchanged" give operational meaning to responseMode even though the parameter is never named, and the verification-mode defaults are left unexplained.

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?

"Dispatch a tap at specific screen coordinates" is a specific verb plus resource, and the guidance to "Prefer tap_element over tap when an element can be resolved" cleanly separates it from the closest sibling. An agent can tell which of tap / tap_element / swipe to reach for without opening a 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?

It gives an explicit ordered workflow (RESOLVE → ACT → WAIT → EXPECT) with a numbered Recommended Usage sequence, plus the exclusion "Do not use wait_for_* alone as final verification when an applicable expect_* tool exists" and a conditional routing to expect_screen vs expect_element_visible. Both when-to-use and when-not-to-use are named alongside the alternatives.

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

Deploy Server

tap

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools