click
Activate a UI target by snapshot ref, selector, or coordinates. Prefer a ref or selector after a snapshot; use coordinates only when semantic targeting is unavailable. This can change app state.
Instructions
Activate a UI target by snapshot ref, selector, or coordinates. Prefer a ref or selector after a snapshot; use coordinates only when semantic targeting is unavailable. This can change app state. Success means the click was dispatched, not that it landed: use settle or verify to confirm the result without a follow-up snapshot, or wait for the expected screen. A ref or selector target is re-checked for motion before dispatch when the session's previous action just animated the screen, and is dispatched at its resting position; one that has not stopped refuses with target_still_moving rather than acting where it was. Times out after 90s; a caller-supplied budget extends it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | Use raw snapshot data during selector resolution. | |
| udid | No | Apple device or simulator UDID; the selector that pins one device when several share a name. | |
| count | No | Number of press/click repetitions. | |
| debug | No | Enable debug diagnostics. | |
| depth | No | Snapshot traversal depth. | |
| runId | No | Lease run identifier. | |
| scope | No | Snapshot scope selector used before resolution. | |
| button | No | Pointer button for platforms that support mouse buttons. | |
| device | No | Device name selector (a UDID belongs in udid, a serial in serial). | |
| holdMs | No | Hold duration for each action. | |
| serial | No | Android, HarmonyOS, or Vega VVD serial selector. | |
| settle | No | After the action, wait for the UI to go quiet and return the settled diff vs the pre-action tree in the same response. Best-effort; never fails the action. | |
| target | Yes | UI target. This is separate from deviceTarget, which selects the device form. | |
| tenant | No | Remote tenant identifier. | |
| verify | No | Capture cheap post-action evidence (AX digest, node counts, changedFromBefore) instead of a follow-up snapshot. | |
| leaseId | No | Existing lease identifier. | |
| session | No | Agent-device session name. | |
| jitterPx | No | Deterministic per-axis coordinate jitter in pixels (each press offsets x and y by up to this amount). | |
| noRecord | No | Do not record this action. | |
| platform | No | Platform selector used to resolve a device. | |
| doubleTap | No | Request a double-tap action. | |
| timeoutMs | No | Settle: wait deadline in milliseconds (default 10000). | |
| intervalMs | No | Delay between repeated press/click actions. | |
| includeCost | No | Include per-command agent-cost (cost.wallClockMs, …) in structuredContent. Defaults to off; the default response shape is unchanged. | |
| deviceTarget | No | Device target form. Maps to the CLI --target flag. | |
| responseLevel | No | Response verbosity: token-cheap digest / default (today) / full. Defaults to default; the default response shape is unchanged. | |
| settleQuietMs | No | Settle: quiet window in milliseconds (default 500; 300 when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the timeoutMs settle deadline; a replacement from a screen the pre-action capture read as presenting nothing, such as a tab switch, gets no 1500ms confirmation and keeps the asked window. | |
| mcpOutputFormat | No | MCP text content format. Defaults to optimized agent-friendly text; use json for JSON text. Structured content is always returned separately. | |
| androidDeviceAllowlist | No | Android serial allowlist used for device resolution. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Resolved interaction x coordinate when available. | |
| y | No | Resolved interaction y coordinate when available. | |
| ref | No | Snapshot ref without the @ prefix when the target was an @ref. | |
| cost | No | ||
| hint | No | ||
| count | No | Number of press/click repetitions. | |
| button | No | ||
| holdMs | No | Hold duration for each action. | |
| settle | No | ||
| message | No | ||
| warning | No | ||
| evidence | No | ||
| jitterPx | No | Deterministic per-axis coordinate jitter in pixels (each press offsets x and y by up to this amount). | |
| refLabel | No | ||
| selector | No | Selector expression when the target was a selector. | |
| doubleTap | No | Whether the command requested a double-tap action. | |
| intervalMs | No | Delay between repeated press/click actions. | |
| resolution | No | Pre-action disclosure of how the acting path resolved its target. Absent when resolutionDisclosure is inapplicable for the path. | |
| targetKind | Yes | Resolved interaction target kind. | |
| selectorChain | No | ||
| referenceWidth | No | Reference frame width for visualizing the interaction point. | |
| targetHittable | No | ||
| referenceHeight | No | Reference frame height for visualizing the interaction point. | |
| maestroFallbackReason | No | ||
| maestroNonHittableCoordinateFallbackUsed | No | Whether the direct iOS Maestro coordinate fallback was actually used. | |
| maestroNonHittableCoordinateFallbackAllowed | No | Whether the direct iOS Maestro coordinate fallback was allowed for this selector. |