find
Locate UI elements on devices by text, label, value, role, or ID, then run actions like click, type, or wait.
Instructions
Find by text/label/value/role/id and run action
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for command execution. | |
| raw | No | ||
| last | No | ||
| udid | No | iOS device UDID selector. | |
| debug | No | Enable debug diagnostics. | |
| depth | No | ||
| first | No | ||
| query | Yes | ||
| runId | No | Lease run identifier. | |
| value | No | ||
| action | No | ||
| device | No | Device name selector. | |
| record | No | Force-record this out-of-band observation into a repair-armed heal (mutually exclusive with noRecord). Authored replay steps are recorded automatically and never need this. On find, valid only for a read-only action. | |
| serial | No | Android device or Vega VVD serial selector. | |
| target | No | Alias for deviceTarget on commands without a UI target field. Interaction commands reserve target for the UI element. | |
| tenant | No | Remote tenant identifier. | |
| leaseId | No | Existing lease identifier. | |
| locator | No | ||
| session | No | Agent-device session name. | |
| noRecord | No | Do not record this action. | |
| platform | No | Platform selector used to resolve a device. | |
| stateDir | No | Agent-device state directory. | |
| timeoutMs | No | ||
| 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. | |
| daemonBaseUrl | No | Remote daemon base URL. | |
| responseLevel | No | Response verbosity: token-cheap digest / default (today) / full. Defaults to default; the default response shape is unchanged. | |
| daemonAuthToken | No | Remote daemon auth token. | |
| iosXctestEnvDir | No | Writable directory for iOS XCTest runner env overlays. | |
| mcpOutputFormat | No | MCP text content format. Defaults to optimized agent-friendly text; use json for JSON text. Structured content is always returned separately. | |
| iosXctestrunFile | No | Externally built iOS XCTest runner .xctestrun artifact path. | |
| iosSimulatorDeviceSet | No | iOS simulator device-set path used for device resolution. | |
| androidDeviceAllowlist | No | Android serial allowlist used for device resolution. | |
| iosXctestDerivedDataPath | No | Derived data path for external iOS XCTest runner execution. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Resolved x coordinate for mutating find actions. | |
| y | No | Resolved y coordinate for mutating find actions. | |
| ref | No | Snapshot ref without the @ prefix when the find action returns one. | |
| cost | No | ||
| node | No | Snapshot node for find get_attrs/get_text. | |
| text | No | Text value returned by find get_text. | |
| found | No | Whether a wait/exists/read-only find satisfied its condition. | |
| query | No | Query argument used for the find action. | |
| settle | No | ||
| locator | No | Locator kind used for the find action. | |
| matches | No | Every match for the read-only find list action (#1625): { ref, node } each. | |
| message | No | Diagnostic message for mutating find actions. | |
| waitedMs | No | Milliseconds waited for a read-only find condition. | |
| refsGeneration | No | ADR 0014 ref frame epoch for read-only find actions. |