mobile-debug-mcp 0.24.1 → 0.24.2

package/dist/interact/index.js

@@ -437,6 +437,12 @@ export class ToolsInteract {
     }
     static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }) {
         const overallStart = Date.now();
+        const requestedIndex = typeof match?.index === 'number' ? match.index : null;
+        const requested = {
+            selector: selector ?? {},
+            condition,
+            match: requestedIndex === null ? null : { index: requestedIndex }
+        };
         // Validate selector: require at least one non-empty field (text, resource_id, or accessibility_id)
         const hasText = typeof selector?.text === 'string' && selector.text.trim().length > 0;
         const hasResId = typeof selector?.resource_id === 'string' && selector.resource_id.trim().length > 0;
@@ -448,22 +454,27 @@ export class ToolsInteract {
                     code: 'INVALID_SELECTOR',
                     message: 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id'
                 },
-                metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }
+                metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 },
+                requested,
+                observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null }
             };
         }
         // Validate condition
         if (!['exists', 'not_exists', 'visible', 'clickable'].includes(condition)) {
-            return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } };
+            return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }, requested, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } };
         }
         // Platform check
         if (platform && !['android', 'ios'].includes(platform)) {
-            return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } };
+            return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }, requested, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } };
         }
         const effectivePoll = Math.max(50, Math.min(poll_interval_ms || 300, 2000));
         const maxAttempts = (retry && retry.max_attempts) ? Math.max(1, retry.max_attempts) : 1;
         const backoff = (retry && retry.backoff_ms) ? Math.max(0, retry.backoff_ms) : 0;
         let attempts = 0;
         let totalPollCount = 0;
+        let lastMatchedCount = 0;
+        let lastMatchedElement = null;
+        let lastConditionSatisfied = false;
         // Precompute normalized selector values and helpers (constant across polls)
         const normalize = ToolsInteract._normalize;
         const containsFlag = !!selector?.contains;
@@ -573,18 +584,27 @@ export class ToolsInteract {
                             else
                                 conditionMet = false;
                         }
+                        const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
+                        const resolvedDeviceId = tree?.device?.id || deviceId;
+                        lastMatchedCount = matchedCount;
+                        lastConditionSatisfied = conditionMet;
+                        lastMatchedElement = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null;
                         if (conditionMet) {
                             const now = Date.now();
                             const latency_ms = now - overallStart;
-                            // Build element output per spec
-                            const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
-                            const resolvedDeviceId = tree?.device?.id || deviceId;
-                            const outEl = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null;
+                            const outEl = lastMatchedElement;
                             return {
                                 status: 'success',
                                 matched: matchedCount,
                                 element: outEl,
-                                metrics: { latency_ms, poll_count: totalPollCount, attempts }
+                                metrics: { latency_ms, poll_count: totalPollCount, attempts },
+                                requested,
+                                observed: {
+                                    matched_count: matchedCount,
+                                    condition_satisfied: true,
+                                    selected_index: outEl?.index ?? null,
+                                    last_matched_element: outEl
+                                }
                             };
                         }
                     }
@@ -603,16 +623,38 @@ export class ToolsInteract {
                 }
                 // Final failure for this call
                 const elapsed = Date.now() - overallStart;
