# Tool catalogue — flutter-dev-agents / phone-controll

_Auto-generated by `scripts/generate_tool_catalogue.py`. Don't edit by hand; re-run after tool changes._

**Total tools registered:** 109.

Tiers:
- **BASIC** — visible at `describe_capabilities(level="basic")` (~18 tools). What a 4B agent sees.
- **INTERMEDIATE** — adds dev-loop, code-quality, multi-window, AR/Vision essentials.
- **expert** — everything else (visible by default).

## Tools

| Tool | Tier | Description |
|---|---|---|
| `assert_no_errors_since` | BASIC | Fail if any ERROR-level log entries appeared in the last since_s seconds. Use as a checkpoint after each test step. |
| `assert_pose_stable` | INTERMEDIATE | Capture N pose samples of one ArUco marker and assert frame-to-frame stability under translation + rotation thresholds. Use to filter single-frame outliers before AR placement assertions. |
| `assert_visible` | expert | Assert an element is visible. Returns the element or errors. |
| `attach_debug_session` | expert | Attach to a `flutter run` started outside this MCP via its VM service URI. Advanced; not implemented in v1. |
| `boot_simulator` | INTERMEDIATE | Boot an iOS simulator by name (e.g. "iPhone 15") or UDID. Returns the booted Device — use its serial in select_device. |
| `build_app` | INTERMEDIATE | Build an app bundle. Android: `flutter build apk`. iOS: `flutter build ipa`. |
| `calibrate_camera` | expert | Calibrate camera intrinsics from chessboard images. Needs ≥3 images with a detected (cols x rows) inner-corner pattern. Returns fx/fy/cx/cy + distortion + reprojection error. |
| `call_service_extension` | expert | Call a registered VM service extension (ext.flutter.*). Returns the result and elapsed_ms. |
| `capture_release_screenshot` | expert | Full-res PNG for app-store listings. Returns metadata + 256px thumbnail; full-res file is NOT inlined. Open release_dir in Finder to drag into Play/App Store. |
| `check_environment` | BASIC | DOCTOR. Run this FIRST in any session. Reports the status of every external dependency (adb, flutter, patrol, pymobiledevice3) with concrete fix commands for any red items. |
| `clear_app_data` | INTERMEDIATE | Clear an app's data (`pm clear`). |
| `close_ide_window` | INTERMEDIATE | Close an IDE window by project_path or window_id. |
| `compare_screenshot` | INTERMEDIATE | Pixel-diff an actual screenshot against a golden image. Returns a similarity score and a diff image highlighting changed regions. For AR/UI regression testing on a fixed camera stand. |
| `compress_png` | expert | Resize (optional) + palette-recompress a PNG in place. Use when an external screenshot (e.g. from computer-use) is bloating the conversation; 3-5x smaller, visually lossless for UI content. Returns bytes_before/after. |
| `dart_analyze` | INTERMEDIATE | Run `dart analyze --format=json` and return structured issues (severity, code, message, file, line, column). Optional min_severity filter. |
| `dart_fix` | expert | Run `dart fix`. apply=false (default) is a dry-run; apply=true modifies files. Returns count of fixes + files changed. |
| `dart_format` | INTERMEDIATE | Run `dart format` on a file or directory. dry_run=true reports what would change without rewriting. |
| `describe_capabilities` | BASIC | Return platforms, frameworks, gates, vision ops, plan_schema, and the tool subset for the given level (basic/intermediate/expert). Call first before planning. 4B models should pass level='basic'. |
| `describe_tool` | BASIC | Full description, JSONSchema, and a copy-pasteable example for ONE tool. Fetch this only for the tool you're about to call to save context for small LLMs. |
| `detect_markers` | expert | Detect ArUco fiducial markers in an image. Returns id, corners, and center for each. Default dictionary DICT_4X4_50. |
| `disk_usage` | expert | Report bytes used in the artifacts root, bucketed: screenshots, originals (.orig.png companions), goldens, release, logs, recordings, other. Useful before pruning. |
| `dump_render_tree` | expert | Convenience for ext.flutter.debugDumpRenderTree. |
| `dump_ui` | expert | Return the current UI hierarchy as XML. |
| `dump_widget_tree` | expert | Convenience for ext.flutter.debugDumpApp. |
| `extract_ui_graph` | expert | Parse the device UI into a typed graph: clickables, inputs, texts, images. Cheaper than vision-model calls. Aligned with CogAgent / ShowUI / OS-Atlas pattern. |
| `fetch_artifact` | expert | Read a previously emitted artifact by path. Returns text content or, for binary files, metadata + sha256. Use after a tool returned data_truncated=true. |
| `find_element` | expert | Find a UI element by text, resource id or class. Returns null if not found. |
| `find_flutter_widget` | expert | Scan lib/ for widget classes whose name matches a regex. Returns file paths + line numbers. |
| `flutter_pub_get` | expert | Run `flutter pub get` to refresh dependencies. |
| `flutter_pub_outdated` | expert | Run `flutter pub outdated` to see stale dependencies. |
| `focus_ide_window` | expert | Bring the IDE window to the foreground (macOS osascript). |
| `force_release_lock` | expert | ADMIN. Break a lock without holding it — use only when another session has crashed and the lock is stuck. |
| `get_artifacts_dir` | BASIC | Return the current artifacts directory. |
| `get_selected_device` | BASIC | Return the currently selected device, or null. |
| `grant_permission` | INTERMEDIATE | Grant a runtime permission to an app. |
| `grep_logs` | expert | Grep a saved log artifact for a regex with line context. Returns line numbers + before/after context for each match. |
| `index_project` | expert | Walk a project, chunk md/dart/py files, push into Qdrant. Idempotent on (collection, source). Run once per project, or on a watcher. |
| `infer_camera_pose` | expert | Estimate camera pose from a single ArUco marker of known physical size. Returns rvec/tvec. Default intrinsics are coarse — supply your stand's camera matrix for accurate results. |
| `inspect_project` | BASIC | Detect what kind of project lives at a path (Flutter, native, RN, web) and which test frameworks apply. Call this before run_patrol_* / run_integration_tests so you know which framework will execute. |
| `install_app` | INTERMEDIATE | Install an app bundle. Provide bundle_path (.apk/.ipa/.app) or project_path. platform defaults to the selected device's platform. |
| `is_ide_available` | expert | Returns the IDE version string if installed; else error. |
| `launch_app` | BASIC | Launch an app. If activity is omitted, uses the LAUNCHER intent. |
| `list_avds` | INTERMEDIATE | List available Android Virtual Devices (emulator -list-avds). |
| `list_debug_sessions` | INTERMEDIATE | List all debug sessions owned by this MCP process. |
| `list_devices` | BASIC | List all attached Android and iOS devices. |
| `list_ide_windows` | INTERMEDIATE | List IDE windows opened by this MCP process. |
| `list_locks` | INTERMEDIATE | List active device locks across all MCP sessions. Stale locks (holder process gone) are auto-cleaned and not returned. |
| `list_missing_widget_keys` | expert | Scan lib/ for tap-target widgets (Buttons, GestureDetector, InkWell, Switch, Checkbox, etc.) that lack a `key:` parameter. The single highest-leverage diagnostic for agents driving Flutter via Patrol or tap_text — selectors without Keys are the dominant source of test fragility (Drizz May 2026: 30-50% of Flutter QA time is selector maintenance). Returns file paths, line numbers, snippets. |
| `list_patrol_tests` | INTERMEDIATE | PREFERRED for Flutter. Discover Patrol-style integration test files under `integration_test/` (any *_test.dart). Returns paths Claude can feed into run_patrol_test. |
| `list_simulators` | INTERMEDIATE | List iOS Simulators via xcrun simctl. By default includes shutdown ones so they can be booted. |
| `list_skills` | expert | Return every named skill in the library, ordered by use count. Use to discover what the agent has learned. |
| `mcp_ping` | BASIC | Identify the running MCP: version, git sha, uptime, image backends, tool count. Call first if a feature seems missing — a stale subprocess is usually the cause. |
| `narrate` | expert | Turn an MCP envelope into a one-line prose summary. Useful for small models that need to echo results back to the user without re-parsing JSON. |
| `new_session` | BASIC | Create a new artifacts session directory. |
| `notify_webhook` | expert | POST a structured event to an n8n / Slack / generic webhook. Use for outbound notifications (build green, release ready). Lock down hosts via MCP_WEBHOOK_ALLOWLIST. |
| `ocr_screenshot` | expert | Extract text from a PNG via Vision / Tesseract / easyocr (tried in order). Use to 'read' a screen without a vision model. Reads full-res original when present. |
| `open_project_in_ide` | INTERMEDIATE | Open a project in a NEW VS Code window (`code -n <path>` by default). Tracks the spawned PID for later close. |
| `patch_apply_safe` | expert | Apply a unified diff to a git project; auto-rollback if quality_gate fails. Requires a clean working tree (or force=true). Leaves changes uncommitted for human review. |
| `prepare_for_test` | BASIC | Atomic CLEAN handoff: stop_app + clear_app_data + press home + evidence screenshot. Returns proof the device is in clean state. |
| `press_key` | expert | Press a hardware/system key (back, home, enter, ...). |
| `promote_sequence` | expert | Tag a slice of the current session trace as a named, reusable skill. Skill names are snake_case, no spaces. Voyager-style skill library. |
| `prune_originals` | expert | Delete `.orig.png` companions older than older_than_days (defaults to MCP_ORIG_RETENTION_DAYS or 14). Conservative: never touches capped screenshots, goldens, or release. Run with dry_run=true first to see what would be removed. |
| `quality_gate` | INTERMEDIATE | Composite check before claiming 'done': dart analyze + dart format check + flutter unit tests. Returns overall_ok=true only when zero analyzer errors, format-clean (if required), and passing tests. |
| `read_debug_log` | INTERMEDIATE | Recent log slice from a debug session (app + daemon events). Filters by level and a window in seconds. |
| `read_logs` | BASIC | Read recent logcat lines. DISCIPLINE: call once per phase end, with a tag filter when possible. Use as evidence for the report — not as a polling primitive. For 'wait until X happens' use tail_logs. |
| `recall` | BASIC | Retrieve top-k chunks matching a query (skill, docs, code, or trace). Use instead of loading the whole SKILL — saves context for 4B agents. |
| `recall_corrective` | expert | Recall + relevance grading + scope fallback. Use when the agent needs an answer it can trust; returns confidence and a diagnosis. |
| `release_device` | BASIC | Release this session's lock on a device. With no serial, releases the currently selected device. Always call this at end of session. |
| `replay_skill` | expert | Re-execute a stored skill through the dispatcher. Records success/failure on the library so high-success skills get prioritised over time. |
| `restart_debug_session` | INTERMEDIATE | Hot reload (default) or hot restart (full_restart=true). |
| `run_integration_tests` | INTERMEDIATE | Run integration tests on the selected device. Routes to Patrol if the project supports it, otherwise plain `flutter test integration_test/`. |
| `run_patrol_suite` | INTERMEDIATE | PREFERRED for Flutter. Run an entire Patrol test directory (default `integration_test/`) on the selected device. |
| `run_patrol_test` | INTERMEDIATE | PREFERRED for Flutter. Run a single Patrol test file on the selected device. Locale-independent (drives by widget Keys), works for AR / Vision / native plugin code paths via patrol_finders + native automator. |
| `run_quick_check` | expert | Fast health check: dart analyze + format check + git status. Skips unit tests; use quality_gate for the full bar. |
| `run_test_plan` | BASIC | Execute a declarative YAML test plan (apiVersion phone-controll/v1). Walks phases, enforces entry/exit assertions, captures artifacts. Provide plan_path (file) OR plan_yaml (inline). Call validate_test_plan first if unsure of schema. |
| `run_unit_tests` | INTERMEDIATE | Run `flutter test` (unit / widget tests, no device). |
| `save_golden_image` | INTERMEDIATE | Capture a screenshot and save it under <project>/tests/fixtures/golden/<label>.png (or under the session artifacts if no project_path). Bootstraps goldens for compare_screenshot regression tests. |
| `scaffold_feature` | expert | Generate a Clean-Architecture skeleton (entity, failure, repo, use case, BLoC, page, tests) for a feature_name in snake_case. Idempotent unless overwrite=true. |
| `select_device` | BASIC | Pick a device for this session AND acquire its cross-session lock. Returns DeviceBusyFailure if another session holds it — set force=true to break the lock, or call release_device when you're done. |
| `session_summary` | BASIC | Return the audit trail of every tool call in the current session. Useful for agent self-reflection and report generation. |
| `set_agent_profile` | BASIC | Apply a known agent profile (claude / haiku / qwen2.5-7b / qwen2.5-14b / llava / default). Flips image cap, auto-narrate, strict schemas, Reflexion retries at once. |
| `setup_webdriveragent` | expert | Build WebDriverAgent for an iOS device (one-time per device). Clones the repo if needed, runs `xcodebuild build-for-testing`. Short-circuits if a previous successful build is recorded (unless skip_if_built=false). |
| `start_debug_session` | INTERMEDIATE | Boot `flutter run --machine` against the selected device and wait for app.started. Requires this session to hold the device lock. |
| `start_emulator` | INTERMEDIATE | Boot an Android emulator and wait until it registers with adb (up to 90s). Returns the emulator's serial. |
| `start_recording` | expert | Start a screen recording. Stop with stop_recording. |
| `start_wda_on_simulator` | expert | Launch WebDriverAgent against an iOS simulator (detached) and wait for it to serve HTTP on `port`. Call this when `tap`/`swipe` returned next_action='start_wda_on_simulator'. Requires setup_webdriveragent to have run once. Returns when ready or fails clearly with the xcodebuild error. |
| `stop_app` | BASIC | Force-stop an app. |
| `stop_debug_session` | INTERMEDIATE | Stop a debug session. Defaults to the most-recently-started. |
| `stop_recording` | expert | Stop the active screen recording and pull the file. |
| `stop_virtual_device` | INTERMEDIATE | Shut down an Android emulator (emulator-XXXX) or iOS simulator (UDID). Auto-detects by serial format. |
| `summarize_session` | BASIC | Boil the session trace down to a 3-line elevator pitch: headline, recent successes, recent errors. |
| `swipe` | expert | Swipe between two points. |
| `tail_debug_log` | INTERMEDIATE | Wait until a regex matches a log line, or timeout. |
| `tail_logs` | INTERMEDIATE | Stream logcat until a regex matches a line, or timeout. |
| `take_screenshot` | BASIC | Capture a PNG screenshot to the artifacts dir. Call only at phase boundaries; label as <PHASE>-<outcome>. Don't shoot speculatively or after a failed tool call. |
| `tap` | expert | Tap at absolute screen coordinates. |
| `tap_and_verify` | BASIC | Tap text then assert an expected element appears within timeout_s. Use for any tap that should produce visible state. |
| `tap_text` | expert | Tap an on-screen element matched by visible text. USE FOR SYSTEM UI ONLY (Settings, permission dialogs, ATT prompts). For your own app's UI prefer Patrol via run_patrol_test — locale-independent. |
| `toggle_inspector` | expert | Toggle the Flutter widget inspector overlay (ext.flutter.inspector.show). |
| `tool_usage_report` | expert | Aggregate the session trace into per-tool usage stats. Surfaces dead tools, top-N callers, and per-tool error rates. |
| `type_text` | expert | Type text into the focused field. |
| `uninstall_app` | INTERMEDIATE | Uninstall an app by package id. |
| `validate_test_plan` | BASIC | Lint a YAML plan against the v1 schema WITHOUT running it. Returns the parsed plan on success or a precise InvalidArgumentFailure. Cheap iteration loop for agents authoring plans. |
| `vm_evaluate` | expert | Evaluate a Dart expression at a frame in an isolate of the active debug session. Defaults to the first runnable isolate and frame 0. Requires the [debug] extra. |
| `vm_list_isolates` | expert | List Dart isolates in the active debug session via the VM service WebSocket. Requires the [debug] extra (websockets). |
| `wait_for_ar_session_ready` | INTERMEDIATE | Tail device logs until ARKit/ARCore reports normal tracking. Use as a gate before AR placement assertions. |
| `wait_for_element` | expert | Wait until an element is visible. Errors on timeout. |
| `wait_for_marker` | expert | Poll screenshots until an ArUco marker appears or timeout. Useful for gating AR test phases on physical-scene readiness. |
| `write_vscode_launch_config` | expert | Write `.vscode/launch.json` for a Flutter project so F5 in VS Code mirrors the agent's debug session. Idempotent unless overwrite=true. |

