mobile-debug-mcp 0.35.0 → 0.37.0

package/test/fixtures/contracts/tool-definitions.json

@@ -1,10 +1,35 @@
 [
   {
     "name": "get_debugger_capabilities",
-    "description": "Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.",
+    "description": "Probe optional platform debugger prerequisites and matching running debuggable processes; does not attach.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "platform": {
+                "const": "ios"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "deviceId": {
+                "pattern": "^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$"
+              }
+            }
+          }
+        },
+        {
+          "not": {
+            "required": [
+              "expectedState"
+            ]
+          }
+        }
+      ],
       "required": [
         "platform",
         "deviceId",
@@ -22,7 +47,8 @@
         "platform": {
           "type": "string",
           "enum": [
-            "android"
+            "android",
+            "ios"
           ]
         },
         "deviceId": {
@@ -34,7 +60,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "pattern": "^[A-Za-z][\\w]*(?:\\.[A-Za-z][\\w]*)+$"
+          "pattern": "^[A-Za-z][\\w-]*(?:\\.[A-Za-z][\\w-]*)+$"
         },
         "processId": {
           "type": "integer",
@@ -47,8 +73,32 @@
           "maximum": 30000,
           "default": 10000
         }
-      },
+      }
+    }
+  },
+  {
+    "name": "attach_debugger",
+    "description": "Attach an owned Android JDI or iOS simulator LLDB session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
       "allOf": [
+        {
+          "if": {
+            "properties": {
+              "platform": {
+                "const": "ios"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "deviceId": {
+                "pattern": "^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$"
+              }
+            }
+          }
+        },
         {
           "not": {
             "required": [
@@ -56,15 +106,7 @@
             ]
           }
         }
-      ]
-    }
-  },
-  {
-    "name": "attach_debugger",
-    "description": "Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.",
-    "inputSchema": {
-      "type": "object",
-      "additionalProperties": false,
+      ],
       "required": [
         "platform",
         "deviceId",
@@ -82,7 +124,8 @@
         "platform": {
           "type": "string",
           "enum": [
-            "android"
+            "android",
+            "ios"
           ]
         },
         "deviceId": {
@@ -94,7 +137,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "pattern": "^[A-Za-z][\\w]*(?:\\.[A-Za-z][\\w]*)+$"
+          "pattern": "^[A-Za-z][\\w-]*(?:\\.[A-Za-z][\\w-]*)+$"
         },
         "processId": {
           "type": "integer",
@@ -107,16 +150,7 @@
           "maximum": 30000,
           "default": 10000
         }
-      },
-      "allOf": [
-        {
-          "not": {
-            "required": [
-              "expectedState"
-            ]
-          }
-        }
-      ]
+      }
     }
   },
   {
@@ -162,13 +196,34 @@
   },
   {
     "name": "set_debugger_breakpoint",
-    "description": "Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.",
+    "description": "Set an exact source breakpoint: Android className or iOS absolute sourceFile (exactly one), plus line; unloaded classes/images remain pending. No silent line relocation.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
+      "oneOf": [
+        {
+          "required": [
+            "className"
+          ],
+          "not": {
+            "required": [
+              "sourceFile"
+            ]
+          }
+        },
+        {
+          "required": [
+            "sourceFile"
+          ],
+          "not": {
+            "required": [
+              "className"
+            ]
+          }
+        }
+      ],
       "required": [
         "debugSessionId",
-        "className",
         "line"
       ],
       "properties": {
@@ -191,6 +246,12 @@
           "maxLength": 512,
           "pattern": "^[A-Za-z_$][\\w$]*(?:\\.[A-Za-z_$][\\w$]*)*$"
         },
+        "sourceFile": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^\\/[^\\0\\r\\n]+$"
+        },
         "line": {
           "type": "integer",
           "minimum": 0,
@@ -372,7 +433,7 @@
   },
   {
     "name": "get_debugger_locals",
-    "description": "Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.",
+    "description": "Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters; iOS aggregates return type summaries. No evaluation or field traversal.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -534,7 +595,7 @@
   },
   {
     "name": "detach_debugger",
-    "description": "Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.",
+    "description": "Dispose the owned debugger connection, release owned suspension and remove its owned transport. Idempotent; retries incomplete cleanup.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -575,7 +636,7 @@
   },
   {
     "name": "get_system_trace_capabilities",
-    "description": "Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.",
+    "description": "Probe Android Perfetto or iOS Instruments prerequisites without recording. iOS requires explicit booted simulator deviceId; reports template matrix and unknown profiling permissions.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -593,8 +654,57 @@
         "deviceId": {
           "type": "string",
           "minLength": 1
+        },
+        "appId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9._-]+$",
+          "description": "iOS only: running development app bundle identifier; required for iOS start."
+        },
+        "template": {
+          "type": "string",
+          "enum": [
+            "System Trace",
+            "Time Profiler",
+            "Animation Hitches",
+            "Hangs"
+          ],
+          "description": "iOS only. Default Time Profiler; initial simulator support is Time Profiler only."
         }
       },
