Skip to main content
Glama

android_explore_and_click

Discover and click Android UI elements via Shadow DOM scanning, bounded scrolling, and graph routing, with hazardous-action confirmation; returns ranked candidates if no confident match.

Instructions

Dynamic Shadow DOM discovery + click with optional A* graph/prefix routing, bounded list scrolling (down/up), hazardous action HITL guard, and automatic Spatial Graph edge recording. Returns top-20 PII-redacted interactive candidates (needs_selection, isError: false) if no confident match is found.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "target": "<target>"
    },
    "name": "android_explore_and_click"
  }
}

Input Schema

NameRequiredDescriptionDefault
targetYesTarget UI label, resource_id suffix, content_desc, or breadcrumb path (e.g. 'Night Light', 'Display > Night Light').
confirmedNoSet to true ONLY after explicit human confirmation in chat to click hazardous/irreversible elements. Default: false.
max_scrollsNoMaximum bounded discovery scrolls (0-10). Default: 3.
device_serialNoOptional ADB device serial. Defaults to the first connected device.
step_timeout_msNoPer-step Shadow DOM settlement timeout in ms (250-10000). Default: 2000.
prefer_graph_routeNoTry known A* graph route (or nearest known prefix vertex) before scanning live Shadow DOM. Default: true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/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 discloses a human-in-the-loop guard for hazardous/irreversible actions, bounded scroll limits (down/up), a side effect (automatic Spatial Graph edge recording), and the no-match return shape (top-20 PII-redacted candidates, isError false). What it omits is the success-path return value and whether graph recording mutates persisted state in a way callers should care about.

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?

Two sentences, front-loaded with the primary action, with no filler or restated title. It loses a point because the phrasing is heavily jargonized ('needs_selection', 'isError: false', 'prefix vertex') and the fallback return contract is tucked into a trailing clause rather than clearly separated.

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 complex, multi-mode tool with no annotations and no output schema, the definition covers the essentials: the discovery/click flow, the hazard gate, the scroll bound, the routing preference, and what comes back when nothing matches. The remaining gap is the success-path response and any permission or device-state assumptions, which an agent would want before calling.

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 100%, so all six parameters are already documented in the schema and the baseline of 3 applies. The description adds only light context on top of that, mainly tying the 'confirmed' flag to the HITL hazard guard and framing max_scrolls as bounded discovery; it adds no syntax or format detail beyond the schema.

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+resource combination ('Shadow DOM discovery + click') and enumerates the capabilities bundled into it (A* routing, bounded scrolling, HITL guard, graph edge recording). An agent can infer it differs from android_tap_element because it performs live discovery rather than tapping an already-known node, but the description never names or contrasts a sibling explicitly.

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

Usage Guidelines3/5

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

Usage is only implied: discovery-first behavior and the fallback of returning candidates suggests 'use when the target is not yet located in the UI tree', and prefer_graph_route hints at a known-route path. There is no explicit statement of when to choose this over android_tap_element or android_get_ui_tree, and no stated preconditions or exclusions.

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