## Input schemas

### `assert_no_errors_since`

- `since_s: integer` — Lookback window in seconds (default 30).
- `tag: string` — Optional log tag filter.
- `serial: string` — Device serial. Defaults to the selected device.

### `assert_pose_stable`

- `marker_id: integer` *(required)*
- `samples: integer` — Default 10.
- `sample_interval_s: number` — Default 0.2.
- `max_translation_m: number` — Default 0.005.
- `max_rotation_deg: number` — Default 2.0.
- `marker_size_m: number` — Default 0.05.
- `serial: string` — Defaults to selected device.

### `assert_visible`

- `text: string`
- `resource_id: string`
- `timeout_s: number`
- `serial: string` — Device serial. Defaults to the selected device.

### `attach_debug_session`

- `vm_service_uri: string` *(required)*
- `project_path: string` *(required)*

### `boot_simulator`

- `name_or_udid: string` *(required)* — Simulator name or UDID.

### `build_app`

- `project_path: string` *(required)* — Path to the Flutter project root.
- `mode: string`
- `platform: string`
- `flavor: string`

### `calibrate_camera`

- `image_paths: array` *(required)*
- `board_cols: integer` — Inner corner columns. Default 9.
- `board_rows: integer` — Inner corner rows. Default 6.
- `square_size_m: number` — Square size in meters. Default 0.025.