+      "oneOf": [
+        {
+          "properties": {
+            "platform": {
+              "const": "android"
+            }
+          },
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "appId"
+                ]
+              },
+              {
+                "required": [
+                  "template"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "properties": {
+            "platform": {
+              "const": "ios"
+            }
+          },
+          "required": [
+            "deviceId"
+          ]
+        }
+      ],
       "allOf": [
         {
           "not": {
@@ -608,7 +718,7 @@
   },
   {
     "name": "start_system_trace",
-    "description": "Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.",
+    "description": "Start bounded Android Perfetto or iOS simulator Time Profiler recording, returning an owned trace_id after readiness. iOS requires explicit deviceId and running appId. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Traces can contain sensitive system metadata, logs and paths; local user-managed retention, no upload.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -627,6 +737,22 @@
           "type": "string",
           "minLength": 1
         },
+        "appId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9._-]+$",
+          "description": "iOS only: running development app bundle identifier; required for iOS start."
+        },
+        "template": {
+          "type": "string",
+          "enum": [
+            "System Trace",
+            "Time Profiler",
+            "Animation Hitches",
+            "Hangs"
+          ],
+          "description": "iOS only. Default Time Profiler; initial simulator support is Time Profiler only."
+        },
         "durationMs": {
           "type": "integer",
           "minimum": 1000,
@@ -634,6 +760,40 @@
           "default": 30000
         }
       },
+      "oneOf": [
+        {
+          "properties": {
+            "platform": {
+              "const": "android"
+            }
+          },
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "appId"
+                ]
+              },
+              {
+                "required": [
+                  "template"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "properties": {
+            "platform": {
+              "const": "ios"
+            }
+          },
+          "required": [
+            "deviceId",
+            "appId"
+          ]
+        }
+      ],
       "allOf": [
         {
           "not": {
@@ -673,7 +833,7 @@
   },
   {
     "name": "stop_system_trace",
-    "description": "Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.",
+    "description": "Stop owned capture gracefully and retrieve a local Perfetto file or validated Instruments .trace bundle. Retry after a transfer/cleanup failure.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -723,9 +883,40 @@
       ]
     }
   },
+  {
+    "name": "get_interaction_diagnostics",
+    "description": "Read the retained original interaction or journey result without replaying input or observing the device. Pass diagnostics.session_id/result_id as sessionId/resultId. Session-local memory: ten minutes, 100 results, 16 MiB total, 1 MiB per result. Expired, evicted or restarted results are unavailable. May contain private UI text and errors; compact output is not redaction.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sessionId",
+        "resultId"
+      ],
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "resultId": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "allOf": [
+        {
+          "not": {
+            "required": [
+              "expectedState"
+            ]
+          }
+        }
+      ]
+    }
+  },
   {
     "name": "get_app_readiness",
-    "description": "Observe readiness with at most two fresh UI-tree samples. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.",
+    "description": "Observe readiness with at most two fresh UI-tree samples. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android and supported iOS simulator debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -770,7 +961,7 @@
   },
   {
     "name": "wait_for_app_ready",
-    "description": "Wait within a single bounded budget for settled UI evidence. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.",
+    "description": "Wait within a single bounded budget for settled UI evidence. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android and supported iOS simulator debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -821,7 +1012,7 @@
   },
   {
     "name": "start_app",
-    "description": "Purpose:\nLaunch a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when launch was dispatched successfully\n- failure_code/retryable when launch dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call start_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the landing screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying",
+    "description": "Purpose:\nLaunch a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when launch was dispatched successfully\n- failure_code/retryable when launch dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call start_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the landing screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -920,7 +1111,7 @@
   },
   {
     "name": "restart_app",
-    "description": "Purpose:\nRestart a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when the restart command completed\n- failure_code/retryable when restart dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call restart_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the reopened screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying",
+    "description": "Purpose:\nRestart a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when the restart command completed\n- failure_code/retryable when restart dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call restart_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the reopened screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1201,7 +1392,7 @@
   },
   {
     "name": "list_devices",
-    "description": "List connected devices and their metadata (android + ios).",
+    "description": "List Android devices and iOS simulators. Supply appId for device-specific installation status; unknown checks do not imply absence.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1211,6 +1402,11 @@
             "android",
             "ios"
           ]
