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

mobile-debug-mcp

by clivejefferies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

press_back

Dispatch the Android Back action to navigate to the previous screen, then verify the resulting UI state to confirm the intended destination.

Instructions

Purpose: Dispatch the Android Back action.

Inputs:

  • platform/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 = { key: "back" }

  • success = true when the back action was dispatched

  • failure_code/retryable when dispatch fails

  • ui_fingerprint_before/ui_fingerprint_after when available

Recommended Usage:

  1. Call press_back

  2. If needed, wait for transition using wait_for_*

  3. Verify with expect_screen when a known destination is expected

  4. If verification fails, retry once or recover explicitly

Verification Guidance:

  • Back outcomes can vary by screen, so verify against the intended destination when possible

  • Follow RESOLVE → ACT → WAIT (if needed) → EXPECT

  • 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

NameRequiredDescriptionDefault
deviceIdNoDevice Serial/UDID. Defaults to connected/booted device.
platformNoPlatform (currently only android supported)
responseModeNodebug
expectedStateNo
actionTimeoutMsNoDispatch budget in milliseconds, clamped to 100–30000.
verificationModeNofull
verificationTimeoutMsNoLight observation budget in milliseconds, clamped to 100–60000.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.34.0
    • addedInput schema / allOf
      Added value: +[
+  {
+    "if": {
+      "required": [
+        "expectedState"
+      ]
+    },
+    "then": {
+      "properties": {
+        "deviceId": {
+          "minLength": 1,
+          "not": {
+            "enum": [
+              "booted",
+              "default"
+            ]
+          },
+          "pattern": "\\S",
+          "type": "string"
+        },
+        "platform": {
+          "enum": [
+            "android"
+          ]
+        }
+      },
+      "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"
+}
  2. First observedv0.31.0

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: it states that input dispatch is not atomic with OS delivery, that a fresh UI-tree precondition check runs even with verification disabled, that no automatic unlock or wake occurs, and that dispatch success does not imply app visibility or input readiness. It also defines the lifecycle_state vocabulary (pending_verification, failed) and the PRECONDITION_FAILED/PRECONDITION_UNAVAILABLE semantics.

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 Purpose and structured under labeled sections, so an agent can scan to the relevant block. It is verbose, though — the compact-results and device_readiness paragraphs read as appended boilerplate, and 'Debug output is unchanged' plus the byte-budget explanation are lower-value than the rest.

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?

For a 7-parameter tool with a nested conditional object and no output schema, the description supplies the return envelope (action_id, timestamp, action_type, lifecycle_state, source_module, target.selector, ui_fingerprint_*), failure codes, and the get_interaction_diagnostics escape hatch. Nothing an agent needs to decide what to do after a dispatch appears to be 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 57%, and the description compensates for the biggest gap: expectedState is explained as coming from a successful get_ui_tree on the same explicit platform/deviceId, with the precondition-check semantics spelled out. It also explains the responseMode compact/debug tradeoff and the retained diagnostics reference, but actionTimeoutMs, verificationMode, and verificationTimeoutMs get only oblique mentions ('even with verification disabled'), leaving their tuning behavior to the schema.

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: 'Dispatch the Android Back action.' That immediately separates it from the other input siblings (tap, tap_element, swipe, scroll_to_element) and from the expect_*/wait_for_* family, which are navigation verification rather than dispatch.

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?

Gives an explicit numbered flow (press_back → wait_for_* → expect_screen → retry/recover), plus an exclusion: 'Do not use wait_for_* alone as final verification when an applicable expect_* tool exists.' It also states failure routing (TIMEOUT → retry once, UNKNOWN → snapshot and stop), which is when-to-use guidance for the sibling recovery tools.

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