### `call_service_extension`

- `method: string` *(required)* — e.g. ext.flutter.debugDumpApp
- `args: object`
- `session_id: string`

### `capture_release_screenshot`

- `label: string` *(required)* — Filename (no slashes). Conventionally '01-home', '02-feed', etc., one per store-listing slot.
- `thumbnail_long_edge: integer` — Thumbnail dimension cap (default 256, min 64).
- `serial: string` — Device serial. Defaults to the selected device.

### `clear_app_data`

- `package_id: string` *(required)* — Android application id, e.g. com.example.app
- `serial: string` — Device serial. Defaults to the selected device.

### `close_ide_window`

- `project_path: string`
- `window_id: string`

### `compare_screenshot`

- `actual_path: string` *(required)* — Path to the captured screenshot.
- `golden_path: string` *(required)* — Path to the golden image.
- `tolerance: number` — Similarity threshold 0..1 (default 0.98).
- `diff_output_path: string` — Optional path to write the diff overlay.

### `compress_png`

- `path: string` *(required)* — Path to a .png file on disk.
- `max_dim: integer` — Also resize if the long edge exceeds this. Omit to skip resize and only recompress.

### `dart_analyze`

- `project_path: string` *(required)*
- `min_severity: string`

### `dart_fix`

- `project_path: string` *(required)*
- `apply: boolean` — Default false (dry-run).

