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

mobile-debug-mcp

by clivejefferies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

scroll_to_element

Scrolls a mobile app screen until the specified element becomes visible, using direction and scroll limits to locate off-screen targets for interaction or verification.

Instructions

Purpose: Scroll until a target element becomes visible.

Inputs:

  • platform

  • selector

  • direction, maxScrolls, scrollAmount, 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 = original selector

  • target.resolved = minimal resolved element info when found

  • success = true when scrolling produced a visible target element

  • failure_code/retryable when the target was not reached

  • ui_fingerprint_before/ui_fingerprint_after when available

Recommended Usage:

  1. Resolve the target selector

  2. Call scroll_to_element

  3. If needed, wait for UI stabilization using wait_for_*

  4. Verify with expect_element_visible when the expected element visibility is known

  5. If success=false, follow failure handling before retrying

Verification Guidance:

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

  • Use expect_element_visible when you need an explicit post-scroll confirmation

  • Do not use wait_for_* alone as final verification when an applicable expect_* tool exists

Failure Handling:

  • NAVIGATION_NO_CHANGE → adjust scroll direction or stop

  • TIMEOUT → retry with refined selector or larger scroll budget

  • UNKNOWN → capture a snapshot and stop 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 UDID (iOS) or Serial (Android). Defaults to booted/connected.
platformYesPlatform to operate on (required)
selectorYes
directionNodown
maxScrollsNo
responseModeNodebug
scrollAmountNo
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/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 does substantial work: it defines success (visible target element), lifecycle_state (pending_verification or failed), failure_code/retryable semantics, and explicitly warns that no automatic unlock or wake is performed and that dispatch success does not prove input readiness. Some of this (device_readiness, compact-result budgeting) reads as generic runtime boilerplate shared across the toolkit rather than tool-specific behavior.

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

Conciseness3/5

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

The sectioned layout (Purpose / Inputs / Output Structure / Recommended Usage / Verification / Failure Handling) is front-loaded and scannable, but the two closing paragraphs on compact results and device readiness are generic cross-tool boilerplate that dilutes focus and partly duplicates the Output Structure block.

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 10-parameter, nested-selector tool with no output schema, the description supplies an output field map, failure taxonomy and verification workflow, which is close to sufficient. Gaps remain around selector matching precedence and the meaning of the scroll budget parameters.

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 only 40%, so the description should compensate. It enumerates platform, selector, direction, maxScrolls, scrollAmount and deviceId, but adds no meaning beyond the names (no units for scrollAmount's 0.7 default, no guidance on which selector field takes precedence), and it never mentions verificationMode, verificationTimeoutMs or actionTimeoutMs.

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?

The opening line gives a specific verb and a target-conditioned goal: 'Scroll until a target element becomes visible.' That distinguishes it from raw gesture tools such as swipe, but the purpose statement itself never names a sibling or states the boundary explicitly.

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 'Recommended Usage' and 'Verification Guidance' sections give an ordered workflow (resolve selector, call scroll_to_element, wait_for_* if needed, then expect_element_visible), state when the alternative wait_for_* tools are insufficient, and add per-failure-code handling for NAVIGATION_NO_CHANGE, TIMEOUT and UNKNOWN.

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