+        },
+        "appId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*$",
+          "description": "Optional package or bundle identifier to check on each device."
         }
       },
       "allOf": [
@@ -1669,7 +1865,7 @@
   },
   {
     "name": "wait_for_ui_change",
-    "description": "Purpose:\nWait for a non-navigation UI mutation or in-place update to become stable.\n\nInputs:\n- expected_change (optional): hierarchy_diff, text_change, or state_change\n- timeout_ms (optional)\n- stability_window_ms (optional)\n- scope (optional): screen or subtree\n- target (optional): element_id when scope=subtree\n\nGuidance:\n- Prefer wait_for_screen_change for navigation transitions.\n- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.\n- Use the returned snapshot_revision as the observed synchronization point when available.\n- Scoped waits return scope-aware stability metadata and a lightweight change summary.\n\nFailure Handling:\n- TIMEOUT means the UI did not change in a stable way within the allotted time.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
+    "description": "Purpose:\nWait for a non-navigation UI mutation or in-place update to become stable.\n\nInputs:\n- expected_change (optional): hierarchy_diff, text_change, or state_change\n- timeout_ms (optional)\n- stability_window_ms (optional)\n- scope (optional): screen or subtree\n- target (optional): element_id when scope=subtree\n\nGuidance:\n- Prefer wait_for_screen_change for navigation transitions.\n- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.\n- Use the returned snapshot_revision as the observed synchronization point when available.\n- Scoped waits return scope-aware stability metadata and a lightweight change summary.\n\nFailure Handling:\n- TIMEOUT means the UI did not change in a stable way within the allotted time.\nDevice-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1913,7 +2109,7 @@
   },
   {
     "name": "adjust_control",
-    "description": "Purpose:\nAdjust a numeric control value with verification.\n\nThis is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.\n\nInputs:\n- exactly one of selector or element_id\n- property (defaults to \"value\")\n- targetValue\n- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)\n- maxAttempts (optional; defaults to 5)\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target_state / actual_state / within_tolerance / converged / attempts / adjustment_mode\n- target.selector = original selector or element handle\n- success = true when the control converges within tolerance\n\nVerification Guidance:\n- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode\n- Use expect_state for the control value readback\n- Do not use derived semantic metadata as proof of success\n\nFailure Handling:\n- ELEMENT_NOT_FOUND → re-resolve the control\n- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime\n- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range\n- UNKNOWN → capture a snapshot and stop",
+    "description": "Purpose:\nAdjust a numeric control value with verification.\n\nThis is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.\n\nInputs:\n- exactly one of selector or element_id\n- property (defaults to \"value\")\n- targetValue\n- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)\n- maxAttempts (optional; defaults to 5)\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target_state / actual_state / within_tolerance / converged / attempts / adjustment_mode\n- target.selector = original selector or element handle\n- success = true when the control converges within tolerance\n\nVerification Guidance:\n- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode\n- Use expect_state for the control value readback\n- Do not use derived semantic metadata as proof of success\n\nFailure Handling:\n- ELEMENT_NOT_FOUND → re-resolve the control\n- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime\n- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range\n- UNKNOWN → capture a snapshot and stop\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1998,7 +2194,7 @@
   },
   {
     "name": "wait_for_ui",
-    "description": "Purpose:\nResolve elements and/or detect that a UI transition or availability condition has occurred.\n\nCapabilities:\n- Deterministic element resolution\n- Synchronization when element timing or availability is uncertain\n\nConstraints:\n- Does not verify correctness of the resulting state\n- Must not be used alone to confirm action success when an applicable expect_* tool exists\n\nRecommended Usage:\n1. Use wait_for_ui to resolve an element before acting or to wait for UI readiness\n2. Call the action tool\n3. If the expected outcome is known, follow with expect_* as final verification\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
+    "description": "Purpose:\nResolve elements and/or detect that a UI transition or availability condition has occurred.\n\nCapabilities:\n- Deterministic element resolution\n- Synchronization when element timing or availability is uncertain\n\nConstraints:\n- Does not verify correctness of the resulting state\n- Must not be used alone to confirm action success when an applicable expect_* tool exists\n\nRecommended Usage:\n1. Use wait_for_ui to resolve an element before acting or to wait for UI readiness\n2. Call the action tool\n3. If the expected outcome is known, follow with expect_* as final verification\nDevice-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2137,7 +2333,7 @@
   },
   {
     "name": "tap",
-    "description": "Purpose:\nDispatch a tap at specific screen coordinates.\n\nInputs:\n- x, y coordinates\n- platform (optional)\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { x, y }\n- success = true when the tap was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve coordinates deterministically\n2. Call tap\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible depending on the intended outcome\n\nVerification Guidance:\n- Prefer tap_element over tap when an element can be resolved\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_screen for navigation and expect_element_visible for local UI changes\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nDispatch a tap at specific screen coordinates.\n\nInputs:\n- x, y coordinates\n- platform (optional)\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { x, y }\n- success = true when the tap was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve coordinates deterministically\n2. Call tap\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible depending on the intended outcome\n\nVerification Guidance:\n- Prefer tap_element over tap when an element can be resolved\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_screen for navigation and expect_element_visible for local UI changes\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2254,7 +2450,7 @@
   },
   {
     "name": "tap_element",
-    "description": "Purpose:\nTap a previously resolved UI element using its elementId.\n\nInputs:\n- elementId: a resolved UI element identifier returned by wait_for_ui\n\nOutput Structure:\n- action_id: unique timestamp-based action identifier\n- timestamp: ISO 8601 timestamp for the action attempt\n- action_type: \"tap_element\"\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector: original target handle ({ elementId })\n- target.resolved: minimal resolved element info used for the tap\n- success: true when the tap was dispatched\n- failure_code: present when success=false\n- retryable: present when failure_code exists\n- ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action\n\nRecommended Usage:\n1. Resolve the target with wait_for_ui or another deterministic resolver\n2. Call tap_element\n3. If needed, wait for transition using wait_for_*\n4. Verify outcome using expect_*\n   - use expect_screen when navigation is expected\n   - use expect_element_visible when the UI change is local\n5. If verification fails, inspect failure_code and follow the retry strategy below\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Prefer expect_screen for navigation or modal transitions\n- Prefer expect_element_visible when the tap should reveal or update a specific element\n- wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists\n- Do not treat tap_element.success as outcome success; it only means the tap was executed\n\nFailure Handling:\n- STALE_REFERENCE → re-resolve the element, then retry\n- ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry\n- UNKNOWN → capture a snapshot and stop\n\nThis tool reports execution success only. Verification must be done with a separate expect_* tool.\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nTap a previously resolved UI element using its elementId.\n\nInputs:\n- elementId: a resolved UI element identifier returned by wait_for_ui\n\nOutput Structure:\n- action_id: unique timestamp-based action identifier\n- timestamp: ISO 8601 timestamp for the action attempt\n- action_type: \"tap_element\"\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector: original target handle ({ elementId })\n- target.resolved: minimal resolved element info used for the tap\n- success: true when the tap was dispatched\n- failure_code: present when success=false\n- retryable: present when failure_code exists\n- ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action\n\nRecommended Usage:\n1. Resolve the target with wait_for_ui or another deterministic resolver\n2. Call tap_element\n3. If needed, wait for transition using wait_for_*\n4. Verify outcome using expect_*\n   - use expect_screen when navigation is expected\n   - use expect_element_visible when the UI change is local\n5. If verification fails, inspect failure_code and follow the retry strategy below\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Prefer expect_screen for navigation or modal transitions\n- Prefer expect_element_visible when the tap should reveal or update a specific element\n- wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists\n- Do not treat tap_element.success as outcome success; it only means the tap was executed\n\nFailure Handling:\n- STALE_REFERENCE → re-resolve the element, then retry\n- ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry\n- UNKNOWN → capture a snapshot and stop\n\nThis tool reports execution success only. Verification must be done with a separate expect_* tool.\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2431,7 +2627,7 @@
   },
   {
     "name": "swipe",
-    "description": "Purpose:\nDispatch a swipe gesture on Android or iOS.\n\nInputs:\n- start and end coordinates\n- duration\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { x1, y1, x2, y2, duration }\n- success = true when the swipe was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Determine swipe coordinates\n2. Call swipe\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible when a deterministic outcome is expected\n\nVerification Guidance:\n- Swipe outcomes are less predictable; choose the most specific verifier available for the intended effect\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nDispatch a swipe gesture on Android or iOS.\n\nInputs:\n- start and end coordinates\n- duration\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { x1, y1, x2, y2, duration }\n- success = true when the swipe was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Determine swipe coordinates\n2. Call swipe\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible when a deterministic outcome is expected\n\nVerification Guidance:\n- Swipe outcomes are less predictable; choose the most specific verifier available for the intended effect\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2563,7 +2759,7 @@
   },
   {
     "name": "scroll_to_element",
-    "description": "Purpose:\nScroll until a target element becomes visible.\n\nInputs:\n- platform\n- selector\n- direction, maxScrolls, scrollAmount, deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = original selector\n- target.resolved = minimal resolved element info when found\n- success = true when scrolling produced a visible target element\n- failure_code/retryable when the target was not reached\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve the target selector\n2. Call scroll_to_element\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible when the expected element visibility is known\n5. If success=false, follow failure handling before retrying\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_element_visible when you need an explicit post-scroll confirmation\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- NAVIGATION_NO_CHANGE → adjust scroll direction or stop\n- TIMEOUT → retry with refined selector or larger scroll budget\n- UNKNOWN → capture a snapshot and stop",
+    "description": "Purpose:\nScroll until a target element becomes visible.\n\nInputs:\n- platform\n- selector\n- direction, maxScrolls, scrollAmount, deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = original selector\n- target.resolved = minimal resolved element info when found\n- success = true when scrolling produced a visible target element\n- failure_code/retryable when the target was not reached\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve the target selector\n2. Call scroll_to_element\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible when the expected element visibility is known\n5. If success=false, follow failure handling before retrying\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_element_visible when you need an explicit post-scroll confirmation\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- NAVIGATION_NO_CHANGE → adjust scroll direction or stop\n- TIMEOUT → retry with refined selector or larger scroll budget\n- UNKNOWN → capture a snapshot and stop\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2655,7 +2851,7 @@
   },
   {
     "name": "type_text",
-    "description": "Purpose:\nType text into the currently focused Android input field.\n\nInputs:\n- text\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { text }\n- success = true when text input was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve or focus the target input first\n2. Call type_text\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible or expect_screen, depending on the intended outcome\n\nVerification Guidance:\n- Prefer verifying the next expected element or screen state instead of inferring success from the text action alone\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → re-focus the input or capture a snapshot\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nType text into the currently focused Android input field.\n\nInputs:\n- text\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { text }\n- success = true when text input was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve or focus the target input first\n2. Call type_text\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible or expect_screen, depending on the intended outcome\n\nVerification Guidance:\n- Prefer verifying the next expected element or screen state instead of inferring success from the text action alone\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → re-focus the input or capture a snapshot\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2765,7 +2961,7 @@
   },
   {
     "name": "press_back",
-    "description": "Purpose:\nDispatch the Android Back action.\n\nInputs:\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { key: \"back\" }\n- success = true when the back action was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Call press_back\n2. If needed, wait for transition using wait_for_*\n3. Verify with expect_screen when a known destination is expected\n4. If verification fails, retry once or recover explicitly\n\nVerification Guidance:\n- Back outcomes can vary by screen, so verify against the intended destination when possible\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nDispatch the Android Back action.\n\nInputs:\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { key: \"back\" }\n- success = true when the back action was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Call press_back\n2. If needed, wait for transition using wait_for_*\n3. Verify with expect_screen when a known destination is expected\n4. If verification fails, retry once or recover explicitly\n\nVerification Guidance:\n- Back outcomes can vary by screen, so verify against the intended destination when possible\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact 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.\nResults 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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2931,7 +3127,7 @@
   },
   {
     "name": "run_journey",
-    "description": "Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.",
+    "description": "Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence through a diagnostics reference in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.",
     "inputSchema": {
       "type": "object",
       "properties": {