### `dart_format`

- `target_path: string` *(required)*
- `dry_run: boolean` — Default false.

### `describe_capabilities`

- `level: string`

### `describe_tool`

- `name: string` *(required)* — Tool name (e.g. 'select_device').

### `detect_markers`

- `image_path: string` *(required)* — Path to a PNG or JPG image.
- `dictionary: string`

### `dump_render_tree`

- `session_id: string`

### `dump_ui`

- `serial: string` — Device serial. Defaults to the selected device.

### `dump_widget_tree`

- `session_id: string`

### `extract_ui_graph`

- `max_nodes: integer` — Cap on returned nodes (default 200).
- `serial: string` — Device serial. Defaults to the selected device.

### `fetch_artifact`

- `path: string` *(required)* — Absolute path returned by an earlier tool.
- `max_bytes: integer` — Cap on text content (default 64000).
- `encoding: string` — Text encoding (default utf-8).

### `find_element`

- `text: string`
- `resource_id: string`
- `class_name: string`
- `timeout_s: number`
- `serial: string` — Device serial. Defaults to the selected device.

### `find_flutter_widget`

- `project_path: string` *(required)*
- `name_pattern: string` *(required)* — Regex on class name.
- `max_results: integer`

### `flutter_pub_get`

- `project_path: string` *(required)*

