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

mobile-debug-mcp

by clivejefferies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

start_app

Launch an Android or iOS app by app ID to begin an automated mobile test session. Dispatches the launch, returning lifecycle state and device readiness so you can wait, then verify the landing screen.

Instructions

Purpose: Launch a mobile app on Android or iOS.

Inputs:

  • platform

  • appId

  • 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 = { appId }

  • success = true when launch was dispatched successfully

  • failure_code/retryable when launch dispatch fails

  • ui_fingerprint_before/ui_fingerprint_after when available

Recommended Usage:

  1. Define the expected landing screen when it is known

  2. Call start_app

  3. If needed, wait for transition using wait_for_*

  4. Verify with expect_screen

  5. If verification fails, retry once or capture a snapshot

Verification Guidance:

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

  • expect_screen is the authoritative verification step when the landing screen is known

  • Do not treat timing or screen change alone as final verification

Failure Handling:

  • TIMEOUT → retry once

  • UNKNOWN → inspect snapshot/logs before retrying 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
appIdYesAndroid package name or iOS bundle id
deviceIdNoDevice UDID (iOS) or Serial (Android). Defaults to booted/connected.
platformYes
responseModeNodebug
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. Changed5 schema fields changedv0.34.0
    • addedInput schema / allOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "expectedState"
+      ]
+    }
+  }
+]
    • addedInput schema / properties / actionTimeoutMs
      Added value: +{
+  "description": "Dispatch budget in milliseconds, clamped to 100–30000.",
+  "type": "integer"
+}
    • 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.3/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 well: it discloses that success only means the launch was dispatched, that pending_verification vs failed lifecycle states exist, which failure codes are retryable, that no automatic unlock or wake is performed, and that Android/iOS readiness signals differ. These are non-obvious behaviors an agent could not infer from structured fields.

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?

Purpose is front-loaded and the labeled sections (Inputs, Output Structure, Recommended Usage, Verification Guidance, Failure Handling) make it scannable despite its length. The trailing paragraph on compact results, get_interaction_diagnostics and debug output is somewhat tangential to launching an app and inflates the definition.

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 a 7-parameter mutation tool with no annotations and no output schema, the description covers output shape, verification workflow, failure handling and readiness caveats, which is close to complete. The remaining gap is that verificationMode's none/light/full options and their cost/benefit tradeoff are never explained anywhere.

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 coverage is 57%, and the description only restates platform, appId and deviceId (already documented in the schema) without adding format or constraint meaning. It says nothing about verificationMode ('full' is the default), responseMode, actionTimeoutMs or verificationTimeoutMs, leaving roughly half the parameters without guidance in either place.

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 first line states a specific verb and resource ('Launch a mobile app on Android or iOS'), which cleanly separates it from siblings such as restart_app, terminate_app, install_app and build_app. An agent knows exactly what this tool does before opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Recommended Usage' block gives an explicit ordered workflow (define expected screen, call start_app, wait_for_*, expect_screen, retry/capture) and 'Verification Guidance' reinforces the RESOLVE → ACT → WAIT → EXPECT pattern with expect_screen as authoritative. It does not explicitly say when NOT to use it (e.g. use restart_app when the app is already running), which keeps it short of a 5.

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