+                const observed = {
+                    matched_count: lastMatchedCount,
+                    condition_satisfied: lastConditionSatisfied,
+                    selected_index: lastMatchedElement?.index ?? null,
+                    last_matched_element: lastMatchedElement
+                };
+                const matchNote = requestedIndex !== null && lastMatchedCount <= requestedIndex
+                    ? ` requested match.index=${requestedIndex} but observed ${lastMatchedCount} match(es)`
+                    : ` observed ${lastMatchedCount} match(es)`;
                 return {
                     status: 'timeout',
-                    error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout` },
-                    metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts }
+                    error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
+                    metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
+                    requested,
+                    observed
                 };
             }
         }
         catch (err) {
             const elapsed = Date.now() - overallStart;
-            return { status: 'timeout', error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) }, metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts } };
+            return {
+                status: 'timeout',
+                error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) },
+                metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
+                requested,
+                observed: {
+                    matched_count: lastMatchedCount,
+                    condition_satisfied: false,
+                    selected_index: lastMatchedElement?.index ?? null,
+                    last_matched_element: lastMatchedElement
+                }
+            };
         }
     }
     // Helper: normalize various log objects into plain message strings for comparison
@@ -635,10 +677,12 @@ export class ToolsInteract {
     static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }) {
         const start = Date.now();
         let lastFingerprint = null;
+        let lastActivity = null;
         while (Date.now() - start < timeoutMs) {
             try {
                 const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
                 const fp = res?.fingerprint ?? null;
+                lastActivity = res?.activity ?? lastActivity;
                 if (fp === null || fp === undefined) {
                     lastFingerprint = null;
                     await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
@@ -651,8 +695,18 @@ export class ToolsInteract {
                     try {
                         const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
                         const confirmFp = confirmRes?.fingerprint ?? null;
+                        lastActivity = confirmRes?.activity ?? lastActivity;
                         if (confirmFp === fp) {
-                            return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start };
+                            return {
+                                success: true,
+                                previousFingerprint,
+                                newFingerprint: fp,
+                                elapsedMs: Date.now() - start,
+                                observed_screen: {
+                                    fingerprint: fp,
+                                    activity: lastActivity
+                                }
+                            };
                         }
                         lastFingerprint = confirmFp;
                         continue;
@@ -668,7 +722,17 @@ export class ToolsInteract {
             }
             await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
         }
-        return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
+        return {
+            success: false,
+            reason: 'timeout',
+            previousFingerprint,
+            lastFingerprint,
+            elapsedMs: Date.now() - start,
+            observed_screen: {
+                fingerprint: lastFingerprint,
+                activity: lastActivity
+            }
+        };
     }
     static async expectScreenHandler({ platform, fingerprint, screen, deviceId }) {
         const observedFingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
@@ -691,16 +755,26 @@ export class ToolsInteract {
             screen: screen ?? null
         };
         let success = false;
+        let basis = 'none';
+        let reason = 'No fingerprint or screen expectation provided';
         if (fingerprint) {
+            basis = 'fingerprint';
             success = observedScreen.fingerprint === fingerprint;
+            reason = success
+                ? `observed fingerprint matches expected fingerprint ${fingerprint}`
+                : `expected fingerprint ${fingerprint} but observed ${observedScreen.fingerprint ?? 'null'}`;
         }
         else if (screen) {
+            basis = 'screen';
             const candidates = new Set();
             if (observedScreen.screen)
                 candidates.add(observedScreen.screen);
             if (observedScreenLabel)
                 candidates.add(observedScreenLabel);
             success = candidates.has(screen);
+            reason = success
+                ? `observed screen matches expected screen ${screen}`
+                : `expected screen ${screen} but observed ${observedScreenLabel ?? observedScreen.screen ?? 'null'}`;
         }
         return {
             success,
@@ -709,7 +783,12 @@ export class ToolsInteract {
                 screen: observedScreenLabel
             },
             expected_screen: expectedScreen,
-            confidence: success ? 1 : 0
+            confidence: success ? 1 : 0,
+            comparison: {
+                basis,
+                matched: success,
+                reason
+            }
         };
     }
     static async expectElementVisibleHandler({ selector, element_id, timeout_ms = 5000, poll_interval_ms = 300, platform, deviceId }) {
@@ -726,6 +805,7 @@ export class ToolsInteract {
                 success: true,
                 selector,
                 element_id: result.element.elementId ?? element_id ?? null,
+                expected_condition: 'visible',
                 element: {
                     elementId: result.element.elementId ?? null,
                     text: result.element.text ?? null,
@@ -734,7 +814,23 @@ export class ToolsInteract {
                     class: result.element.class ?? null,
                     bounds: result.element.bounds ?? null,
                     index: typeof result.element.index === 'number' ? result.element.index : null
-                }
+                },
+                observed: {
+                    status: result.status,
+                    matched_count: typeof result.matched === 'number' ? result.matched : result?.observed?.matched_count ?? null,
+                    condition_satisfied: true,
+                    selected_index: typeof result.element.index === 'number' ? result.element.index : null,
+                    last_matched_element: {
+                        elementId: result.element.elementId ?? null,
+                        text: result.element.text ?? null,
+                        resource_id: result.element.resource_id ?? null,
+                        accessibility_id: result.element.accessibility_id ?? null,
+                        class: result.element.class ?? null,
+                        bounds: result.element.bounds ?? null,
+                        index: typeof result.element.index === 'number' ? result.element.index : null
+                    }
+                },
+                reason: 'selector is visible'
             };
         }
         const errorCode = result?.error?.code === 'INTERNAL_ERROR' ? 'UNKNOWN' : 'TIMEOUT';
@@ -742,6 +838,15 @@ export class ToolsInteract {
             success: false,
             selector,
             element_id: element_id ?? null,
+            expected_condition: 'visible',
+            observed: {
+                status: result?.status,
+                matched_count: result?.observed?.matched_count,
+                condition_satisfied: result?.observed?.condition_satisfied ?? false,
+                selected_index: result?.observed?.selected_index ?? null,
+                last_matched_element: result?.observed?.last_matched_element ?? null
+            },
+            reason: result?.error?.message ?? 'selector is not visible',
             failure_code: errorCode,
             retryable: errorCode === 'TIMEOUT'
         };

package/dist/manage/android.js

@@ -5,6 +5,7 @@ import { existsSync } from 'fs';
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js';
 import { execAdbWithDiagnostics } from '../utils/diagnostics.js';
 import { detectJavaHome } from '../utils/java.js';
+import { AndroidObserve } from '../observe/android.js';
 export class AndroidManage {
     isTestOnlyInstallFailure(output) {
         return typeof output === 'string' && output.includes('INSTALL_FAILED_TEST_ONLY');
@@ -144,8 +145,21 @@ export class AndroidManage {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
-            return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 };
+            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null);
+            return {
+                device: deviceInfo,
+                appStarted: true,
+                launchTimeMs: 1000,
+                output,
+                observedApp: {
+                    appId,
+                    package: current?.package ?? null,
+                    activity: current?.activity ?? null,
+                    screen: current?.shortActivity ?? current?.activity ?? null,
+                    matchedTarget: current ? current.package === appId : null
+                }
+            };
         }
         catch (e) {
             const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
@@ -165,12 +179,18 @@ export class AndroidManage {
         }
     }
     async restartApp(appId, deviceId) {
-        await this.terminateApp(appId, deviceId);
+        const terminateResult = await this.terminateApp(appId, deviceId);
         const startResult = await this.startApp(appId, deviceId);
         return {
             device: startResult.device,
             appRestarted: startResult.appStarted,
-            launchTimeMs: startResult.launchTimeMs
+            launchTimeMs: startResult.launchTimeMs,
+            output: startResult.output,
+            observedApp: startResult.observedApp,
+            terminatedBeforeRestart: terminateResult.appTerminated,
+            ...(terminateResult.error ? { terminateError: terminateResult.error } : {}),
+            ...(startResult.error ? { error: startResult.error } : {}),
+            ...(startResult.diagnostics ? { diagnostics: startResult.diagnostics } : {})
         };
     }
     async resetAppData(appId, deviceId) {

package/dist/manage/ios.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "fs";
 import { spawn, spawnSync } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js";
+import { iOSObserve } from "../observe/ios.js";
 import path from "path";
 export class iOSManage {
     async build(projectPath, optsOrVariant) {
@@ -294,7 +295,20 @@ export class iOSManage {
         try {
             const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            return { device, appStarted: !!result.output, launchTimeMs: 1000 };
+            const fingerprint = await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null);
+            const pidMatch = result.output.match(/:\s*(\d+)\s*$/);
+            return {
+                device,
+                appStarted: !!result.output,
+                launchTimeMs: 1000,
+                output: result.output,
+                observedApp: {
+                    appId: bundleId,
+                    pid: pidMatch ? Number(pidMatch[1]) : null,
+                    screen: fingerprint?.activity ?? null,
+                    matchedTarget: null
+                }
+            };
         }
         catch (e) {
             const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
@@ -316,9 +330,19 @@ export class iOSManage {
         }
     }
     async restartApp(bundleId, deviceId = "booted") {
-        await this.terminateApp(bundleId, deviceId);
+        const terminateResult = await this.terminateApp(bundleId, deviceId);
         const startResult = await this.startApp(bundleId, deviceId);
-        return { device: startResult.device, appRestarted: startResult.appStarted, launchTimeMs: startResult.launchTimeMs };
+        return {
+            device: startResult.device,
+            appRestarted: startResult.appStarted,
+            launchTimeMs: startResult.launchTimeMs,
+            output: startResult.output,
+            observedApp: startResult.observedApp,
+            terminatedBeforeRestart: terminateResult.appTerminated,
+            ...(terminateResult.error ? { terminateError: terminateResult.error } : {}),
+            ...(startResult.error ? { error: startResult.error } : {}),
+            ...(startResult.diagnostics ? { diagnostics: startResult.diagnostics } : {})
+        };
     }
     async resetAppData(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);

package/dist/server/common.js

@@ -48,12 +48,13 @@ export function inferScrollFailure(message) {
         return { failureCode: 'TIMEOUT', retryable: true };
     return { failureCode: 'UNKNOWN', retryable: false };
 }
-export function buildActionExecutionResult({ actionType, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure }) {
+export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details }) {
     const timestamp = Date.now();
     return {
         action_id: nextActionId(actionType, timestamp),
         timestamp,
         action_type: actionType,
+        ...(device ? { device } : {}),
         target: {
             selector,
             resolved: normalizeResolvedTarget(resolved)
@@ -61,6 +62,7 @@ export function buildActionExecutionResult({ actionType, selector, resolved, suc
         success,
         ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
         ui_fingerprint_before: uiFingerprintBefore,
-        ui_fingerprint_after: uiFingerprintAfter
+        ui_fingerprint_after: uiFingerprintAfter,
+        ...(details ? { details } : {})
     };
 }

package/dist/server/tool-handlers.js

@@ -13,11 +13,19 @@ async function handleStartApp(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'start_app',
+        device: res.device,
         selector: { appId },
         success: !!res.appStarted,
         uiFingerprintBefore,
         uiFingerprintAfter,
-        failure: res.appStarted ? undefined : inferGenericFailure(res.error)
+        failure: res.appStarted ? undefined : inferGenericFailure(res.error),
+        details: {
+            launch_time_ms: res.launchTimeMs,
+            ...(typeof res.output === 'string' ? { output: res.output } : {}),
+            ...(res.device ? { device_id: res.device.id } : {}),
+            ...(typeof res.error === 'string' ? { error: res.error } : {}),
+            ...(res.observedApp ? { observed_app: res.observedApp } : {})
+        }
     }));
 }
 async function handleTerminateApp(args) {
@@ -34,11 +42,20 @@ async function handleRestartApp(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'restart_app',
+        device: res.device,
         selector: { appId },
         success: !!res.appRestarted,
         uiFingerprintBefore,
         uiFingerprintAfter,
-        failure: res.appRestarted ? undefined : inferGenericFailure(res.error)
+        failure: res.appRestarted ? undefined : inferGenericFailure(res.error),
+        details: {
+            launch_time_ms: res.launchTimeMs,
+            ...(typeof res.output === 'string' ? { output: res.output } : {}),
+            ...(typeof res.terminatedBeforeRestart === 'boolean' ? { terminated_before_restart: res.terminatedBeforeRestart } : {}),
+            ...(typeof res.terminateError === 'string' ? { terminate_error: res.terminateError } : {}),
+            ...(typeof res.error === 'string' ? { error: res.error } : {}),
+            ...(res.observedApp ? { observed_app: res.observedApp } : {})
+        }
     }));
 }
 async function handleResetAppData(args) {

package/dist/system/index.js

@@ -8,8 +8,30 @@ export async function getSystemStatus() {
         const gradle = await checkGradle();
         const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])];
         const success = issues.length === 0;
+        const androidReady = android.adbAvailable && android.devices > 0 && !android.issues.some((issue) => /unauthorized|offline/i.test(issue));
+        const iosReady = ios.iosAvailable && ios.iosDevices > 0;
+        const gradleReady = (gradle.issues || []).length === 0;
+        const overallStatus = success ? 'ready' : (androidReady || iosReady ? 'degraded' : 'blocked');
+        const androidSummary = !android.adbAvailable
+            ? 'ADB unavailable'
+            : android.devices === 0
+                ? 'ADB available but no Android devices connected'
+                : android.logsAvailable
+                    ? `${android.devices} Android device(s) connected; log access available`
+                    : `${android.devices} Android device(s) connected; log access unavailable`;
+        const iosSummary = !ios.iosAvailable
+            ? 'xcrun unavailable'
+            : ios.iosDevices === 0
+                ? 'xcrun available but no iOS simulators booted'
+                : `${ios.iosDevices} iOS simulator(s) booted`;
+        const gradleSummary = !gradle.gradleJavaHome
+            ? 'No explicit Gradle JDK override detected'
+            : gradleReady
+                ? `Gradle JDK configured at ${gradle.gradleJavaHome}`
+                : `Gradle JDK override invalid: ${gradle.gradleJavaHome}`;
         return {
             success,
+            status: overallStatus,
             adbAvailable: android.adbAvailable,
             adbVersion: android.adbVersion,
             devices: android.devices,
@@ -23,10 +45,39 @@ export async function getSystemStatus() {
             gradleJavaHome: gradle.gradleJavaHome,
             gradleValid: gradle.gradleValid,
             gradleFilesChecked: gradle.filesChecked,
-            gradleSuggestedFixes: gradle.suggestedFixes
+            gradleSuggestedFixes: gradle.suggestedFixes,
+            summary: {
+                overall: overallStatus,
+                android: {
+                    ready: androidReady,
+                    summary: androidSummary,
+                    blockers: android.issues
+                },
+                ios: {
+                    ready: iosReady,
+                    summary: iosSummary,
+                    blockers: ios.issues
+                },
+                gradle: {
+                    ready: gradleReady,
+                    summary: gradleSummary,
+                    blockers: gradle.issues || [],
+                    suggestedFixes: gradle.suggestedFixes || []
+                }
+            }
         };
     }
     catch (e) {
-        return { success: false, issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))] };
+        return {
+            success: false,
+            status: 'blocked',
+            issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))],
+            summary: {
+                overall: 'blocked',
+                android: { ready: false, summary: 'Android status unavailable', blockers: [] },
+                ios: { ready: false, summary: 'iOS status unavailable', blockers: [] },
+                gradle: { ready: false, summary: 'Gradle status unavailable', blockers: [], suggestedFixes: [] }
+            }
+        };
     }
 }

package/docs/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.24.2]
+- Fixed Android install issue
+- Updated tools to have more detailed responses
+
 ## [0.24.1]
 - Fixed Android install issue
+- Updated tools to have more detailed responses
 
 ## [0.24.0]
 - Improved execution loop

package/docs/tools/interact.md

@@ -111,13 +111,26 @@ Input example:
 Success response example:
 
 ```json
-{ "success": true, "newFingerprint": "<hex-fingerprint>", "elapsedMs": 420 }
+{
+  "success": true,
+  "previousFingerprint": "<old-hex-fingerprint>",
+  "newFingerprint": "<hex-fingerprint>",
+  "elapsedMs": 420,
+  "observed_screen": { "fingerprint": "<hex-fingerprint>", "activity": "MainActivity" }
+}
 ```
 
 Failure (timeout) example:
 
 ```json
-{ "success": false, "reason": "timeout", "lastFingerprint": "<hex-fingerprint>", "elapsedMs": 5000 }
+{
+  "success": false,
+  "reason": "timeout",
+  "previousFingerprint": "<old-hex-fingerprint>",
+  "lastFingerprint": "<hex-fingerprint>",
+  "elapsedMs": 5000,
+  "observed_screen": { "fingerprint": "<hex-fingerprint>", "activity": "HomeActivity" }
+}
 ```
 
 Notes:
@@ -214,7 +227,26 @@ Success response:
     "index": 8,
     "elementId": "el_..."
   },
-  "metrics": { "latency_ms": 120, "poll_count": 1, "attempts": 1 }
+  "metrics": { "latency_ms": 120, "poll_count": 1, "attempts": 1 },
+  "requested": {
+    "selector": { "text": "Generate Session", "contains": false },
+    "condition": "clickable",
+    "match": { "index": 0 }
+  },
+  "observed": {
+    "matched_count": 1,
+    "condition_satisfied": true,
+    "selected_index": 8,
+    "last_matched_element": {
+      "text": "Generate Session",
+      "resource_id": null,
+      "accessibility_id": null,
+      "class": "android.widget.TextView",
+      "bounds": [471, 1098, 809, 1158],
+      "index": 8,
+      "elementId": "el_..."
+    }
+  }
 }
 ```
 
@@ -223,8 +255,27 @@ Timeout response:
 ```json
 {
   "status": "timeout",
-  "error": { "code": "ELEMENT_NOT_FOUND", "message": "Condition visible not satisfied within timeout" },
-  "metrics": { "latency_ms": 5000, "poll_count": 17, "attempts": 1 }
+  "error": { "code": "ELEMENT_NOT_FOUND", "message": "Condition visible not satisfied within timeout; observed 1 match(es)" },
+  "metrics": { "latency_ms": 5000, "poll_count": 17, "attempts": 1 },
+  "requested": {
+    "selector": { "text": "Generate Session", "contains": false },
+    "condition": "visible",
+    "match": { "index": 0 }
+  },
+  "observed": {
+    "matched_count": 1,
+    "condition_satisfied": false,
+    "selected_index": 8,
+    "last_matched_element": {
+      "text": "Generate Session",
+      "resource_id": null,
+      "accessibility_id": null,
+      "class": "android.widget.TextView",
+      "bounds": [471, 1098, 809, 1158],
+      "index": 8,
+      "elementId": "el_..."
+    }
+  }
 }
 ```
 
@@ -232,6 +283,7 @@ Notes:
 
 - Use `wait_for_ui` to get a stable `elementId` for `tap_element`.
 - Use it before an action when the target element or timing is uncertain.
+- Use `requested` and `observed` to see exactly what condition was checked and what the last poll actually found.
 - If the expected outcome is known after the action, follow with `expect_*`.
 
 ---
@@ -330,7 +382,12 @@ Response:
   "success": true,
   "observed_screen": { "fingerprint": "<actual-fingerprint>", "screen": "com.example.app.MainActivity" },
   "expected_screen": { "fingerprint": "<expected-fingerprint>", "screen": null },
-  "confidence": 1
+  "confidence": 1,
+  "comparison": {
+    "basis": "fingerprint",
+    "matched": true,
+    "reason": "observed fingerprint matches expected fingerprint <expected-fingerprint>"
+  }
 }
 ```
 
@@ -367,6 +424,7 @@ Response:
   "success": true,
   "selector": { "text": "Play session" },
   "element_id": "el_123",
+  "expected_condition": "visible",
   "element": {
     "elementId": "el_123",
     "text": "Play session",
@@ -375,7 +433,14 @@ Response:
     "class": "android.widget.TextView",
     "bounds": [519, 1770, 762, 1830],
     "index": 11
-  }
+  },
+  "observed": {
+    "status": "success",
+    "matched_count": 1,
+    "condition_satisfied": true,
+    "selected_index": 11
+  },
+  "reason": "selector is visible"
 }
 ```
 
@@ -384,4 +449,5 @@ Notes:
 - Primary and authoritative verification tool for expected element visibility.
 - `selector` is the primary input; `element_id` is optional context only.
 - The tool resolves the selector internally when needed.
+- On failure, `reason` and `observed` tell you whether the selector was missing entirely or present but not yet visible.
 - Use when the screen should remain on the same destination but a specific element should appear or become visible.