### `flutter_pub_outdated`

- `project_path: string` *(required)*

### `focus_ide_window`

- `project_path: string` *(required)*

### `force_release_lock`

- `serial: string` *(required)* — Device serial whose lock should be released.

### `grant_permission`

- `package_id: string` *(required)* — Android application id, e.g. com.example.app
- `permission: string` *(required)*
- `serial: string` — Device serial. Defaults to the selected device.

### `grep_logs`

- `path: string` *(required)* — Path to log artifact.
- `pattern: string` *(required)* — Regex.
- `context_lines: integer`
- `max_matches: integer`

### `index_project`

- `project_path: string` *(required)* — Project root.
- `collection: string` — Qdrant collection name.
- `include_globs: array` — Glob patterns to include.
- `exclude_globs: array` — Glob patterns to exclude.

### `infer_camera_pose`

- `image_path: string` *(required)*
- `marker_id: integer` *(required)* — ArUco marker ID.
- `marker_size_m: number` *(required)* — Marker side length in meters.

### `inspect_project`

- `project_path: string` *(required)* — Absolute or ~-relative path.

### `install_app`

- `bundle_path: string`
- `apk_path: string` — (deprecated) alias for bundle_path
- `project_path: string`
- `mode: string`
- `platform: string`
- `flavor: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `is_ide_available`

- `ide: string`

### `launch_app`

- `package_id: string` *(required)* — Android application id, e.g. com.example.app
- `activity: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `list_missing_widget_keys`

- `project_path: string` *(required)*
- `target_widgets: array` — Override the default tap-target widget set. Useful for codebases using custom button types.
- `max_results: integer` — Default 200.

### `list_patrol_tests`

- `project_path: string` *(required)*

### `list_simulators`

- `include_shutdown: boolean` — Default true; set false for booted-only listing.

### `narrate`

- `envelope: object` *(required)* — MCP envelope.
- `tool: string` — Optional tool name for richer phrasing.

### `new_session`

- `label: string`

### `notify_webhook`

- `url: string` *(required)* — Webhook URL (https, or http on localhost).
- `event: string` *(required)* — Snake_case event identifier.
- `payload: object` — JSON payload sent under `payload`.
- `auth_bearer: string` — Optional Bearer token.
- `auth_header_name: string` — Optional custom auth header.
- `auth_header_value: string`
- `timeout_s: number` — HTTP timeout (default 10).

### `ocr_screenshot`

- `path: string` *(required)* — Path to a PNG.
- `languages: array` — Languages, e.g. ['eng','pol']. Default ['eng'].
- `min_confidence: number` — 0..1; easyocr only.

### `open_project_in_ide`

- `project_path: string` *(required)*
- `ide: string`
- `new_window: boolean` — Default true.

### `patch_apply_safe`

- `project_path: string` *(required)* — Git project root.
- `diff: string` *(required)* — Unified diff content.
- `skip_gate: boolean` — Skip quality_gate (default false).
- `force: boolean` — Apply even if working tree is dirty.

### `prepare_for_test`

- `package_id: string` *(required)* — Application id to clean.
- `skip_clear: boolean` — Skip clear_app_data (iOS-style flow).
- `capture_evidence: boolean` — Default true; takes a PRE_FLIGHT screenshot.
- `serial: string` — Defaults to selected device.

### `press_key`

- `keycode: string` *(required)*
- `serial: string` — Device serial. Defaults to the selected device.

### `promote_sequence`

- `name: string` *(required)* — Skill identifier (snake_case).
- `description: string` *(required)* — Human-readable summary.
- `from_sequence: integer` — Earliest trace seq to include.
- `to_sequence: integer` — Latest trace seq to include.
- `only_ok: boolean` — Only include ok=True steps (default true).

### `prune_originals`

- `older_than_days: integer` — Retention window in days. Defaults to env or 14.
- `dry_run: boolean` — Report candidates without deleting (default false).

### `quality_gate`

- `project_path: string` *(required)*
- `require_format_clean: boolean` — Default true.
- `run_unit_tests: boolean` — Default true.

### `read_debug_log`

- `session_id: string`
- `since_s: integer`
- `level: string`
- `max_lines: integer`

### `read_logs`

- `since_s: integer`
- `tag: string`
- `min_level: string`
- `max_lines: integer`
- `serial: string` — Device serial. Defaults to the selected device.

### `recall`

- `query: string` *(required)* — Natural-language query.
- `k: integer` — Top-k chunks (default 3, max 20).
- `scope: string` — Filter chunks by scope (default 'all').

### `recall_corrective`

- `query: string` *(required)* — Natural-language query.
- `k: integer` — Top-k chunks (default 3).
- `scope: string` — Initial scope (default 'all').
- `confidence_threshold: number` — Mean lexical-overlap floor (default 0.15).
- `max_retries: integer` — Scope-fallback retries (default 1, max 4).

### `release_device`

- `serial: string` — Defaults to the currently selected device.

### `replay_skill`

- `name: string` *(required)* — Skill name.
- `overrides: object` — Placeholder substitutions for $-prefixed args.

### `restart_debug_session`

- `session_id: string`
- `full_restart: boolean` — Default false (hot reload).

### `run_integration_tests`

- `project_path: string` *(required)*
- `test_path: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `run_patrol_suite`

- `project_path: string` *(required)* — Flutter project root.
- `test_dir: string` — Defaults to integration_test/
- `flavor: string`
- `build_mode: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `run_patrol_test`

- `project_path: string` *(required)* — Flutter project root.
- `test_path: string` *(required)* — Path to a *_test.dart file.
- `flavor: string`
- `build_mode: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `run_quick_check`

- `project_path: string` *(required)* — Flutter project root.

### `run_test_plan`

- `plan_path: string` — Path to a v1 YAML plan.
- `plan_yaml: string` — Inline YAML plan.

### `run_unit_tests`

- `project_path: string` *(required)*

### `save_golden_image`

- `label: string` *(required)*
- `project_path: string` — Optional; defaults to artifacts dir.
- `serial: string` — Defaults to selected device.

### `scaffold_feature`

- `project_path: string` *(required)* — Flutter project root.
- `feature_name: string` *(required)* — snake_case feature id.
- `overwrite: boolean`

### `select_device`

- `serial: string` *(required)* — Device serial.
- `force: boolean` — Override an existing lock held by another session.
- `note: string` — Optional human-readable note recorded with the lock.

### `session_summary`

- `session_id: string` — Defaults to current.

### `set_agent_profile`

- `name: string` *(required)* — Profile name. Default for Claude is 'claude'.

### `setup_webdriveragent`

- `udid: string` *(required)*
- `wda_dir: string` — Existing WDA checkout (skip clone).
- `repo_url: string`
- `scheme: string` — Default WebDriverAgentRunner.
- `skip_if_built: boolean` — Default true; set false to force rebuild.

### `start_debug_session`

- `project_path: string` *(required)* — Flutter project root.
- `mode: string`
- `flavor: string`
- `target: string` — Optional entry-point dart file.
- `serial: string` — Defaults to selected device.

### `start_emulator`

- `avd_name: string` *(required)* — Name of the AVD.
- `headless: boolean` — Run with -no-window. Default false.

### `start_recording`

- `label: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `start_wda_on_simulator`

- `udid: string` *(required)* — Simulator UDID (from list_simulators).
- `port: integer` — WDA listen port. Default 8100. Override with MCP_IOS_SIM_WDA_PORT for global default.
- `wda_dir: string` — WebDriverAgent checkout dir. Defaults to ~/.mcp_phone_controll/WebDriverAgent.
- `scheme: string` — Default WebDriverAgentRunner.
- `ready_timeout_s: number` — How long to wait for WDA to come up. Default 60.

### `stop_app`

- `package_id: string` *(required)* — Android application id, e.g. com.example.app
- `serial: string` — Device serial. Defaults to the selected device.

### `stop_debug_session`

- `session_id: string`

### `stop_recording`

- `serial: string` — Device serial. Defaults to the selected device.

### `stop_virtual_device`

- `serial: string` *(required)* — Emulator serial or simulator UDID.

### `summarize_session`

- `session_id: string` — Defaults to current.
- `top_facts: integer`

### `swipe`

- `x1: integer` *(required)*
- `y1: integer` *(required)*
- `x2: integer` *(required)*
- `y2: integer` *(required)*
- `duration_ms: integer`
- `serial: string` — Device serial. Defaults to the selected device.

### `tail_debug_log`

- `until_pattern: string` *(required)*
- `session_id: string`
- `timeout_s: number`

### `tail_logs`

- `until_pattern: string` *(required)*
- `tag: string`
- `timeout_s: number`
- `serial: string` — Device serial. Defaults to the selected device.

### `take_screenshot`

- `label: string` — Required by convention: <PHASE>-<outcome>. Examples: 'PRE_FLIGHT-home', 'UMP_GATE-declined', 'UNDER_TEST-ac1-pass', 'VERDICT_BLOCKED'.
- `serial: string` — Device serial. Defaults to the selected device.

### `tap`

- `x: integer` *(required)*
- `y: integer` *(required)*
- `serial: string` — Device serial. Defaults to the selected device.

### `tap_and_verify`

- `text: string` *(required)* — Text to tap.
- `expect_text: string` — Text that must appear after tap.
- `expect_resource_id: string` — Resource id alternative.
- `timeout_s: number` — Verification timeout (default 5).
- `exact: boolean`
- `serial: string` — Device serial. Defaults to the selected device.

### `tap_text`

- `text: string` *(required)*
- `exact: boolean`
- `serial: string` — Device serial. Defaults to the selected device.

### `toggle_inspector`

- `enabled: boolean` *(required)*
- `session_id: string`

### `tool_usage_report`

- `session_id: string` — Defaults to current.
- `top_n: integer` — Top-N rows to include (default 10).

### `type_text`

- `text: string` *(required)*
- `serial: string` — Device serial. Defaults to the selected device.

### `uninstall_app`

- `package_id: string` *(required)* — Android application id, e.g. com.example.app
- `serial: string` — Device serial. Defaults to the selected device.

### `validate_test_plan`

- `plan_path: string` — Path to a v1 YAML plan.
- `plan_yaml: string` — Inline YAML plan.

### `vm_evaluate`

- `expression: string` *(required)* — Dart expression.
- `isolate_id: string` — Optional; defaults to first runnable.
- `frame_index: integer` — Default 0.
- `session_id: string`

### `vm_list_isolates`

- `session_id: string`

### `wait_for_ar_session_ready`

- `timeout_s: number` — Default 30.
- `serial: string` — Defaults to selected device.

### `wait_for_element`

- `text: string`
- `resource_id: string`
- `timeout_s: number`
- `serial: string` — Device serial. Defaults to the selected device.

### `wait_for_marker`

- `marker_id: integer` *(required)*
- `timeout_s: number` — Default 30s.
- `poll_interval_s: number` — Default 1s.
- `dictionary: string`
- `serial: string` — Device serial. Defaults to the selected device.

### `write_vscode_launch_config`

- `project_path: string` *(required)* — Flutter project root.
- `flavor: string` — Optional Flutter flavor.
- `target: string` — Entry-point Dart file (default lib/main.dart).
- `debug_mode: string` — Default mode reflected in the active configuration.
- `overwrite: boolean` — Replace an existing file if true.

