react-native-ai-debugger 1.5.1 → 1.6.0

package/build/index.js

@@ -5,13 +5,13 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { createServer as createHttpServer } from "node:http";
 import { existsSync, unlinkSync } from "fs";
 import { z } from "zod";
-import { getGuideOverview, getGuideByTopic, getAvailableTopics } from "./core/guides.js";
+import { getGuideOverview, getGuideByTopic, getAvailableTopics, DECISION_TREE } from "./core/guides.js";
 import { getLicenseStatus, getDashboardUrl, getUsageInfo } from "./core/license.js";
 import { API_BASE_URL } from "./core/config.js";
 import { getPostHogClient, identifyIfDevMode, shutdownPostHog } from "./core/posthog.js";
 import { getInstallationId, getServerVersion, getPackageName, isDevMode, TELEMETRY_JSONL_PATH, categorizeError } from "./core/telemetry.js";
 import { isSDKInstalled, querySDKNetwork, getSDKNetworkEntry, getSDKNetworkStats, clearSDKNetwork, querySDKConsole, getSDKConsoleStats, clearSDKConsole } from "./core/sdkBridge.js";
-import { tap, convertScreenshotToTapCoords } from "./pro/tap.js";
+import { tap } from "./pro/tap.js";
 import { getActivateLicenseConfig, handleActivateLicense, getDeleteAccountConfig, handleDeleteAccount, } from "./tools/accountTools.js";
 import { logBuffers, networkBuffers, getLogBuffer, getNetworkBuffer, getTotalLogCount, getConnectedAppByDevice, getConnectedAppBySimulatorUdid, getConnectedAppByAndroidDeviceId, LogBuffer, NetworkBuffer, bundleErrorBuffer, imageBuffer, connectedApps, getActiveOrBootedSimulatorUdid, scanMetroPorts, fetchDevices, filterDebuggableDevices, connectToDevice, getConnectedApps, executeInApp, listDebugGlobals, inspectGlobal, reloadApp, 
 // React Component Inspection
@@ -32,16 +32,10 @@ recognizeText, inferIOSDevicePixelRatio,
 listAndroidDevices, androidScreenshot, androidInstallApp, androidLaunchApp, androidListPackages, 
 // Android UI Input (Phase 2)
 ANDROID_KEY_EVENTS, androidTap, androidLongPress, androidSwipe, androidInputText, androidKeyEvent, androidGetScreenSize, androidGetDensity, androidGetStatusBarHeight, 
-// Android Accessibility (UI Hierarchy)
-androidDescribeAll, androidDescribePoint, 
-// Android Element Finding (no screenshots)
-androidFindElement, androidWaitForElement, 
 // iOS
 listIOSSimulators, iosScreenshot, iosInstallApp, iosLaunchApp, iosOpenUrl, iosTerminateApp, iosBootSimulator, 
 // iOS UI driver tools
-isUiDriverAvailable, iosTap, iosSwipe, iosInputText, iosButton, iosKeyEvent, iosKeySequence, iosDescribeAll, iosDescribePoint, IOS_BUTTON_TYPES, 
-// iOS Element Finding (no screenshots)
-iosFindElement, iosWaitForElement, getDevicePixelRatio, getIOSSafeAreaTop, 
+isUiDriverAvailable, iosTap, iosButton, iosDescribeAll, IOS_BUTTON_TYPES, getDevicePixelRatio, getIOSSafeAreaTop, 
 // Telemetry
 initTelemetry, trackToolInvocation, getTargetPlatform, 
 // Format utilities (TONL)
@@ -91,7 +85,13 @@ const server = new McpServer({
     name: "react-native-ai-devtools",
     version: "1.0.0"
 }, {
-    instructions: "React Native debugging MCP server. Call get_usage_guide to learn recommended workflows for all tools. Quick start: scan_metro → get_logs / search_logs (console debugging) → ios_screenshot → tap(text=\"Submit\") or tap(x, y) (interact with UI)."
+    instructions: [
+        "React Native debugging MCP server.",
+        "",
+        DECISION_TREE,
+        "",
+        "Call get_usage_guide with no arguments for the same decision tree plus a summary of every guide."
+    ].join("\n")
 });
 // ============================================================================
 // Telemetry Wrapper
@@ -178,9 +178,28 @@ const NON_METRO_TOOLS = new Set([
     "android_install_app",
     "send_feedback"
 ]);
-// Registry for dev meta-tool — stores handlers and configs for dynamic dispatch
+// Banner helpers for platform-specific tool descriptions. Appended after the
+// verbatim first sentence of every ios_*/android_* tool to steer agents toward
+// cross-platform primaries (tap, get_screen_layout, etc) unless native-only
+// behavior is required. See src/core/nativeOnlyHints.ts for the complementary
+// runtime hint shown when Metro is absent.
+const platformFallbackBanner = (prefer) => `\n[PLATFORM FALLBACK — prefer ${prefer} unless you specifically need native-only behavior]`;
+const platformUniqueBanner = (useCase) => `\n[PLATFORM-SPECIFIC — no cross-platform equivalent; use when ${useCase}]`;
+const primaryInteractionBanner = () => `\n[PRIMARY INTERACTION TOOL — works on iOS and Android; prefer over ios_*/android_* siblings]`;
+// Registry for dev meta-tool — stores handlers and configs for dynamic dispatch.
+// Also exported so unit tests can enumerate every registered tool without booting
+// the server. Populated by registerToolWithTelemetry AND by the server.registerTool
+// interceptor installed below, so it captures every registration site.
 /* eslint-disable @typescript-eslint/no-explicit-any */
-const toolRegistry = new Map();
+export const toolRegistry = new Map();
+// Interceptor: capture every direct server.registerTool call into toolRegistry so
+// tests and the dev meta-tool see the full surface (including platform-native tools
+// and the dev meta-tool itself that bypass registerToolWithTelemetry).
+const _originalRegisterTool = server.registerTool.bind(server);
+server.registerTool = (name, config, handler) => {
+    toolRegistry.set(name, { config, handler });
+    return _originalRegisterTool(name, config, handler);
+};
 function registerToolWithTelemetry(toolName, config, handler, emptyResultDetector) {
     toolRegistry.set(toolName, { config, handler });
     server.registerTool(toolName, config, async (args) => {
@@ -360,7 +379,13 @@ registerToolWithTelemetry("get_usage_guide", {
 });
 // Tool: Scan for Metro servers
 registerToolWithTelemetry("scan_metro", {
-    description: "Scan for running Metro bundler servers and automatically connect to any found React Native apps. This is typically the FIRST tool to call when starting a debugging session - it establishes the connection needed for other tools like get_logs, list_debug_globals, execute_in_app, and reload_app.",
+    description: "Scan for running Metro bundler servers and automatically connect to any found React Native apps. This is typically the FIRST tool to call when starting a debugging session - it establishes the connection needed for other tools like get_logs, list_debug_globals, execute_in_app, and reload_app.\n" +
+        "PURPOSE: Discover Metro on common ports (8081, 8082, 19000-19002) and auto-connect all React Native debugger targets it advertises.\n" +
+        "WHEN TO USE: At the start of any session, or after the user restarts Metro / boots a new simulator.\n" +
+        "WORKFLOW: scan_metro -> get_apps -> get_logs / ios_screenshot / tap.\n" +
+        "GOOD: scan_metro()\n" +
+        "BAD: scan_metro() called repeatedly in a loop — use ensure_connection to re-verify an existing connection.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         startPort: z.coerce.number().optional().default(8081).describe("Start port for scanning (default: 8081)"),
         endPort: z.coerce.number().optional().default(19002).describe("End port for scanning (default: 19002)")
@@ -482,7 +507,7 @@ registerToolWithTelemetry("scan_metro", {
         const uiDriverOk = await isUiDriverAvailable();
         if (!uiDriverOk) {
             results.push("");
-            results.push("⚠️  WARNING: iOS UI driver is NOT installed. Tools like tap, ios_swipe, ios_input_text, ios_describe_all, and ios_find_element will fail.");
+            results.push("⚠️  WARNING: iOS UI driver is NOT installed. The `tap` tool and other UI-interaction tools will fail.");
             results.push("   Install the recommended driver: brew install cameroncooke/axe/axe");
             results.push("   Then set IOS_DRIVER=axe in your MCP server environment.");
             results.push("   Alternative: brew install idb-companion (used by default)");
@@ -497,224 +522,15 @@ registerToolWithTelemetry("scan_metro", {
         ]
     };
 });
-// Tool: Get connected apps
-registerToolWithTelemetry("get_apps", {
-    description: "List currently connected React Native apps and their connection status. If no apps are connected, run scan_metro first to establish a connection.",
-    inputSchema: {}
-}, async () => {
-    const apps = getConnectedApps();
-    if (apps.length === 0) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "No connected devices. Run scan_metro to discover and connect to Metro servers."
-                }
-            ]
-        };
-    }
-    const deviceLines = apps
-        .filter(({ isConnected }) => isConnected)
-        .map(({ app }, i) => {
-        const name = app.deviceInfo.deviceName || app.deviceInfo.title;
-        const appId = app.deviceInfo.appId || app.deviceInfo.title.split(" (")[0] || "unknown";
-        const lines = [`  ${i + 1}. ${name} — ${appId} (${app.platform}, port ${app.port})`];
-        if (app.appDetection) {
-            const d = app.appDetection;
-            const version = d.reactNativeVersion !== "unknown" ? `RN ${d.reactNativeVersion}` : "RN unknown";
-            const expo = d.expoSdkVersion ? `, Expo SDK ${d.expoSdkVersion}` : "";
-            lines.push(`     Environment: ${version}, ${d.architecture} arch, ${d.jsEngine}, ${app.platform} ${d.osVersion}${expo}`);
-        }
-        return lines.join("\n");
-    });
-    const text = [
-        `Connected devices:`,
-        ...deviceLines,
-        ``,
-        `Use device="${apps[0].app.deviceInfo.deviceName}" to target a specific device.`,
-        ``,
-        `Total logs in buffer: ${getTotalLogCount()}`
-    ].join("\n");
-    return {
-        content: [{ type: "text", text }]
-    };
-});
-// Tool: Get connection status (detailed health and gap tracking)
-registerToolWithTelemetry("get_connection_status", {
-    description: "Get detailed connection health status including uptime, recent disconnects/reconnects, and connection gaps that may indicate missing data.",
-    inputSchema: {}
-}, async () => {
-    const connections = getConnectedApps();
-    const states = getAllConnectionStates();
-    const metadata = getAllConnectionMetadata();
-    const lines = [];
-    lines.push("=== Connection Status ===\n");
-    if (connections.length === 0 && states.size === 0) {
-        lines.push("No connections established. Run scan_metro to connect.");
-        return {
-            content: [{ type: "text", text: lines.join("\n") }]
-        };
-    }
-    // Show active connections
-    for (const { key, app, isConnected } of connections) {
-        const state = states.get(key);
-        const contextHealth = getContextHealth(key);
-        lines.push(`--- ${app.deviceInfo.title} (Port ${app.port}) ---`);
-        lines.push(`  Status: ${isConnected ? "CONNECTED" : "DISCONNECTED"}`);
-        if (state) {
-            if (state.lastConnectedTime) {
-                const uptime = Date.now() - state.lastConnectedTime.getTime();
-                lines.push(`  Connected since: ${state.lastConnectedTime.toLocaleTimeString()}`);
-                lines.push(`  Uptime: ${formatDuration(uptime)}`);
-            }
-            if (state.status === "reconnecting") {
-                lines.push(`  Reconnecting: Attempt ${state.reconnectionAttempts}`);
-            }
-            // Show recent gaps (last 5 minutes)
-            if (state.connectionGaps.length > 0) {
-                const recentGaps = state.connectionGaps.filter((g) => Date.now() - g.disconnectedAt.getTime() < 300000);
-                if (recentGaps.length > 0) {
-                    lines.push(`  Recent gaps: ${recentGaps.length}`);
-                    for (const gap of recentGaps.slice(-3)) {
-                        const duration = gap.durationMs ? formatDuration(gap.durationMs) : "ongoing";
-                        lines.push(`    - ${gap.disconnectedAt.toLocaleTimeString()} (${duration}): ${gap.reason}`);
-                    }
-                }
-            }
-        }
-        // Show context health
-        if (contextHealth) {
-            lines.push(`  Context Health:`);
-            lines.push(`    Context ID: ${contextHealth.contextId ?? "unknown"}`);
-            lines.push(`    Status: ${contextHealth.isStale ? "STALE" : "HEALTHY"}`);
-            if (contextHealth.lastHealthCheck) {
-                const healthResult = contextHealth.lastHealthCheckSuccess ? "PASS" : "FAIL";
-                lines.push(`    Last Check: ${contextHealth.lastHealthCheck.toLocaleTimeString()} (${healthResult})`);
-            }
-            if (contextHealth.lastContextCreated) {
-                lines.push(`    Context Created: ${contextHealth.lastContextCreated.toLocaleTimeString()}`);
-            }
-            if (contextHealth.lastContextDestroyed) {
-                lines.push(`    Context Destroyed: ${contextHealth.lastContextDestroyed.toLocaleTimeString()}`);
-            }
-        }
-        lines.push("");
-    }
-    // Show disconnected/reconnecting states without active connections
-    for (const [key, state] of states.entries()) {
-        if (!connections.find((c) => c.key === key)) {
-            const meta = metadata.get(key);
-            lines.push(`--- ${meta?.deviceInfo.title || key} (Disconnected) ---`);
-            lines.push(`  Status: ${state.status.toUpperCase()}`);
-            if (state.lastDisconnectTime) {
-                lines.push(`  Disconnected at: ${state.lastDisconnectTime.toLocaleTimeString()}`);
-            }
-            if (state.reconnectionAttempts > 0) {
-                lines.push(`  Reconnection attempts: ${state.reconnectionAttempts}`);
-            }
-            lines.push("");
-        }
-    }
-    return {
-        content: [{ type: "text", text: lines.join("\n") }]
-    };
-});
-// Tool: License status
-registerToolWithTelemetry("get_license_status", {
-    description: "Get your installation ID and license status. Shows your unique Installation ID (needed to activate Pro in the dashboard), current license tier, and cache validity.",
-    inputSchema: {},
-}, async () => {
-    const status = getLicenseStatus();
-    const lines = [];
-    lines.push(`Installation ID: ${status.installationId}`);
-    lines.push(`License: ${status.tier.charAt(0).toUpperCase() + status.tier.slice(1)}`);
-    if (status.plan) {
-        lines.push(`Plan expires: ${status.plan.expiresAt}`);
-    }
-    lines.push(`Cache valid until: ${status.cacheExpiresAt}`);
-    // Usage limits
-    const usage = getUsageInfo();
-    if (usage) {
-        lines.push("");
-        lines.push("--- Usage ---");
-        if (usage.creditsRemaining !== null) {
-            lines.push(`Credits remaining: ${usage.creditsRemaining.toLocaleString()}`);
-            lines.push(`Used this month: ${usage.used.toLocaleString()}`);
-        }
-        else {
-            lines.push(`Monthly usage: ${usage.used} / ${usage.limit}`);
-        }
-        lines.push(`Month: ${usage.monthKey}`);
-        if (usage.promotionalPeriod) {
-            const endsAt = usage.promotionalPeriodEndsAt
-                ? new Date(usage.promotionalPeriodEndsAt).toLocaleDateString("en-GB", { day: "2-digit", month: "2-digit", year: "numeric" })
-                : "unknown";
-            lines.push(`Status: Active (promotional period — no limits until ${endsAt})`);
-        }
-        else {
-            lines.push(`Status: ${usage.canUse ? "Active" : "Limit reached"}`);
-        }
-    }
-    if (status.tier === "free") {
-        const dashboardUrl = getDashboardUrl();
-        lines.push("");
-        if (dashboardUrl) {
-            lines.push(`Link your account: ${dashboardUrl}/link?id=${status.installationId}`);
-        }
-    }
-    return {
-        content: [{ type: "text", text: lines.join("\n") }],
-    };
-});
-// Tool: Send feedback / bug report / feature request
-registerToolWithTelemetry("send_feedback", {
-    description: "Create a feedback report (bug, feature request, or general feedback) for the react-native-ai-devtools team. " +
-        "Auto-collects environment info. Returns a pre-filled GitHub issue URL and formatted issue body. " +
-        "Ask the user to open the URL and paste the body to submit.",
-    inputSchema: {
-        type: z.enum(["feedback", "feature_request", "bug"]).describe('Type of feedback: "feedback", "feature_request", or "bug"'),
-        title: z.string().describe("Short summary (becomes the GitHub issue title)"),
-        description: z.string().describe("Detailed description of the feedback, feature request, or bug"),
-        workflow_context: z.string().optional().describe("What the user was trying to accomplish when they decided to give feedback")
-    }
-}, async ({ type, title, description, workflow_context }) => {
-    // Collect environment info
-    const serverVersion = getServerVersion();
-    const platform = process.platform;
-    const deviceType = getTargetPlatform();
-    const licenseStatus = getLicenseStatus();
-    const env = {
-        serverVersion,
-        platform,
-        deviceType,
-        licenseTier: licenseStatus.tier
-    };
-    const input = { type, title, description, workflowContext: workflow_context };
-    const issueBody = formatIssueBody(input, env);
-    const githubUrl = buildGitHubUrl(title, type);
-    const output = [
-        "## Feedback Report Ready",
-        "",
-        `**GitHub Issue URL:** ${githubUrl}`,
-        "",
-        "**Issue body to paste:**",
-        "",
-        "```markdown",
-        issueBody,
-        "```",
-        "",
-        "Please ask the user to:",
-        "1. Open the GitHub URL above",
-        "2. Paste the issue body into the description field",
-        "3. Review and submit the issue"
-    ].join("\n");
-    return {
-        content: [{ type: "text", text: output }]
-    };
-});
 // Tool: Ensure connection health
 registerToolWithTelemetry("ensure_connection", {
-    description: "Verify or establish a healthy connection to a React Native app. Use before running commands if connection may be stale, or after navigation/reload. This tool runs a health check and will auto-reconnect if needed.",
+    description: "Verify or establish a healthy connection to a React Native app. Use before running commands if connection may be stale, or after navigation/reload. This tool runs a health check and will auto-reconnect if needed.\n" +
+        "PURPOSE: Health-check the existing CDP connection and transparently reconnect if it has gone stale, without rescanning all Metro ports.\n" +
+        "WHEN TO USE: After a suspected disconnect (silent gaps, reload_app, app crash) or before long-running flows where a mid-flow drop would be costly. Cheaper than scan_metro when you already connected once this session.\n" +
+        "WORKFLOW: scan_metro (once) -> ensure_connection(healthCheck=true) -> resume tool calls. Use forceRefresh=true if the first probe still looks dead.\n" +
+        "GOOD: ensure_connection({ healthCheck: true })\n" +
+        "BAD: ensure_connection() before scan_metro has ever run — call scan_metro first.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         port: z.coerce.number().optional().describe("Metro port (default: auto-detect)"),
         healthCheck: z
@@ -763,48 +579,280 @@ registerToolWithTelemetry("ensure_connection", {
         content: [{ type: "text", text: lines.join("\n") }]
     };
 });
-// Tool: Get console logs
-registerToolWithTelemetry("get_logs", {
-    description: "Retrieve console logs from connected React Native app. Tip: Use summary=true first for a quick overview (counts by level + last 5 messages), then fetch specific logs as needed.",
-    inputSchema: {
-        maxLogs: z.coerce
-            .number()
-            .optional()
-            .default(50)
-            .describe("Maximum number of logs to return (default: 50)"),
-        level: z
-            .enum(["all", "log", "warn", "error", "info", "debug"])
-            .optional()
-            .default("all")
-            .describe("Filter by log level (default: all)"),
-        startFromText: z.string().optional().describe("Start from the first log line containing this text"),
-        maxMessageLength: z.coerce
-            .number()
-            .optional()
-            .default(500)
-            .describe("Max characters per message (default: 500, set to 0 for unlimited). Tip: Use lower values for overview, higher when debugging specific data structures."),
-        verbose: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Disable all truncation and return full messages. Tip: Use with lower maxLogs (e.g., 10) to avoid token overload when inspecting large objects."),
-        format: z
-            .enum(["text", "tonl"])
-            .optional()
-            .default("tonl")
-            .describe("Output format: 'text' or 'tonl' (default, compact token-optimized format, ~30-50% smaller)"),
-        summary: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Return summary statistics instead of full logs (count by level + last 5 messages). Use for quick overview."),
-        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
-    }
-}, async ({ maxLogs, level, startFromText, maxMessageLength, verbose, format, summary, device }) => {
-    // Check if SDK is installed — prefer SDK data for richer logs
-    const sdkAvailable = await isSDKInstalled();
-    if (sdkAvailable) {
-        if (summary) {
+// Tool: Get connected apps
+registerToolWithTelemetry("get_apps", {
+    description: "List currently connected React Native apps and their connection status. If no apps are connected, run scan_metro first to establish a connection.\n" +
+        "PURPOSE: Enumerate active debug targets with device names, platforms, ports, and detected RN/Expo versions so you can target the right one.\n" +
+        "WHEN TO USE: After scan_metro to confirm what connected, or before passing a device=\"...\" filter to another tool.\n" +
+        "WORKFLOW: scan_metro -> get_apps -> get_logs / ios_screenshot / tap (with device=\"...\" if multiple).\n" +
+        "LIMITATIONS: Only lists devices the MCP has successfully connected to — stale targets don't appear here, use get_connection_status for health details.\n" +
+        "GOOD: get_apps()\n" +
+        "BAD: Calling get_apps in a tight loop — the list doesn't change without a scan_metro or disconnect_metro.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
+    inputSchema: {}
+}, async () => {
+    const apps = getConnectedApps();
+    if (apps.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No connected devices. Run scan_metro to discover and connect to Metro servers."
+                }
+            ]
+        };
+    }
+    const deviceLines = apps
+        .filter(({ isConnected }) => isConnected)
+        .map(({ app }, i) => {
+        const name = app.deviceInfo.deviceName || app.deviceInfo.title;
+        const appId = app.deviceInfo.appId || app.deviceInfo.title.split(" (")[0] || "unknown";
+        const lines = [`  ${i + 1}. ${name} — ${appId} (${app.platform}, port ${app.port})`];
+        if (app.appDetection) {
+            const d = app.appDetection;
+            const version = d.reactNativeVersion !== "unknown" ? `RN ${d.reactNativeVersion}` : "RN unknown";
+            const expo = d.expoSdkVersion ? `, Expo SDK ${d.expoSdkVersion}` : "";
+            lines.push(`     Environment: ${version}, ${d.architecture} arch, ${d.jsEngine}, ${app.platform} ${d.osVersion}${expo}`);
+        }
+        return lines.join("\n");
+    });
+    const text = [
+        `Connected devices:`,
+        ...deviceLines,
+        ``,
+        `Use device="${apps[0].app.deviceInfo.deviceName}" to target a specific device.`,
+        ``,
+        `Total logs in buffer: ${getTotalLogCount()}`
+    ].join("\n");
+    return {
+        content: [{ type: "text", text }]
+    };
+});
+// Tool: Unified tap — tries fiber, accessibility, OCR, coordinate strategies
+registerToolWithTelemetry("tap", {
+    description: "Tap a UI element. Automatically tries multiple strategies: fiber tree (React), accessibility tree (native), and OCR (visual)." +
+        primaryInteractionBanner() + "\n" +
+        "PURPOSE: Single unified tap entry point — resolves text/testID/component/coordinates into a real touch event on the correct device.\n" +
+        "WHEN TO USE: Any time you need to press a button, focus an input, open a menu, or verify a handler fires. Prefer testID, then text, then component, then (x,y) from a screenshot's pressables list.\n" +
+        "WORKFLOW: ios_screenshot or android_screenshot -> tap(testID=\"...\") | tap(text=\"...\") | tap(x, y) -> screenshot again to verify. Use burst=true when meaningful=false but visual feedback looks transient.\n" +
+        "LIMITATIONS: iOS needs AXe (brew install cameroncooke/axe/axe) or IDB for accessibility/coordinate taps. Non-ASCII text skips fiber (Hermes); prefer testID. When iOS AND Android are connected, pass platform explicitly.\n" +
+        "GOOD: tap({ testID: \"login-btn\" }); tap({ text: \"Submit\" }); tap({ x: 300, y: 600 }); tap({ x: 300, y: 600, native: true, platform: \"android\" })\n" +
+        "BAD: tap({ text: \"\" }) or tap({ x: 0, y: 0 }) — missing a target. tap({ text: \"Submit\" }) without first screenshotting an ambiguous screen.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full device-interaction playbook.",
+    inputSchema: {
+        text: z
+            .string()
+            .optional()
+            .describe("Visible text to match (case-insensitive substring). ASCII only for fiber strategy; OCR handles non-ASCII."),
+        testID: z
+            .string()
+            .optional()
+            .describe("Exact match on the element's testID prop."),
+        component: z
+            .string()
+            .optional()
+            .describe("Component name match (case-insensitive substring, e.g. 'Button', 'MenuItem')."),
+        index: z.coerce
+            .number()
+            .optional()
+            .describe("Zero-based index when multiple elements match (default: 0)."),
+        x: z.coerce
+            .number()
+            .optional()
+            .describe("X coordinate in pixels (from screenshot). Must provide both x and y."),
+        y: z.coerce
+            .number()
+            .optional()
+            .describe("Y coordinate in pixels (from screenshot). Must provide both x and y."),
+        strategy: z
+            .enum(["auto", "fiber", "accessibility", "ocr", "coordinate"])
+            .optional()
+            .default("auto")
+            .describe('"auto" (default) tries fiber -> accessibility -> OCR. Set explicitly to skip strategies you know will fail.'),
+        maxTraversalDepth: z.coerce
+            .number()
+            .optional()
+            .describe("Max parent levels to traverse when searching by component name (default: 15). " +
+            "Increase if your component is deeply wrapped (e.g. inside multiple HOCs/animation wrappers)."),
+        native: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, tap coordinates directly via ADB/simctl without requiring a React Native connection. " +
+            "Useful for interacting with native UI, system dialogs, or non-RN apps. Requires x/y coordinates."),
+        platform: z
+            .enum(["ios", "android"])
+            .optional()
+            .describe("Target platform. Required when both iOS and Android devices are connected. Auto-detected if only one platform is available."),
+        screenshot: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Capture and return a post-tap screenshot. Enabled by default. Set to false for fastest execution (no screenshots)."),
+        verify: z
+            .boolean()
+            .optional()
+            .describe("Run before/after screenshot diff to detect if the tap had a meaningful visual effect. " +
+            "Default: true for coordinate/accessibility/ocr strategies, false for fiber. Requires screenshot=true."),
+        burst: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Enable burst screenshot capture for enhanced verification. " +
+            "Captures 4 rapid screenshots (~150ms intervals) after the tap to detect transient visual feedback " +
+            "(press animations, highlights, ripples) that may settle before a standard after-screenshot. " +
+            "Results are stored in the image buffer (use get_images to inspect individual frames). " +
+            "Default: false."),
+    },
+}, async (args) => {
+    const result = await tap({
+        text: args.text,
+        testID: args.testID,
+        component: args.component,
+        index: args.index,
+        x: args.x,
+        y: args.y,
+        strategy: args.strategy,
+        maxTraversalDepth: args.maxTraversalDepth,
+        native: args.native,
+        platform: args.platform,
+        screenshot: args.screenshot,
+        verify: args.verify,
+        burst: args.burst,
+    });
+    const { screenshot: screenshotData, ...resultWithoutScreenshot } = result;
+    const text = JSON.stringify(resultWithoutScreenshot, null, 2);
+    // Pack strategy mode + attempted strategies into errorContext for telemetry
+    // e.g. "s=ocr|fiber:no_pressable|ocr:no_match" or "s=auto|fiber:no_pressable|accessibility:not_found|ocr:no_match"
+    const stratPrefix = args.strategy && args.strategy !== "auto" ? `s=${args.strategy}|` : "";
+    const errorContext = result.attempted?.length
+        ? stratPrefix + result.attempted.map(a => `${a.strategy}:${a.reason.slice(0, 40)}`).join("|")
+        : undefined;
+    const content = [
+        { type: "text", text },
+    ];
+    if (screenshotData) {
+        content.push({
+            type: "image",
+            data: screenshotData.image,
+            mimeType: "image/jpeg",
+        });
+    }
+    return {
+        content,
+        isError: !result.success && !result.ambiguous,
+        _errorMessage: !result.success && !result.ambiguous
+            ? `${JSON.stringify(result.query)}|${result.error || ""}`
+            : undefined,
+        _errorContext: errorContext,
+        _meaningful: result.verification?.meaningful,
+        _changeRate: result.verification?.changeRate,
+        _tapStrategy: result.method,
+        _iosDriver: result.platform === "ios" ? (process.env.IOS_DRIVER?.toLowerCase() || "idb") : undefined,
+    };
+});
+// Tool: Get full screen layout (all components with layout styles)
+registerToolWithTelemetry("get_screen_layout", {
+    description: "Get a screen map showing visible components as an indented tree with actual screen positions. Uses measureInWindow for real coordinates and filters out off-screen components. Returns meaningful component names with text content and frame data (x,y width x height). Coordinates are in **points** (iOS) or **dp** (Android) — NOT screenshot pixels. Use tap(text=...) or tap(testID=...) to interact with discovered components. Use extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.)." +
+        primaryInteractionBanner() + "\n" +
+        "PURPOSE: Quickest textual map of what is actually on screen right now — component names, positions, and text — so you can plan taps and inspections without guessing.\n" +
+        "WHEN TO USE: First step whenever the user asks \"what's on screen\", \"why is X covering Y\", or before tapping a visually ambiguous element.\n" +
+        "WORKFLOW: get_screen_layout -> find_components(pattern=\"...\") or inspect_component(componentName=\"...\") -> tap(testID=...) -> get_screen_layout again to confirm.\n" +
+        "LIMITATIONS: Coordinates are points/dp, not screenshot pixels — pass them to tap() which handles conversion, do not multiply by devicePixelRatio yourself.\n" +
+        "GOOD: get_screen_layout({ extended: true })\n" +
+        "BAD: get_screen_layout({ summary: true }) when you actually need to pick a specific element — summary hides the tree.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"layout\") for the full layout-check playbook.",
+    inputSchema: {
+        extended: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include layout styles (padding, margin, flex, backgroundColor, borderRadius, etc.) for each component. Default: false for compact output."),
+        summary: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return only component counts by name instead of full tree (default: false)"),
+        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
+    }
+}, async ({ extended, summary, device }) => {
+    if (!hasMetro()) {
+        const hint = await metroMissingHintIfAbsent("get_screen_layout");
+        return {
+            content: [{ type: "text", text: `Screen Layout unavailable.${hint}` }],
+            isError: true
+        };
+    }
+    const result = await getScreenLayout({ extended, summary, device });
+    if (!result.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${result.error}`
+                }
+            ],
+            isError: true
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Screen Layout:\n\n${result.result}`
+            }
+        ]
+    };
+});
+// Tool: Get console logs
+registerToolWithTelemetry("get_logs", {
+    description: "Retrieve console logs from connected React Native app. Tip: Use summary=true first for a quick overview (counts by level + last 5 messages), then fetch specific logs as needed.\n" +
+        "PURPOSE: Pull captured console output (log/warn/error/info/debug) from the in-memory buffer for the connected app.\n" +
+        "WHEN TO USE: Start of any log-driven investigation, verifying a code change picked up via Fast Refresh, or confirming a reported error actually fires.\n" +
+        "WORKFLOW: scan_metro -> get_logs(summary=true) -> narrow with search_logs(text=\"...\") or get_logs(level=\"error\") -> clear_logs between reproductions.\n" +
+        "LIMITATIONS: Circular buffer (~500 entries). Only captures logs emitted after the app connected; pre-connect logs are lost.\n" +
+        "GOOD: get_logs({ summary: true }) then get_logs({ level: \"error\", maxLogs: 20 })\n" +
+        "BAD: get_logs({ maxLogs: 500, verbose: true }) as a first call — floods context; start with summary=true.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"logs\") for the full console-debugging playbook.",
+    inputSchema: {
+        maxLogs: z.coerce
+            .number()
+            .optional()
+            .default(50)
+            .describe("Maximum number of logs to return (default: 50)"),
+        level: z
+            .enum(["all", "log", "warn", "error", "info", "debug"])
+            .optional()
+            .default("all")
+            .describe("Filter by log level (default: all)"),
+        startFromText: z.string().optional().describe("Start from the first log line containing this text"),
+        maxMessageLength: z.coerce
+            .number()
+            .optional()
+            .default(500)
+            .describe("Max characters per message (default: 500, set to 0 for unlimited). Tip: Use lower values for overview, higher when debugging specific data structures."),
+        verbose: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Disable all truncation and return full messages. Tip: Use with lower maxLogs (e.g., 10) to avoid token overload when inspecting large objects."),
+        format: z
+            .enum(["text", "tonl"])
+            .optional()
+            .default("tonl")
+            .describe("Output format: 'text' or 'tonl' (default, compact token-optimized format, ~30-50% smaller)"),
+        summary: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return summary statistics instead of full logs (count by level + last 5 messages). Use for quick overview."),
+        device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ maxLogs, level, startFromText, maxMessageLength, verbose, format, summary, device }) => {
+    // Check if SDK is installed — prefer SDK data for richer logs
+    const sdkAvailable = await isSDKInstalled();
+    if (sdkAvailable) {
+        if (summary) {
             const sdkStats = await getSDKConsoleStats();
             if (sdkStats.success) {
                 const s = sdkStats.data;
@@ -987,7 +1035,14 @@ registerToolWithTelemetry("get_logs", {
 () => getTotalLogCount() === 0);
 // Tool: Search logs
 registerToolWithTelemetry("search_logs", {
-    description: "Search console logs for text (case-insensitive)",
+    description: "Search console logs for text (case-insensitive).\n" +
+        "PURPOSE: Find log lines matching a substring across the connected app's console buffer.\n" +
+        "WHEN TO USE: User reports a known error/warning, or wants to trace a specific event (e.g., \"redux\", \"auth failed\"). For unfocused exploration, prefer get_logs.\n" +
+        "WORKFLOW: scan_metro -> search_logs(text=\"...\") -> if empty, get_logs to verify buffer populated.\n" +
+        "LIMITATIONS: Only matches text captured AFTER the app connected; won't find pre-connect logs.\n" +
+        "GOOD: search_logs({ text: \"TypeError\" })\n" +
+        "BAD: search_logs({ text: \"\" })  (use get_logs for a raw dump)\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"logs\") for the full console-debugging playbook.",
     inputSchema: {
         text: z.string().describe("Text to search for in log messages"),
         maxResults: z.coerce
@@ -1075,15 +1130,584 @@ registerToolWithTelemetry("search_logs", {
         ]
     };
 });
-// Tool: Clear logs
-registerToolWithTelemetry("clear_logs", {
-    description: "Clear the log buffer",
+// Tool: iOS screenshot
+registerToolWithTelemetry("ios_screenshot", {
+    description: "Take a screenshot from an iOS simulator. Returns the image plus two lists: (1) pressable elements — the tappable components on screen with ready-to-use pixel tap coordinates, testIDs, and labels; (2) screen layout — all visible React components for context. Prefer tap(text=\"...\") when text is exact and unique; otherwise use tap(x, y) with coordinates from the pressables list — this is the most reliable way to tap icons or visually-identified elements. Use component names from the layout for inspect_component/find_components.\n" +
+        "PURPOSE: Snapshot what the user sees on iOS AND get tap-ready pressables + a structured component map in one call.\n" +
+        "WHEN TO USE: Any visual verification, before/after comparison, or as the starting point for tapping UI by coordinates.\n" +
+        "WORKFLOW: ios_screenshot -> pick element from pressables -> tap(x, y) or tap(testID=...) -> ios_screenshot to verify.\n" +
+        "LIMITATIONS: Requires a booted iOS simulator (simctl). For physical devices or system dialogs without RN, combine with tap(..., native=true).\n" +
+        "GOOD: ios_screenshot()\n" +
+        "BAD: ios_screenshot({ udid: \"guess\" }) with a made-up UDID — run list_ios_simulators first.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full device-interaction playbook.",
     inputSchema: {
-        device: z.string().optional().describe("Target device name (substring match). Omit to clear all devices. Run get_apps to see connected devices.")
+        outputPath: z
+            .string()
+            .optional()
+            .describe("Optional path to save the screenshot. If not provided, saves to temp directory."),
+        udid: z
+            .string()
+            .optional()
+            .describe("Optional simulator UDID (from list_ios_simulators). Uses booted simulator if not specified.")
     }
-}, async ({ device }) => {
-    if (device) {
-        const app = getConnectedAppByDevice(device);
+}, async ({ outputPath, udid }) => {
+    const result = await iosScreenshot(outputPath, udid);
+    if (!result.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${result.error}`
+                }
+            ],
+            isError: true
+        };
+    }
+    // Include image data if available
+    if (result.data) {
+        // Build info text with coordinate guidance for iOS
+        const pixelWidth = result.originalWidth || 0;
+        const pixelHeight = result.originalHeight || 0;
+        // Resolve the RN app running on THIS simulator so enrichment pulls
+        // fiber/layout data from the right app (not the first-connected one,
+        // which may belong to a different simulator).
+        const resolvedUdid = udid || (await getActiveOrBootedSimulatorUdid());
+        const targetApp = resolvedUdid ? getConnectedAppBySimulatorUdid(resolvedUdid) : null;
+        const targetDeviceName = targetApp?.deviceInfo.deviceName;
+        // Store screenshot metadata on the matching app (not an arbitrary one)
+        if (targetApp) {
+            targetApp.lastScreenshot = {
+                originalWidth: pixelWidth,
+                originalHeight: pixelHeight,
+                scaleFactor: result.scaleFactor || 1,
+            };
+        }
+        // Try to get actual screen dimensions and safe area from accessibility tree
+        let pointWidth = 0;
+        let pointHeight = 0;
+        let scaleFactor = 3; // Default to 3x for modern iPhones
+        let safeAreaTop = 59; // Default safe area offset
+        try {
+            const describeResult = await iosDescribeAll(udid);
+            if (describeResult.success && describeResult.elements && describeResult.elements.length > 0) {
+                // First element is typically the Application with full screen frame
+                const rootElement = describeResult.elements[0];
+                // Try parsed frame first, then parse AXFrame string
+                if (rootElement.frame) {
+                    pointWidth = Math.round(rootElement.frame.width);
+                    pointHeight = Math.round(rootElement.frame.height);
+                    // The frame.y of the root element indicates where content starts (after status bar)
+                    if (rootElement.frame.y > 0) {
+                        safeAreaTop = Math.round(rootElement.frame.y);
+                    }
+                }
+                else if (rootElement.AXFrame) {
+                    // Parse format: "{{x, y}, {width, height}}"
+                    const match = rootElement.AXFrame.match(/\{\{([\d.]+),\s*([\d.]+)\},\s*\{([\d.]+),\s*([\d.]+)\}\}/);
+                    if (match) {
+                        const frameY = parseFloat(match[2]);
+                        pointWidth = Math.round(parseFloat(match[3]));
+                        pointHeight = Math.round(parseFloat(match[4]));
+                        if (frameY > 0) {
+                            safeAreaTop = Math.round(frameY);
+                        }
+                    }
+                }
+                // Calculate actual scale factor
+                if (pointWidth > 0) {
+                    scaleFactor = Math.round(pixelWidth / pointWidth);
+                }
+            }
+        }
+        catch {
+            // Fallback: use 3x scale for modern devices
+        }
+        // Fallback if we couldn't get dimensions
+        if (pointWidth === 0) {
+            pointWidth = Math.round(pixelWidth / scaleFactor);
+            pointHeight = Math.round(pixelHeight / scaleFactor);
+        }
+        const safeAreaOffsetPixels = safeAreaTop * scaleFactor;
+        // The Screen Layout tree was previously appended here but produced huge noisy
+        // output (nested Svg/G/Path duplicates). Agents should use get_screen_layout
+        // explicitly when they need the tree. The Pressable elements block below is
+        // the signal most consumers actually want.
+        let pressablesText = null;
+        const canEnrich = !!targetApp;
+        // Enrich with pressable elements (filtered list of tappable components, converted to screenshot pixel coords)
+        try {
+            if (!canEnrich)
+                throw new Error("skip");
+            const pressables = await getPressableElements({ device: targetDeviceName });
+            if (pressables.success && pressables.parsedElements && pressables.parsedElements.length > 0) {
+                const screenshotScale = result.scaleFactor || 1;
+                pressablesText = pressables.parsedElements.map((el) => {
+                    // See enrichScreenshotWithLayout: shift y when fiber reports the element
+                    // inside the safe-area band (a react-native-screens modal artifact).
+                    let centerYPoints = el.center.y;
+                    if (safeAreaTop > 0 && centerYPoints < safeAreaTop) {
+                        centerYPoints += safeAreaTop;
+                    }
+                    const px = Math.round((el.center.x * scaleFactor) / screenshotScale);
+                    const py = Math.round((centerYPoints * scaleFactor) / screenshotScale);
+                    const label = el.accessibilityLabel || el.text || el.testID || (el.intent ? `${el.intent} icon` : el.component);
+                    const idPart = el.testID ? ` testID="${el.testID}"` : "";
+                    const kindPart = el.isInput ? " [input]" : "";
+                    const wrapPart = el.isWrapper ? " [wrapper — skip]" : "";
+                    const nearPart = !el.text && !el.accessibilityLabel && el.nearbyText ? ` near "${el.nearbyText}"` : "";
+                    return `  (${px}, ${py}) ${el.component}: "${label}"${nearPart}${idPart}${kindPart}${wrapPart}`;
+                }).join("\n");
+            }
+        }
+        catch {
+            // Non-fatal: screenshot works without pressables enrichment
+        }
+        let infoText = `Screenshot captured (${pixelWidth}x${pixelHeight} pixels)`;
+        infoText += `\n📱 iOS screen: ${pointWidth}x${pointHeight} points (${scaleFactor}x scale)`;
+        infoText += `\n📐 tap() handles pixel-to-point conversion automatically — pass pixel coords from this image directly`;
+        infoText += `\n⚠️ Status bar + safe area: ${safeAreaTop} points (${safeAreaOffsetPixels} pixels) from top`;
+        if (result.scaleFactor && result.scaleFactor > 1) {
+            infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
+        }
+        if (pressablesText) {
+            infoText += `\n\n🎯 Pressable elements (ready-to-tap, coordinates in screenshot pixels):`;
+            infoText += `\n${pressablesText}`;
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — when text is exact and unique`;
+            infoText += `\n  • tap(testID="id") or tap(component="Name") — when you know the identifier`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — use coordinates from the pressable elements list above (reliable for icons and ambiguous elements)`;
+            infoText += `\n  • get_screen_layout — full component tree when you need more than pressables`;
+        }
+        else {
+            if (!canEnrich && connectedApps.size > 0) {
+                infoText += `\n\nℹ️ Pressable enrichment skipped: no RN app is connected to simulator ${resolvedUdid}.`;
+                infoText += ` ${connectedApps.size} other app(s) are connected on different device(s) — their fiber data was intentionally not used to avoid mismatched output.`;
+            }
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
+            infoText += `\n  • get_screen_layout — get full UI tree with real on-screen positions`;
+        }
+        // Check for LogBox overlay — only on the matching RN app; skip otherwise
+        // to avoid surfacing warnings from a different simulator's app.
+        if (canEnrich) {
+            try {
+                const logBoxState = await detectLogBox(targetDeviceName);
+                if (logBoxState && logBoxState.total > 0) {
+                    infoText += formatLogBoxWarning(logBoxState);
+                }
+            }
+            catch {
+                // Non-fatal: LogBox detection failure should not break screenshot
+            }
+        }
+        imageBuffer.add({
+            id: `ios-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            image: result.data,
+            timestamp: Date.now(),
+            source: "ios_screenshot",
+            metadata: {
+                width: result.originalWidth || 0,
+                height: result.originalHeight || 0,
+                scaleFactor: result.scaleFactor || 1,
+                platform: "ios",
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: infoText
+                },
+                {
+                    type: "image",
+                    data: result.data.toString("base64"),
+                    mimeType: "image/jpeg"
+                }
+            ]
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Screenshot saved to: ${result.result}`
+            }
+        ]
+    };
+});
+// Tool: Android screenshot
+registerToolWithTelemetry("android_screenshot", {
+    description: "Take a screenshot from an Android device/emulator. Returns the image plus two lists: (1) pressable elements — the tappable components on screen with ready-to-use pixel tap coordinates, testIDs, and labels; (2) screen layout — all visible React components for context. Prefer tap(text=\"...\") when text is exact and unique; otherwise use tap(x, y) with coordinates from the pressables list — this is the most reliable way to tap icons or visually-identified elements. Use component names from the layout for inspect_component/find_components.\n" +
+        "PURPOSE: Snapshot what the user sees on Android AND get tap-ready pressables + a structured component map in one call.\n" +
+        "WHEN TO USE: Any visual verification, before/after comparison, or as the starting point for tapping UI by coordinates on Android.\n" +
+        "WORKFLOW: android_screenshot -> pick element from pressables -> tap(x, y) or tap(testID=...) -> android_screenshot to verify.\n" +
+        "LIMITATIONS: Requires adb in PATH and a running device/emulator. For non-RN surfaces (system dialogs, permission prompts), combine with tap(..., native=true).\n" +
+        "GOOD: android_screenshot()\n" +
+        "BAD: android_screenshot({ deviceId: \"guess\" }) with a made-up serial — run list_android_devices first.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full device-interaction playbook.",
+    inputSchema: {
+        outputPath: z
+            .string()
+            .optional()
+            .describe("Optional path to save the screenshot. If not provided, saves to temp directory."),
+        deviceId: z
+            .string()
+            .optional()
+            .describe("Optional device ID (from list_android_devices). Uses first available device if not specified.")
+    }
+}, async ({ outputPath, deviceId }) => {
+    const result = await androidScreenshot(outputPath, deviceId);
+    if (!result.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${result.error}`
+                }
+            ],
+            isError: true
+        };
+    }
+    // Include image data if available
+    if (result.data) {
+        // Build info text with coordinate conversion guidance
+        const pixelWidth = result.originalWidth || 0;
+        const pixelHeight = result.originalHeight || 0;
+        // Resolve the RN app running on THIS Android device so enrichment
+        // pulls data from the right app (not whichever app is "first").
+        const targetApp = getConnectedAppByAndroidDeviceId(deviceId);
+        const targetDeviceName = targetApp?.deviceInfo.deviceName;
+        // Store screenshot metadata on the matching app (not an arbitrary one)
+        if (targetApp) {
+            targetApp.lastScreenshot = {
+                originalWidth: pixelWidth,
+                originalHeight: pixelHeight,
+                scaleFactor: result.scaleFactor || 1,
+            };
+        }
+        let infoText = `Screenshot captured (${pixelWidth}x${pixelHeight} pixels)`;
+        // Get status bar height for coordinate guidance
+        let statusBarPixels = 63; // Default fallback
+        let statusBarDp = 24;
+        let densityDpi = 440; // Common default
+        try {
+            const statusBarResult = await androidGetStatusBarHeight(deviceId);
+            if (statusBarResult.success && statusBarResult.heightPixels) {
+                statusBarPixels = statusBarResult.heightPixels;
+                statusBarDp = statusBarResult.heightDp || 24;
+            }
+            const densityResult = await androidGetDensity(deviceId);
+            if (densityResult.success && densityResult.density) {
+                densityDpi = densityResult.density;
+            }
+        }
+        catch {
+            // Use defaults
+        }
+        // Enrich with screen layout data (component names + tap coordinates)
+        // Android: density ratio = densityDpi / 160 (160dpi = 1dp = 1px baseline)
+        const androidPixelRatio = densityDpi / 160;
+        // Skip enrichment when no RN app is connected to this Android device —
+        // otherwise we would pull fiber data from a different device's app.
+        const canEnrich = !!targetApp;
+        let pressablesText = null;
+        // Screen Layout tree previously appended here was dropped — it was noisy
+        // (nested Svg/G/Path duplicates). Use get_screen_layout when the tree is needed.
+        // Enrich with pressable elements (filtered list of tappable components, converted to screenshot pixel coords)
+        try {
+            if (!canEnrich)
+                throw new Error("skip");
+            const pressables = await getPressableElements({ device: targetDeviceName });
+            if (pressables.success && pressables.parsedElements && pressables.parsedElements.length > 0) {
+                const screenshotScale = result.scaleFactor || 1;
+                pressablesText = pressables.parsedElements.map((el) => {
+                    const px = Math.round((el.center.x * androidPixelRatio) / screenshotScale);
+                    const py = Math.round((el.center.y * androidPixelRatio) / screenshotScale);
+                    const label = el.accessibilityLabel || el.text || el.testID || (el.intent ? `${el.intent} icon` : el.component);
+                    const idPart = el.testID ? ` testID="${el.testID}"` : "";
+                    const kindPart = el.isInput ? " [input]" : "";
+                    const wrapPart = el.isWrapper ? " [wrapper — skip]" : "";
+                    const nearPart = !el.text && !el.accessibilityLabel && el.nearbyText ? ` near "${el.nearbyText}"` : "";
+                    return `  (${px}, ${py}) ${el.component}: "${label}"${nearPart}${idPart}${kindPart}${wrapPart}`;
+                }).join("\n");
+            }
+        }
+        catch {
+            // Non-fatal: screenshot works without pressables enrichment
+        }
+        infoText += `\n📱 Android uses PIXELS for all coordinates`;
+        if (result.scaleFactor && result.scaleFactor > 1) {
+            infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
+            infoText += `\n📐 tap() handles coordinate conversion automatically — pass pixel coords from this image directly`;
+        }
+        else {
+            infoText += `\n📐 Screenshot coords = tap coords (no conversion needed)`;
+        }
+        infoText += `\n⚠️ Status bar: ${statusBarPixels}px (${statusBarDp}dp) from top - app content starts below this`;
+        infoText += `\n📊 Display density: ${densityDpi}dpi`;
+        if (pressablesText) {
+            infoText += `\n\n🎯 Pressable elements (ready-to-tap, coordinates in screenshot pixels):`;
+            infoText += `\n${pressablesText}`;
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — when text is exact and unique`;
+            infoText += `\n  • tap(testID="id") or tap(component="Name") — when you know the identifier`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — use coordinates from the pressable elements list above (reliable for icons and ambiguous elements)`;
+            infoText += `\n  • get_screen_layout — full component tree when you need more than pressables`;
+        }
+        else {
+            if (!canEnrich && connectedApps.size > 0) {
+                infoText += `\n\nℹ️ Pressable enrichment skipped: no RN app is connected to device ${deviceId ?? "(default)"}.`;
+                infoText += ` ${connectedApps.size} other app(s) are connected on different device(s) — their fiber data was intentionally not used to avoid mismatched output.`;
+            }
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
+            infoText += `\n  • get_screen_layout — get full UI tree with real on-screen positions`;
+        }
+        // Check for LogBox overlay — only on the matching RN app; skip otherwise
+        // to avoid surfacing warnings from a different device's app.
+        if (canEnrich) {
+            try {
+                const logBoxState = await detectLogBox(targetDeviceName);
+                if (logBoxState && logBoxState.total > 0) {
+                    infoText += formatLogBoxWarning(logBoxState);
+                }
+            }
+            catch {
+                // Non-fatal: LogBox detection failure should not break screenshot
+            }
+        }
+        imageBuffer.add({
+            id: `android-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            image: result.data,
+            timestamp: Date.now(),
+            source: "android_screenshot",
+            metadata: {
+                width: result.originalWidth || 0,
+                height: result.originalHeight || 0,
+                scaleFactor: result.scaleFactor || 1,
+                platform: "android",
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: infoText
+                },
+                {
+                    type: "image",
+                    data: result.data.toString("base64"),
+                    mimeType: "image/jpeg"
+                }
+            ]
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Screenshot saved to: ${result.result}`
+            }
+        ]
+    };
+});
+// Tool: Get connection status (detailed health and gap tracking)
+registerToolWithTelemetry("get_connection_status", {
+    description: "Get detailed connection health status including uptime, recent disconnects/reconnects, and connection gaps that may indicate missing data.\n" +
+        "PURPOSE: Diagnose flaky CDP sessions — quantify uptime, count reconnects, and expose gaps where logs/network data could be missing.\n" +
+        "WHEN TO USE: When logs look suspiciously empty, tools complain about disconnect/reconnect, or the app was suspended and resumed.\n" +
+        "WORKFLOW: get_connection_status -> if unhealthy: disconnect_metro -> scan_metro to rebuild a clean session.\n" +
+        "LIMITATIONS: Reports only MCP-side view; doesn't know why Metro dropped the socket (simulator sleep, app backgrounded, etc).\n" +
+        "GOOD: get_connection_status() after noticing stale data.\n" +
+        "BAD: Polling get_connection_status as a heartbeat — use ensure_connection(healthCheck=true) for a live probe.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
+    inputSchema: {}
+}, async () => {
+    const connections = getConnectedApps();
+    const states = getAllConnectionStates();
+    const metadata = getAllConnectionMetadata();
+    const lines = [];
+    lines.push("=== Connection Status ===\n");
+    if (connections.length === 0 && states.size === 0) {
+        lines.push("No connections established. Run scan_metro to connect.");
+        return {
+            content: [{ type: "text", text: lines.join("\n") }]
+        };
+    }
+    // Show active connections
+    for (const { key, app, isConnected } of connections) {
+        const state = states.get(key);
+        const contextHealth = getContextHealth(key);
+        lines.push(`--- ${app.deviceInfo.title} (Port ${app.port}) ---`);
+        lines.push(`  Status: ${isConnected ? "CONNECTED" : "DISCONNECTED"}`);
+        if (state) {
+            if (state.lastConnectedTime) {
+                const uptime = Date.now() - state.lastConnectedTime.getTime();
+                lines.push(`  Connected since: ${state.lastConnectedTime.toLocaleTimeString()}`);
+                lines.push(`  Uptime: ${formatDuration(uptime)}`);
+            }
+            if (state.status === "reconnecting") {
+                lines.push(`  Reconnecting: Attempt ${state.reconnectionAttempts}`);
+            }
+            // Show recent gaps (last 5 minutes)
+            if (state.connectionGaps.length > 0) {
+                const recentGaps = state.connectionGaps.filter((g) => Date.now() - g.disconnectedAt.getTime() < 300000);
+                if (recentGaps.length > 0) {
+                    lines.push(`  Recent gaps: ${recentGaps.length}`);
+                    for (const gap of recentGaps.slice(-3)) {
+                        const duration = gap.durationMs ? formatDuration(gap.durationMs) : "ongoing";
+                        lines.push(`    - ${gap.disconnectedAt.toLocaleTimeString()} (${duration}): ${gap.reason}`);
+                    }
+                }
+            }
+        }
+        // Show context health
+        if (contextHealth) {
+            lines.push(`  Context Health:`);
+            lines.push(`    Context ID: ${contextHealth.contextId ?? "unknown"}`);
+            lines.push(`    Status: ${contextHealth.isStale ? "STALE" : "HEALTHY"}`);
+            if (contextHealth.lastHealthCheck) {
+                const healthResult = contextHealth.lastHealthCheckSuccess ? "PASS" : "FAIL";
+                lines.push(`    Last Check: ${contextHealth.lastHealthCheck.toLocaleTimeString()} (${healthResult})`);
+            }
+            if (contextHealth.lastContextCreated) {
+                lines.push(`    Context Created: ${contextHealth.lastContextCreated.toLocaleTimeString()}`);
+            }
+            if (contextHealth.lastContextDestroyed) {
+                lines.push(`    Context Destroyed: ${contextHealth.lastContextDestroyed.toLocaleTimeString()}`);
+            }
+        }
+        lines.push("");
+    }
+    // Show disconnected/reconnecting states without active connections
+    for (const [key, state] of states.entries()) {
+        if (!connections.find((c) => c.key === key)) {
+            const meta = metadata.get(key);
+            lines.push(`--- ${meta?.deviceInfo.title || key} (Disconnected) ---`);
+            lines.push(`  Status: ${state.status.toUpperCase()}`);
+            if (state.lastDisconnectTime) {
+                lines.push(`  Disconnected at: ${state.lastDisconnectTime.toLocaleTimeString()}`);
+            }
+            if (state.reconnectionAttempts > 0) {
+                lines.push(`  Reconnection attempts: ${state.reconnectionAttempts}`);
+            }
+            lines.push("");
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }]
+    };
+});
+// Tool: License status
+registerToolWithTelemetry("get_license_status", {
+    description: "Get your installation ID and license status. Shows your unique Installation ID (needed to activate Pro in the dashboard), current license tier, and cache validity.",
+    inputSchema: {},
+}, async () => {
+    const status = getLicenseStatus();
+    const lines = [];
+    lines.push(`Installation ID: ${status.installationId}`);
+    lines.push(`License: ${status.tier.charAt(0).toUpperCase() + status.tier.slice(1)}`);
+    if (status.plan) {
+        lines.push(`Plan expires: ${status.plan.expiresAt}`);
+    }
+    lines.push(`Cache valid until: ${status.cacheExpiresAt}`);
+    // Usage limits
+    const usage = getUsageInfo();
+    if (usage) {
+        lines.push("");
+        lines.push("--- Usage ---");
+        if (usage.creditsRemaining !== null) {
+            lines.push(`Credits remaining: ${usage.creditsRemaining.toLocaleString()}`);
+            lines.push(`Used this month: ${usage.used.toLocaleString()}`);
+        }
+        else {
+            lines.push(`Monthly usage: ${usage.used} / ${usage.limit}`);
+        }
+        lines.push(`Month: ${usage.monthKey}`);
+        if (usage.promotionalPeriod) {
+            const endsAt = usage.promotionalPeriodEndsAt
+                ? new Date(usage.promotionalPeriodEndsAt).toLocaleDateString("en-GB", { day: "2-digit", month: "2-digit", year: "numeric" })
+                : "unknown";
+            lines.push(`Status: Active (promotional period — no limits until ${endsAt})`);
+        }
+        else {
+            lines.push(`Status: ${usage.canUse ? "Active" : "Limit reached"}`);
+        }
+    }
+    if (status.tier === "free") {
+        const dashboardUrl = getDashboardUrl();
+        lines.push("");
+        if (dashboardUrl) {
+            lines.push(`Link your account: ${dashboardUrl}/link?id=${status.installationId}`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// Tool: Send feedback / bug report / feature request
+registerToolWithTelemetry("send_feedback", {
+    description: "Create a feedback report (bug, feature request, or general feedback) for the react-native-ai-devtools team. " +
+        "Auto-collects environment info. Returns a pre-filled GitHub issue URL and formatted issue body. " +
+        "Ask the user to open the URL and paste the body to submit.",
+    inputSchema: {
+        type: z.enum(["feedback", "feature_request", "bug"]).describe('Type of feedback: "feedback", "feature_request", or "bug"'),
+        title: z.string().describe("Short summary (becomes the GitHub issue title)"),
+        description: z.string().describe("Detailed description of the feedback, feature request, or bug"),
+        workflow_context: z.string().optional().describe("What the user was trying to accomplish when they decided to give feedback")
+    }
+}, async ({ type, title, description, workflow_context }) => {
+    // Collect environment info
+    const serverVersion = getServerVersion();
+    const platform = process.platform;
+    const deviceType = getTargetPlatform();
+    const licenseStatus = getLicenseStatus();
+    const env = {
+        serverVersion,
+        platform,
+        deviceType,
+        licenseTier: licenseStatus.tier
+    };
+    const input = { type, title, description, workflowContext: workflow_context };
+    const issueBody = formatIssueBody(input, env);
+    const githubUrl = buildGitHubUrl(title, type);
+    const output = [
+        "## Feedback Report Ready",
+        "",
+        `**GitHub Issue URL:** ${githubUrl}`,
+        "",
+        "**Issue body to paste:**",
+        "",
+        "```markdown",
+        issueBody,
+        "```",
+        "",
+        "Please ask the user to:",
+        "1. Open the GitHub URL above",
+        "2. Paste the issue body into the description field",
+        "3. Review and submit the issue"
+    ].join("\n");
+    return {
+        content: [{ type: "text", text: output }]
+    };
+});
+// Tool: Clear logs
+registerToolWithTelemetry("clear_logs", {
+    description: "Clear the log buffer.\n" +
+        "PURPOSE: Empty the in-memory console buffer (and the SDK buffer if installed) so the next get_logs / search_logs only sees fresh entries.\n" +
+        "WHEN TO USE: Before reproducing a bug so the resulting logs are isolated; between test iterations to avoid noise from earlier runs.\n" +
+        "WORKFLOW: clear_logs -> reproduce the issue (tap / navigate / reload_app) -> get_logs or search_logs.\n" +
+        "GOOD: clear_logs() right before tap(text=\"Submit\")\n" +
+        "BAD: clear_logs() AFTER the repro — you just deleted the evidence.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"logs\") for the full console-debugging playbook.",
+    inputSchema: {
+        device: z.string().optional().describe("Target device name (substring match). Omit to clear all devices. Run get_apps to see connected devices.")
+    }
+}, async ({ device }) => {
+    if (device) {
+        const app = getConnectedAppByDevice(device);
         if (!app)
             throw new Error(`No connected device matches "${device}"`);
         const deviceName = app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
@@ -1107,7 +1731,11 @@ registerToolWithTelemetry("clear_logs", {
 });
 // Tool: Connect to specific Metro port
 registerToolWithTelemetry("connect_metro", {
-    description: "Connect to a Metro server on a specific port. Use this when you know the exact port, otherwise use scan_metro which auto-detects. Establishes the WebSocket connection needed for debugging tools.",
+    description: "Connect to a Metro server on a specific port.\n" +
+        "[DEPRECATED IN PRACTICE — prefer `scan_metro` which auto-discovers all common ports and connects every Bridgeless target at once. Use `connect_metro` only when you need to target a specific non-default port]\n" +
+        "PURPOSE: Establish a CDP WebSocket connection to a single Metro server on a known, non-default port.\n" +
+        "WHEN TO USE: Only when the Metro bundler is running on a port outside the common 8081/8082/19000-19002 range that `scan_metro` already covers — otherwise always prefer `scan_metro`.\n" +
+        "SEE ALSO: call scan_metro for auto-discovery; call get_apps afterwards to confirm the device attached.",
     inputSchema: {
         port: z.coerce.number().default(8081).describe("Metro server port (default: 8081)")
     }
@@ -1164,7 +1792,14 @@ registerToolWithTelemetry("connect_metro", {
 });
 // Tool: Disconnect from Metro
 registerToolWithTelemetry("disconnect_metro", {
-    description: "Disconnect from Metro servers and stop auto-reconnection. Without device param: disconnects ALL devices. With device param: disconnects only the matching device. Use this to remove stale connections or free the CDP slot for the built-in debugger. Log and network buffers are preserved. Reconnect later with scan_metro.",
+    description: "Disconnect from Metro servers and stop auto-reconnection. Without device param: disconnects ALL devices. With device param: disconnects only the matching device. Use this to remove stale connections or free the CDP slot for the built-in debugger. Log and network buffers are preserved. Reconnect later with scan_metro.\n" +
+        "PURPOSE: Cleanly release CDP slots so another debugger (Flipper, React DevTools, Chrome) can attach, or nuke a stale connection the MCP keeps reviving.\n" +
+        "WHEN TO USE: Before launching a native debugger, when connections keep flapping, or after a simulator/device restart left zombie targets.\n" +
+        "WORKFLOW: disconnect_metro -> attach other debugger / restart app -> scan_metro to reconnect.\n" +
+        "LIMITATIONS: Suppresses auto-reconnect until scan_metro or connect_metro is called again; buffers persist but won't receive new events.\n" +
+        "GOOD: disconnect_metro(); disconnect_metro({ device: \"iPhone\" })\n" +
+        "BAD: Using disconnect_metro to clear logs — use clear_logs instead; disconnect breaks capture.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match) to disconnect. Omit to disconnect all devices. Run get_apps to see connected devices.")
     }
@@ -1253,7 +1888,8 @@ registerToolWithTelemetry("execute_in_app", {
         "- NO emoji or non-ASCII characters in string literals — causes parse errors\n" +
         "- Keep expressions simple and synchronous when possible\n\n" +
         "GOOD examples: `__DEV__`, `__APOLLO_CLIENT__.cache.extract()`, `__EXPO_ROUTER__.navigate('/settings')`\n" +
-        "BAD examples: `async () => { await fetch(...) }`, `require('react-native')`, `console.log('\\u{1F600}')`",
+        "BAD examples: `async () => { await fetch(...) }`, `require('react-native')`, `console.log('\\u{1F600}')`\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"state\") for the full app-state playbook.",
     inputSchema: {
         expression: z
             .string()
@@ -1321,7 +1957,14 @@ registerToolWithTelemetry("execute_in_app", {
 });
 // Tool: List debug globals available in the app
 registerToolWithTelemetry("list_debug_globals", {
-    description: "List globally available debugging objects in the connected React Native app (Apollo Client, Redux store, React DevTools, etc.). Use this to discover what state management and debugging tools are available.",
+    description: "List globally available debugging objects in the connected React Native app (Apollo Client, Redux store, React DevTools, etc.). Use this to discover what state management and debugging tools are available.\n" +
+        "PURPOSE: Enumerate the app's `globalThis.*` surface so you know which stores, clients, and debug hooks you can drill into.\n" +
+        "WHEN TO USE: Start of a state-debugging session, or when you don't know whether the app exposes a Redux/Apollo/Zustand handle.\n" +
+        "WORKFLOW: list_debug_globals -> inspect_global(objectName=\"...\") -> execute_in_app for reads/mutations.\n" +
+        "LIMITATIONS: Only sees variables explicitly assigned to a global (e.g., `globalThis.store = store`). Module-scoped state is invisible — expose it first.\n" +
+        "GOOD: list_debug_globals()\n" +
+        "BAD: Calling before scan_metro — needs a live connection.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"state\") for the full app-state playbook.",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
@@ -1349,7 +1992,14 @@ registerToolWithTelemetry("list_debug_globals", {
 });
 // Tool: Inspect a global object to see its properties and types
 registerToolWithTelemetry("inspect_global", {
-    description: "Inspect a global object to see its properties, types, and whether they are callable functions. Use this BEFORE calling methods on unfamiliar objects to avoid errors.",
+    description: "Inspect a global object to see its properties, types, and whether they are callable functions. Use this BEFORE calling methods on unfamiliar objects to avoid errors.\n" +
+        "PURPOSE: Surface the shape of a global (Apollo client, Redux store, Expo Router, etc.) — keys, types, and which members are callable — without executing arbitrary code.\n" +
+        "WHEN TO USE: After list_debug_globals identifies a promising global and before you try execute_in_app on it.\n" +
+        "WORKFLOW: list_debug_globals -> inspect_global(objectName=\"__APOLLO_CLIENT__\") -> execute_in_app(\"__APOLLO_CLIENT__.cache.extract()\").\n" +
+        "LIMITATIONS: Only reads one level deep; nested objects show as `[object Object]` — re-inspect the child path with execute_in_app. Throws ReferenceError for globals that don't exist.\n" +
+        "GOOD: inspect_global({ objectName: \"__APOLLO_CLIENT__\" })\n" +
+        "BAD: inspect_global({ objectName: \"store.state\" }) — path expressions aren't supported; use execute_in_app for property chains.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"state\") for the full app-state playbook.",
     inputSchema: {
         objectName: z
             .string()
@@ -1389,7 +2039,14 @@ registerToolWithTelemetry("inspect_global", {
 // ============================================================================
 // Tool: Get the React component tree
 registerToolWithTelemetry("get_component_tree", {
-    description: "Get the full React component tree from the running app. Shows the complete fiber hierarchy including providers, navigation wrappers, and internal components. For a screen overview with positions and text, use get_screen_layout instead. Use structureOnly=true for compact names-only output.",
+    description: "Get the full React component tree from the running app. Shows the complete fiber hierarchy including providers, navigation wrappers, and internal components. For a screen overview with positions and text, use get_screen_layout instead. Use structureOnly=true for compact names-only output.\n" +
+        "PURPOSE: Expose the entire fiber tree — including providers, navigators, and off-screen subtrees — when get_screen_layout's visible-only view isn't enough.\n" +
+        "WHEN TO USE: Debugging context propagation, navigation wrappers, hidden modals, or when you need to understand the full React architecture.\n" +
+        "WORKFLOW: get_component_tree(structureOnly=true) for overview -> find_components for targeted lookup -> inspect_component for props/state.\n" +
+        "LIMITATIONS: Full trees can be large; always start with structureOnly=true. Ignores non-React native views. Minified builds return display names that may be opaque.\n" +
+        "GOOD: get_component_tree({ structureOnly: true })\n" +
+        "BAD: get_component_tree({ includeProps: true, includeStyles: true }) on a large app — likely hits response-size limits. Prefer inspect_component for specific nodes.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"inspect\") for the full component-inspect playbook.",
     inputSchema: {
         structureOnly: z
             .boolean()
@@ -1452,54 +2109,17 @@ registerToolWithTelemetry("get_component_tree", {
         ]
     };
 });
-// Tool: Get full screen layout (all components with layout styles)
-registerToolWithTelemetry("get_screen_layout", {
-    description: "Get a screen map showing visible components as an indented tree with actual screen positions. Uses measureInWindow for real coordinates and filters out off-screen components. Returns meaningful component names with text content and frame data (x,y width x height). Coordinates are in **points** (iOS) or **dp** (Android) — NOT screenshot pixels. Use tap(text=...) or tap(testID=...) to interact with discovered components. Use extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.).",
-    inputSchema: {
-        extended: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Include layout styles (padding, margin, flex, backgroundColor, borderRadius, etc.) for each component. Default: false for compact output."),
-        summary: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Return only component counts by name instead of full tree (default: false)"),
-        device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
-    }
-}, async ({ extended, summary, device }) => {
-    if (!hasMetro()) {
-        const hint = await metroMissingHintIfAbsent("get_screen_layout");
-        return {
-            content: [{ type: "text", text: `Screen Layout unavailable.${hint}` }],
-            isError: true
-        };
-    }
-    const result = await getScreenLayout({ extended, summary, device });
-    if (!result.success) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${result.error}`
-                }
-            ],
-            isError: true
-        };
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Screen Layout:\n\n${result.result}`
-            }
-        ]
-    };
-});
 // Tool: Get all pressable elements on screen
 registerToolWithTelemetry("get_pressable_elements", {
-    description: "Find all pressable (onPress) and input (TextInput) elements currently visible on screen. Returns component names, ready-to-tap center coordinates in SCREENSHOT PIXELS (same space as ios_screenshot/android_screenshot — pass directly to tap(x, y)), text labels, testID, accessibilityLabel, and a spatial nearbyText hint for icon-only buttons. Each element includes hasLabel (true if it contains text) and isInput (true for TextInput fields).",
+    description: "Find all pressable (onPress) and input (TextInput) elements currently visible on screen. Returns component names, ready-to-tap center coordinates in SCREENSHOT PIXELS (same space as ios_screenshot/android_screenshot — pass directly to tap(x, y)), text labels, testID, accessibilityLabel, and a spatial nearbyText hint for icon-only buttons. Each element includes hasLabel (true if it contains text) and isInput (true for TextInput fields).\n" +
+        "HELPER — call before `tap` when you need to enumerate candidate elements before committing to a target; not a replacement for tap itself.\n" +
+        "PURPOSE: Produce a ready-to-tap inventory of every interactive element on screen with screenshot-pixel coordinates that tap(x, y) accepts directly.\n" +
+        "WHEN TO USE: Before tapping icon-only buttons, when text-based tap keeps failing, or to enumerate what the user can actually interact with.\n" +
+        "WORKFLOW: ios_screenshot / android_screenshot -> get_pressable_elements -> tap(testID=\"...\") or tap(x, y) using the center coordinates.\n" +
+        "LIMITATIONS: Visible-only (off-screen pressables are excluded). Requires a live React connection. Coordinates are in screenshot pixels — the tap tool converts to points internally.\n" +
+        "GOOD: get_pressable_elements()\n" +
+        "BAD: Calling when tap(testID=\"...\") already works — testID matching is faster and more stable.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full interaction playbook.",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
@@ -1642,7 +2262,15 @@ function formatPressablesInPixels(elements, opts) {
 }
 // Tool: Inspect a specific component by name
 registerToolWithTelemetry("inspect_component", {
-    description: "Inspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_screen_layout or find_components to identify which component to inspect. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go.",
+    description: "Inspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_screen_layout or find_components to identify which component to inspect. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go." +
+        primaryInteractionBanner() + "\n" +
+        "PURPOSE: Reveal a mounted component's live props, hook state, and (optionally) child subtree so you can reason about why it renders the way it does.\n" +
+        "WHEN TO USE: User asks \"why is this button disabled\", \"what props does X receive\", or you need to confirm state changed after a tap.\n" +
+        "WORKFLOW: get_screen_layout or find_components -> inspect_component(componentName=\"Foo\") -> tap or execute_in_app to change state -> inspect_component again.\n" +
+        "LIMITATIONS: Requires the component to be currently mounted in the fiber tree. Name matching is exact; use find_components for fuzzy/regex lookup.\n" +
+        "GOOD: inspect_component({ componentName: \"SneakerCard\", index: 0 })\n" +
+        "BAD: inspect_component({ componentName: \"Card\" }) when many Card instances exist — pass index or narrow via find_components.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"inspect\") for the full component-inspect playbook.",
     inputSchema: {
         componentName: z
             .string()
@@ -1703,7 +2331,15 @@ registerToolWithTelemetry("inspect_component", {
 });
 // Tool: Find components matching a pattern
 registerToolWithTelemetry("find_components", {
-    description: "Find components matching a name pattern. **TARGETED SEARCH**: Use after get_screen_layout or get_component_tree(structureOnly=true) to find specific components by pattern. Use includeLayout=true to get padding/margin/flex styles.",
+    description: "Find components matching a name pattern. **TARGETED SEARCH**: Use after get_screen_layout or get_component_tree(structureOnly=true) to find specific components by pattern. Use includeLayout=true to get padding/margin/flex styles." +
+        primaryInteractionBanner() + "\n" +
+        "PURPOSE: Fast regex search over the entire fiber tree — including off-screen and wrapper components — to locate every instance of a component by name.\n" +
+        "WHEN TO USE: You know roughly what the component is called (e.g., \"Button\", \"Screen$\") but not where it lives, or you need counts/paths before drilling in with inspect_component.\n" +
+        "WORKFLOW: get_screen_layout (orient) -> find_components(pattern=\"...\") -> inspect_component(componentName=\"...\", index=N).\n" +
+        "LIMITATIONS: Matches the React display name only; minified builds may return opaque names. Large result sets — use maxResults or a tighter pattern.\n" +
+        "GOOD: find_components({ pattern: \"Button\" }); find_components({ pattern: \"Screen$\" })\n" +
+        "BAD: find_components({ pattern: \".*\" }) — floods the response; narrow the regex.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"inspect\") for the full component-inspect playbook.",
     inputSchema: {
         pattern: z
             .string()
@@ -1732,153 +2368,29 @@ registerToolWithTelemetry("find_components", {
     if (!result.success) {
         return {
             content: [
-                {
-                    type: "text",
-                    text: `Error: ${result.error}`
-                }
-            ],
-            isError: true
-        };
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Find Components (pattern: "${pattern}"):\n\n${result.result}`
-            }
-        ]
-    };
-});
-// Tool: Unified tap — tries fiber, accessibility, OCR, coordinate strategies
-registerToolWithTelemetry("tap", {
-    description: "Tap a UI element. Automatically tries multiple strategies: fiber tree (React), accessibility tree (native), and OCR (visual). " +
-        "Auto-detects platform (iOS/Android). For coordinates, pass raw pixel values from screenshot — tap handles all coordinate conversion internally (iOS pixel-to-point, scale factor adjustments).\n\n" +
-        "PREREQUISITE: For iOS, an iOS UI driver must be installed — AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion). Without it, accessibility and coordinate strategies will fail.\n\n" +
-        "IMPORTANT: When both iOS and Android devices are connected, specify platform explicitly to avoid tapping on the wrong device.\n\n" +
-        "Examples:\n" +
-        "- tap(text=\"Submit\") — finds and taps element with matching text\n" +
-        "- tap(testID=\"login-btn\") — finds by testID\n" +
-        "- tap(component=\"HamburgerIcon\") — finds by React component name\n" +
-        "- tap(x=300, y=600) — taps at pixel coordinates; use coordinates from the pressable elements list returned by ios_screenshot/android_screenshot for reliable icon and ambiguous-element taps\n" +
-        "- tap(text=\"Menu\", strategy=\"ocr\") — forces OCR strategy only\n" +
-        "- tap(x=300, y=600, native=true, platform=\"android\") — taps directly via ADB/simctl without React Native connection\n\n" +
-        "Returns a post-tap screenshot by default (set screenshot=false to disable). " +
-        "For coordinate/accessibility/OCR taps, automatically verifies the tap had a visual effect via before/after screenshot diff (set verify=false to disable).",
-    inputSchema: {
-        text: z
-            .string()
-            .optional()
-            .describe("Visible text to match (case-insensitive substring). ASCII only for fiber strategy; OCR handles non-ASCII."),
-        testID: z
-            .string()
-            .optional()
-            .describe("Exact match on the element's testID prop."),
-        component: z
-            .string()
-            .optional()
-            .describe("Component name match (case-insensitive substring, e.g. 'Button', 'MenuItem')."),
-        index: z.coerce
-            .number()
-            .optional()
-            .describe("Zero-based index when multiple elements match (default: 0)."),
-        x: z.coerce
-            .number()
-            .optional()
-            .describe("X coordinate in pixels (from screenshot). Must provide both x and y."),
-        y: z.coerce
-            .number()
-            .optional()
-            .describe("Y coordinate in pixels (from screenshot). Must provide both x and y."),
-        strategy: z
-            .enum(["auto", "fiber", "accessibility", "ocr", "coordinate"])
-            .optional()
-            .default("auto")
-            .describe('"auto" (default) tries fiber -> accessibility -> OCR. Set explicitly to skip strategies you know will fail.'),
-        maxTraversalDepth: z.coerce
-            .number()
-            .optional()
-            .describe("Max parent levels to traverse when searching by component name (default: 15). " +
-            "Increase if your component is deeply wrapped (e.g. inside multiple HOCs/animation wrappers)."),
-        native: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, tap coordinates directly via ADB/simctl without requiring a React Native connection. " +
-            "Useful for interacting with native UI, system dialogs, or non-RN apps. Requires x/y coordinates."),
-        platform: z
-            .enum(["ios", "android"])
-            .optional()
-            .describe("Target platform. Required when both iOS and Android devices are connected. Auto-detected if only one platform is available."),
-        screenshot: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Capture and return a post-tap screenshot. Enabled by default. Set to false for fastest execution (no screenshots)."),
-        verify: z
-            .boolean()
-            .optional()
-            .describe("Run before/after screenshot diff to detect if the tap had a meaningful visual effect. " +
-            "Default: true for coordinate/accessibility/ocr strategies, false for fiber. Requires screenshot=true."),
-        burst: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Enable burst screenshot capture for enhanced verification. " +
-            "Captures 4 rapid screenshots (~150ms intervals) after the tap to detect transient visual feedback " +
-            "(press animations, highlights, ripples) that may settle before a standard after-screenshot. " +
-            "Results are stored in the image buffer (use get_images to inspect individual frames). " +
-            "Default: false."),
-    },
-}, async (args) => {
-    const result = await tap({
-        text: args.text,
-        testID: args.testID,
-        component: args.component,
-        index: args.index,
-        x: args.x,
-        y: args.y,
-        strategy: args.strategy,
-        maxTraversalDepth: args.maxTraversalDepth,
-        native: args.native,
-        platform: args.platform,
-        screenshot: args.screenshot,
-        verify: args.verify,
-        burst: args.burst,
-    });
-    const { screenshot: screenshotData, ...resultWithoutScreenshot } = result;
-    const text = JSON.stringify(resultWithoutScreenshot, null, 2);
-    // Pack strategy mode + attempted strategies into errorContext for telemetry
-    // e.g. "s=ocr|fiber:no_pressable|ocr:no_match" or "s=auto|fiber:no_pressable|accessibility:not_found|ocr:no_match"
-    const stratPrefix = args.strategy && args.strategy !== "auto" ? `s=${args.strategy}|` : "";
-    const errorContext = result.attempted?.length
-        ? stratPrefix + result.attempted.map(a => `${a.strategy}:${a.reason.slice(0, 40)}`).join("|")
-        : undefined;
-    const content = [
-        { type: "text", text },
-    ];
-    if (screenshotData) {
-        content.push({
-            type: "image",
-            data: screenshotData.image,
-            mimeType: "image/jpeg",
-        });
+                {
+                    type: "text",
+                    text: `Error: ${result.error}`
+                }
+            ],
+            isError: true
+        };
     }
     return {
-        content,
-        isError: !result.success && !result.ambiguous,
-        _errorMessage: !result.success && !result.ambiguous
-            ? `${JSON.stringify(result.query)}|${result.error || ""}`
-            : undefined,
-        _errorContext: errorContext,
-        _meaningful: result.verification?.meaningful,
-        _changeRate: result.verification?.changeRate,
-        _tapStrategy: result.method,
-        _iosDriver: result.platform === "ios" ? (process.env.IOS_DRIVER?.toLowerCase() || "idb") : undefined,
+        content: [
+            {
+                type: "text",
+                text: `Find Components (pattern: "${pattern}"):\n\n${result.result}`
+            }
+        ]
     };
 });
 // Tool: Toggle Element Inspector programmatically
 registerToolWithTelemetry("toggle_element_inspector", {
-    description: "Toggle React Native's Element Inspector overlay on/off. Rarely needed directly — get_inspector_selection auto-enables the inspector when called with coordinates. Use this only when you need manual control over the overlay visibility.",
+    description: "Toggle React Native's Element Inspector overlay on/off. Rarely needed directly — get_inspector_selection auto-enables the inspector when called with coordinates. Use this only when you need manual control over the overlay visibility.\n" +
+        "PURPOSE: Manual control over the on-device inspector overlay — mostly useful for screenshots that should show the inspector UI or for disabling it after a session.\n" +
+        "WHEN TO USE: Only when get_inspector_selection's auto-enable isn't appropriate (e.g., leaving the overlay on for a user screenshot).\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"inspect\") for the full component-inspect playbook.",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
@@ -1930,7 +2442,14 @@ registerToolWithTelemetry("toggle_element_inspector", {
 });
 // Tool: Get currently selected element from Element Inspector
 registerToolWithTelemetry("get_inspector_selection", {
-    description: "Identify the React component at a screen location by reading RN's Element Inspector. Returns a clean component hierarchy with file paths — ideal for finding the real component name (e.g. HomeScreen > SneakerCard > PulseActionButton). If x/y provided: auto-enables inspector, taps at coordinates, returns hierarchy. If no coordinates: returns current selection. WORKFLOW: Use ios_screenshot or ocr_screenshot to visually identify the target element, then call this tool with coordinates to get the component tree.",
+    description: "Identify the React component at a screen location by reading RN's Element Inspector. Returns a clean component hierarchy with file paths — ideal for finding the real component name (e.g. HomeScreen > SneakerCard > PulseActionButton). If x/y provided: auto-enables inspector, taps at coordinates, returns hierarchy. If no coordinates: returns current selection.\n" +
+        "PURPOSE: Map a screen coordinate to a real component name AND source file path, so you know which file to edit.\n" +
+        "WHEN TO USE: You have a screenshot and want to know \"what component renders this pixel?\" — especially for file-path grounding before making code changes.\n" +
+        "WORKFLOW: ios_screenshot / android_screenshot / ocr_screenshot -> get_inspector_selection(x, y) -> edit the returned source file.\n" +
+        "LIMITATIONS: Requires RN dev mode (inspector only exists in __DEV__). x/y are in points/dp, not screenshot pixels — tap-style coordinates are fine since the tool taps internally. Flaky on Bridgeless if the inspector fails to initialize.\n" +
+        "GOOD: get_inspector_selection({ x: 180, y: 420 })\n" +
+        "BAD: Using it for layout measurements — prefer inspect_at_point which returns the exact frame.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"inspect\") for the full component-inspect playbook.",
     inputSchema: {
         x: z
             .number()
@@ -2033,7 +2552,14 @@ registerToolWithTelemetry("get_inspector_selection", {
 });
 // Tool: Inspect component at coordinates (like Element Inspector)
 registerToolWithTelemetry("inspect_at_point", {
-    description: "Inspect the React component at specific (x, y) coordinates for layout debugging. Returns component props, measured frame (position/size in dp), and component path. Works on both Paper and Fabric. Coordinates are in dp (density-independent pixels). To convert from screenshot pixels: divide by the device pixel ratio (e.g. 540px / 2.625 = 205dp). Best for: checking layout bounds, reading component props/styles, pixel-perfect debugging. For identifying component names: prefer get_inspector_selection which returns a cleaner hierarchy with file paths.",
+    description: "Inspect the React component at specific (x, y) coordinates for layout debugging. Returns component props, measured frame (position/size in dp), and component path. Works on both Paper and Fabric. Coordinates are in dp (density-independent pixels). To convert from screenshot pixels: divide by the device pixel ratio (e.g. 540px / 2.625 = 205dp). Best for: checking layout bounds, reading component props/styles, pixel-perfect debugging. For identifying component names: prefer get_inspector_selection which returns a cleaner hierarchy with file paths.\n" +
+        "PURPOSE: Pixel-precise layout diagnosis — returns the exact measured frame, props, and style of whatever renders at a point.\n" +
+        "WHEN TO USE: Checking why a button is clipped, why an element's hit area is wrong, or reading the actual computed size/position of a component.\n" +
+        "WORKFLOW: ios_screenshot -> find suspect pixel -> convert to dp (pixel / pixelRatio) -> inspect_at_point(x, y).\n" +
+        "LIMITATIONS: Coordinates MUST be in dp, not screenshot pixels — this differs from tap() which accepts either. Wrong unit = wrong component. Requires live React connection.\n" +
+        "GOOD: inspect_at_point({ x: 205, y: 360 }) // dp after dividing\n" +
+        "BAD: inspect_at_point({ x: 540, y: 960 }) // raw screenshot pixels — picks the wrong node.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"inspect\") for the full component-inspect playbook.",
     inputSchema: {
         x: z
             .number()
@@ -2099,7 +2625,14 @@ registerToolWithTelemetry("inspect_at_point", {
 });
 // Tool: Get network requests
 registerToolWithTelemetry("get_network_requests", {
-    description: "Retrieve captured network requests from connected React Native app. Shows URL, method, status, and timing. Note: On Bridgeless targets (Expo SDK 52+) without the SDK, capture may miss early startup requests. Install react-native-ai-devtools-sdk for full capture with headers and response bodies. Tip: Use summary=true first for stats overview.",
+    description: "Retrieve captured network requests from connected React Native app. Shows URL, method, status, and timing. Note: On Bridgeless targets (Expo SDK 52+) without the SDK, capture may miss early startup requests. Install react-native-ai-devtools-sdk for full capture with headers and response bodies. Tip: Use summary=true first for stats overview.\n" +
+        "PURPOSE: Inspect HTTP traffic the app made since connection — URLs, methods, status codes, and timings — to debug API, auth, and caching issues.\n" +
+        "WHEN TO USE: User reports a failed login/load, slow screen, or wrong data. Confirm a request fired, check its status, and pivot to get_request_details for headers/body.\n" +
+        "WORKFLOW: scan_metro -> reproduce action -> get_network_requests({ summary: true }) -> get_network_requests({ status: 500 }) or search_network -> get_request_details(id).\n" +
+        "LIMITATIONS: Bridgeless targets without the SDK may miss pre-connect requests and response bodies — install react-native-ai-devtools-sdk for full fidelity.\n" +
+        "GOOD: get_network_requests({ summary: true }) then get_network_requests({ urlPattern: \"/login\", status: 401 })\n" +
+        "BAD: get_network_requests({ maxRequests: 500 }) as the first call — start with summary=true.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"network\") for the full network-inspect playbook.",
     inputSchema: {
         maxRequests: z
             .number()
@@ -2253,7 +2786,14 @@ registerToolWithTelemetry("get_network_requests", {
     total += b.size; return total === 0; });
 // Tool: Search network requests
 registerToolWithTelemetry("search_network", {
-    description: "Search network requests by URL pattern (case-insensitive)",
+    description: "Search network requests by URL pattern (case-insensitive).\n" +
+        "PURPOSE: Filter the network buffer to requests whose URL matches a substring — fast way to find a specific endpoint in a noisy app.\n" +
+        "WHEN TO USE: You know part of the URL (e.g., \"/graphql\", \"users\", a domain) and want matching requests across all devices.\n" +
+        "WORKFLOW: search_network(urlPattern=\"/api/\") -> get_request_details(requestId=\"...\") for full headers/body.\n" +
+        "LIMITATIONS: Matches URL only; for method/status/body filtering use get_network_requests. Bodies are only present when the SDK is installed.\n" +
+        "GOOD: search_network({ urlPattern: \"/graphql\" })\n" +
+        "BAD: search_network({ urlPattern: \"\" }) — empty pattern matches everything; use get_network_requests instead.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"network\") for the full network-inspect playbook.",
     inputSchema: {
         urlPattern: z.string().describe("URL pattern to search for"),
         maxResults: z.number().optional().default(50).describe("Maximum number of results to return (default: 50)"),
@@ -2323,7 +2863,14 @@ registerToolWithTelemetry("search_network", {
 });
 // Tool: Get request details
 registerToolWithTelemetry("get_request_details", {
-    description: "Get full details of a specific network request including headers, body, and timing. With the SDK installed, includes full request/response bodies. Without SDK, bodies are not available on most targets. Use get_network_requests first to find the request ID.",
+    description: "Get full details of a specific network request including headers, body, and timing. With the SDK installed, includes full request/response bodies. Without SDK, bodies are not available on most targets. Use get_network_requests first to find the request ID.\n" +
+        "PURPOSE: Drill into a single network entry — full request/response headers, body, status, and timing breakdown.\n" +
+        "WHEN TO USE: After get_network_requests or search_network returns a suspect ID and you need the payload to diagnose.\n" +
+        "WORKFLOW: get_network_requests / search_network -> copy id -> get_request_details(requestId).\n" +
+        "LIMITATIONS: Bodies require the react-native-ai-devtools-sdk in the app; on CDP-only targets response bodies are missing. Large bodies are truncated — raise maxBodyLength.\n" +
+        "GOOD: get_request_details({ requestId: \"42\", maxBodyLength: 4000 })\n" +
+        "BAD: Guessing requestIds — always get them from get_network_requests / search_network first.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"network\") for the full network-inspect playbook.",
     inputSchema: {
         requestId: z.string().describe("The request ID to get details for"),
         maxBodyLength: z.coerce
@@ -2412,7 +2959,14 @@ registerToolWithTelemetry("get_request_details", {
 });
 // Tool: Get network stats
 registerToolWithTelemetry("get_network_stats", {
-    description: "Get statistics about captured network requests: counts by method, status code, and domain.",
+    description: "Get statistics about captured network requests: counts by method, status code, and domain.\n" +
+        "PURPOSE: High-level view of traffic shape — totals, error counts, average duration, and top domains — without scanning every request.\n" +
+        "WHEN TO USE: To quickly answer \"is there a spike in 5xx?\", \"which domain is chattiest?\", or to sanity-check capture is working.\n" +
+        "WORKFLOW: get_network_stats -> if errors > 0: get_network_requests(status=\"500\") -> get_request_details.\n" +
+        "LIMITATIONS: Reflects only the buffered window (last 200 entries per device). Resets when clear_network is called.\n" +
+        "GOOD: get_network_stats()\n" +
+        "BAD: Using it to find a specific request — use search_network or get_network_requests.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"network\") for the full network-inspect playbook.",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.")
     }
@@ -2475,7 +3029,14 @@ registerToolWithTelemetry("get_network_stats", {
     total += b.size; return total === 0; });
 // Tool: Clear network requests
 registerToolWithTelemetry("clear_network", {
-    description: "Clear the network request buffer",
+    description: "Clear the network request buffer.\n" +
+        "PURPOSE: Reset the captured request list to isolate new traffic from a specific user action.\n" +
+        "WHEN TO USE: Right before reproducing a bug so the buffer contains only the relevant requests.\n" +
+        "WORKFLOW: clear_network -> trigger action (tap, execute_in_app) -> get_network_requests / search_network.\n" +
+        "LIMITATIONS: Irreversible — cleared requests cannot be recovered. Also clears the SDK's in-app buffer when SDK is present.\n" +
+        "GOOD: clear_network() before a reproduction.\n" +
+        "BAD: Using clear_network as a workaround for stale connections — use scan_metro / ensure_connection instead.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"network\") for the full network-inspect playbook.",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match). Omit to clear all devices. Run get_apps to see connected devices.")
     }
@@ -2512,7 +3073,14 @@ registerToolWithTelemetry("clear_network", {
 });
 // Tool: Get images from shared image buffer
 registerToolWithTelemetry("get_images", {
-    description: "Access the shared image buffer containing screenshots from all tools (ios_screenshot, android_screenshot, ocr_screenshot, tap verification). Returns metadata only by default — use id or groupId+frameIndex to retrieve actual image data. Tap burst verification stores frame groups here when burst=true is used.",
+    description: "Access the shared image buffer containing screenshots from all tools (ios_screenshot, android_screenshot, ocr_screenshot, tap verification). Returns metadata only by default — use id or groupId+frameIndex to retrieve actual image data. Tap burst verification stores frame groups here when burst=true is used.\n" +
+        "PURPOSE: Retrieve prior screenshots — especially tap burst frames — without re-taking them, for visual diffing or reviewing transient UI states.\n" +
+        "WHEN TO USE: After tap(burst=true) reports transientChangeDetected, or to compare before/after frames without another screenshot round-trip.\n" +
+        "WORKFLOW: tap(burst=true) -> note verification.burstGroupId -> get_images(groupId, frameIndex=N) to inspect individual frames.\n" +
+        "LIMITATIONS: Circular buffer (50 entries) — old images are evicted. Metadata is cheap; fetching image data is not — request specific ids, not bulk.\n" +
+        "GOOD: get_images({ list: true }); get_images({ groupId: \"burst-abc\", frameIndex: 2 })\n" +
+        "BAD: get_images() with no filter when buffer is full — floods context. Use list:true or last:N first.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full interaction playbook.",
     inputSchema: {
         list: z.boolean().optional().describe("List all entries and groups (metadata only, no image data)"),
         id: z.string().optional().describe("Retrieve a specific image by ID (returns image data)"),
@@ -2574,7 +3142,9 @@ registerToolWithTelemetry("get_images", {
 });
 // Tool: Reload the app
 registerToolWithTelemetry("reload_app", {
-    description: "Reload the React Native app (triggers JavaScript bundle reload like pressing 'r' in Metro). Will auto-connect to Metro if no connection exists. Note: After reload, the app may take a few seconds to fully restart and become responsive — wait before running other tools. IMPORTANT: React Native has Fast Refresh enabled by default - code changes are automatically applied without needing reload. Only use when: (1) logs/behavior don't reflect code changes after a few seconds, (2) app is in broken/error state, or (3) need to reset app state completely (navigation stack, context, etc.).",
+    description: "Reload the React Native app (triggers JavaScript bundle reload like pressing 'r' in Metro).\n" +
+        "WHEN TO USE: Only after native code / config changes or a broken app state — NOT after JS/TS edits (Fast Refresh handles those in 1-2s).\n" +
+        "Will auto-connect to Metro if no connection exists. Note: After reload, the app may take a few seconds to fully restart and become responsive — wait before running other tools. IMPORTANT: React Native has Fast Refresh enabled by default - code changes are automatically applied without needing reload. Only use when: (1) logs/behavior don't reflect code changes after a few seconds, (2) app is in broken/error state, or (3) need to reset app state completely (navigation stack, context, etc.).",
     inputSchema: {
         device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
@@ -2607,7 +3177,14 @@ registerToolWithTelemetry("logbox", {
         '"push" displays a message in the LogBox error banner (visible to the developer watching the device). ' +
         '"ignore" adds patterns to suppress future LogBox entries for this session. ' +
         '"detect" reads current LogBox state without modifying it. ' +
-        "Only works in __DEV__ mode — LogBox does not exist in production builds.",
+        "Only works in __DEV__ mode — LogBox does not exist in production builds.\n" +
+        "PURPOSE: Control RN's on-device red/yellow overlay — clear it when it blocks UI, suppress noisy repeats, or push a message back to the developer.\n" +
+        "WHEN TO USE: Screenshot/tap reports LogBox is obstructing the screen, an error banner prevents interaction, or you want to surface info to the dev watching the simulator.\n" +
+        "WORKFLOW: logbox(action=\"detect\") -> if present: logbox(action=\"dismiss\") to read + clear -> continue UI work. Use action=\"ignore\" with patterns to stop repeat noise.\n" +
+        "LIMITATIONS: Dev-only — no effect in production builds. \"push\" at level=\"warning\" won't show a banner unless LogBox is already open.\n" +
+        "GOOD: logbox({ action: \"dismiss\" }); logbox({ action: \"ignore\", patterns: [\"[APOLLO]\"] })\n" +
+        "BAD: Spamming logbox(action=\"push\") for every tool step — annoys the developer.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"logs\") for the full logs playbook.",
     inputSchema: {
         action: z.enum(["dismiss", "push", "ignore", "detect"]).describe('Action to perform: "dismiss", "push", "ignore", or "detect"'),
         message: z.string().optional().describe('Message to push into LogBox (required when action="push")'),
@@ -2782,7 +3359,14 @@ registerToolWithTelemetry("logbox", {
 // ============================================================================
 // Tool: Get bundle status
 registerToolWithTelemetry("get_bundle_status", {
-    description: "Get the current Metro bundler status including build state and any recent bundling errors. Use this to check if there are compilation/bundling errors that prevent the app from loading.",
+    description: "Get the current Metro bundler status including build state and any recent bundling errors. Use this to check if there are compilation/bundling errors that prevent the app from loading.\n" +
+        "PURPOSE: Snapshot Metro's current build state (idle / transforming / error) together with any captured errors — a fast \"is the bundler healthy?\" check.\n" +
+        "WHEN TO USE: Before diving into runtime debugging — rules out compile-time failures that would make get_logs and tap pointless.\n" +
+        "WORKFLOW: get_bundle_status -> if errors present: get_bundle_errors for detail -> fix -> clear_bundle_errors.\n" +
+        "LIMITATIONS: Relies on Metro's WebSocket event stream; if Metro isn't running or the connection dropped, status may be stale.\n" +
+        "GOOD: get_bundle_status() at the start of a debug session.\n" +
+        "BAD: Polling every second — Metro events are push-based; just call once and act on the result.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"bundle\") for the full bundle-check playbook.",
     inputSchema: {}
 }, async () => {
     // Get port from first connected app if available
@@ -2800,7 +3384,14 @@ registerToolWithTelemetry("get_bundle_status", {
 });
 // Tool: Get bundle errors
 registerToolWithTelemetry("get_bundle_errors", {
-    description: "Retrieve captured Metro bundling/compilation errors. These are errors that occur during the bundle build process (import resolution, syntax errors, transform errors) that prevent the app from loading. If no errors are captured but Metro is running without connected apps, automatically falls back to screenshot+OCR to capture the error from the device screen.",
+    description: "Retrieve captured Metro bundling/compilation errors. These are errors that occur during the bundle build process (import resolution, syntax errors, transform errors) that prevent the app from loading. If no errors are captured but Metro is running without connected apps, automatically falls back to screenshot+OCR to capture the error from the device screen.\n" +
+        "PURPOSE: Surface Metro's build-time failures (not runtime JS errors) that keep the app from booting or hot-reloading.\n" +
+        "WHEN TO USE: App shows the red error screen, refuses to connect, or Fast Refresh stops working after an edit. Also use when get_logs is silent but the app is clearly broken.\n" +
+        "WORKFLOW: get_bundle_status -> get_bundle_errors -> fix source -> clear_bundle_errors -> reload_app.\n" +
+        "LIMITATIONS: Captures errors Metro emits via its WebSocket; the screenshot+OCR fallback requires a booted simulator and the platform param.\n" +
+        "GOOD: get_bundle_errors({ platform: \"ios\" })\n" +
+        "BAD: Using get_bundle_errors to look for runtime TypeErrors — those live in get_logs, not the bundler.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"bundle\") for the full bundle-check playbook.",
     inputSchema: {
         maxErrors: z.number().optional().default(10).describe("Maximum number of errors to return (default: 10)"),
         platform: z
@@ -2857,283 +3448,122 @@ registerToolWithTelemetry("get_bundle_errors", {
     try {
         let screenshotResult;
         if (platform === "android") {
-            screenshotResult = await androidScreenshot(undefined, deviceId);
-        }
-        else {
-            screenshotResult = await iosScreenshot(undefined, deviceId);
-        }
-        if (!screenshotResult.success || !screenshotResult.data) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected (possible bundle error).\n\nScreenshot fallback failed: ${screenshotResult.error || "No image data"}`
-                    }
-                ]
-            };
-        }
-        // Calculate device pixel ratio for iOS
-        const devicePixelRatio = platform === "ios" && screenshotResult.originalWidth && screenshotResult.originalHeight
-            ? inferIOSDevicePixelRatio(screenshotResult.originalWidth, screenshotResult.originalHeight)
-            : 1;
-        // Run OCR on the screenshot
-        const ocrResult = await recognizeText(screenshotResult.data, {
-            scaleFactor: screenshotResult.scaleFactor || 1,
-            platform,
-            devicePixelRatio
-        });
-        if (!ocrResult.success || !ocrResult.fullText) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected.\n\nScreenshot captured but OCR found no text. The screen may not show an error message.`
-                    }
-                ]
-            };
-        }
-        // Parse the OCR text for error information
-        const parsedError = parseErrorScreenText(ocrResult.fullText);
-        if (!parsedError.found || !parsedError.error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected.\n\nScreenshot OCR text:\n${ocrResult.fullText.substring(0, 1000)}${ocrResult.fullText.length > 1000 ? "..." : ""}\n\n(No error pattern detected in text)`
-                    }
-                ]
-            };
-        }
-        // Add the parsed error to the buffer for future reference
-        bundleErrorBuffer.add(parsedError.error);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Bundle Errors (1 captured via screenshot fallback):\n\n${formatParsedError(parsedError)}`
-                }
-            ]
-        };
-    }
-    catch (fallbackError) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected.\n\nScreenshot fallback error: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`
-                }
-            ]
-        };
-    }
-});
-// Tool: Clear bundle errors
-registerToolWithTelemetry("clear_bundle_errors", {
-    description: "Clear the bundle error buffer",
-    inputSchema: {}
-}, async () => {
-    const count = bundleErrorBuffer.clear();
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Cleared ${count} bundle errors from buffer.`
-            }
-        ]
-    };
-});
-// ============================================================================
-// Android Tools
-// ============================================================================
-// Tool: List Android devices
-registerToolWithTelemetry("list_android_devices", {
-    description: "List connected Android devices and emulators via ADB",
-    inputSchema: {}
-}, async () => {
-    const result = await listAndroidDevices();
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: Android screenshot
-registerToolWithTelemetry("android_screenshot", {
-    description: "Take a screenshot from an Android device/emulator. Returns the image plus two lists: (1) pressable elements — the tappable components on screen with ready-to-use pixel tap coordinates, testIDs, and labels; (2) screen layout — all visible React components for context. Prefer tap(text=\"...\") when text is exact and unique; otherwise use tap(x, y) with coordinates from the pressables list — this is the most reliable way to tap icons or visually-identified elements. Use component names from the layout for inspect_component/find_components.",
-    inputSchema: {
-        outputPath: z
-            .string()
-            .optional()
-            .describe("Optional path to save the screenshot. If not provided, saves to temp directory."),
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID (from list_android_devices). Uses first available device if not specified.")
-    }
-}, async ({ outputPath, deviceId }) => {
-    const result = await androidScreenshot(outputPath, deviceId);
-    if (!result.success) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${result.error}`
-                }
-            ],
-            isError: true
-        };
-    }
-    // Include image data if available
-    if (result.data) {
-        // Build info text with coordinate conversion guidance
-        const pixelWidth = result.originalWidth || 0;
-        const pixelHeight = result.originalHeight || 0;
-        // Resolve the RN app running on THIS Android device so enrichment
-        // pulls data from the right app (not whichever app is "first").
-        const targetApp = getConnectedAppByAndroidDeviceId(deviceId);
-        const targetDeviceName = targetApp?.deviceInfo.deviceName;
-        // Store screenshot metadata on the matching app (not an arbitrary one)
-        if (targetApp) {
-            targetApp.lastScreenshot = {
-                originalWidth: pixelWidth,
-                originalHeight: pixelHeight,
-                scaleFactor: result.scaleFactor || 1,
-            };
-        }
-        let infoText = `Screenshot captured (${pixelWidth}x${pixelHeight} pixels)`;
-        // Get status bar height for coordinate guidance
-        let statusBarPixels = 63; // Default fallback
-        let statusBarDp = 24;
-        let densityDpi = 440; // Common default
-        try {
-            const statusBarResult = await androidGetStatusBarHeight(deviceId);
-            if (statusBarResult.success && statusBarResult.heightPixels) {
-                statusBarPixels = statusBarResult.heightPixels;
-                statusBarDp = statusBarResult.heightDp || 24;
-            }
-            const densityResult = await androidGetDensity(deviceId);
-            if (densityResult.success && densityResult.density) {
-                densityDpi = densityResult.density;
-            }
-        }
-        catch {
-            // Use defaults
-        }
-        // Enrich with screen layout data (component names + tap coordinates)
-        // Android: density ratio = densityDpi / 160 (160dpi = 1dp = 1px baseline)
-        const androidPixelRatio = densityDpi / 160;
-        // Skip enrichment when no RN app is connected to this Android device —
-        // otherwise we would pull fiber data from a different device's app.
-        const canEnrich = !!targetApp;
-        let pressablesText = null;
-        // Screen Layout tree previously appended here was dropped — it was noisy
-        // (nested Svg/G/Path duplicates). Use get_screen_layout when the tree is needed.
-        // Enrich with pressable elements (filtered list of tappable components, converted to screenshot pixel coords)
-        try {
-            if (!canEnrich)
-                throw new Error("skip");
-            const pressables = await getPressableElements({ device: targetDeviceName });
-            if (pressables.success && pressables.parsedElements && pressables.parsedElements.length > 0) {
-                const screenshotScale = result.scaleFactor || 1;
-                pressablesText = pressables.parsedElements.map((el) => {
-                    const px = Math.round((el.center.x * androidPixelRatio) / screenshotScale);
-                    const py = Math.round((el.center.y * androidPixelRatio) / screenshotScale);
-                    const label = el.accessibilityLabel || el.text || el.testID || (el.intent ? `${el.intent} icon` : el.component);
-                    const idPart = el.testID ? ` testID="${el.testID}"` : "";
-                    const kindPart = el.isInput ? " [input]" : "";
-                    const wrapPart = el.isWrapper ? " [wrapper — skip]" : "";
-                    const nearPart = !el.text && !el.accessibilityLabel && el.nearbyText ? ` near "${el.nearbyText}"` : "";
-                    return `  (${px}, ${py}) ${el.component}: "${label}"${nearPart}${idPart}${kindPart}${wrapPart}`;
-                }).join("\n");
-            }
-        }
-        catch {
-            // Non-fatal: screenshot works without pressables enrichment
-        }
-        infoText += `\n📱 Android uses PIXELS for all coordinates`;
-        if (result.scaleFactor && result.scaleFactor > 1) {
-            infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
-            infoText += `\n📐 tap() handles coordinate conversion automatically — pass pixel coords from this image directly`;
-        }
-        else {
-            infoText += `\n📐 Screenshot coords = tap coords (no conversion needed)`;
-        }
-        infoText += `\n⚠️ Status bar: ${statusBarPixels}px (${statusBarDp}dp) from top - app content starts below this`;
-        infoText += `\n📊 Display density: ${densityDpi}dpi`;
-        if (pressablesText) {
-            infoText += `\n\n🎯 Pressable elements (ready-to-tap, coordinates in screenshot pixels):`;
-            infoText += `\n${pressablesText}`;
-            infoText += `\n\n💡 Next steps:`;
-            infoText += `\n  • tap(text="Button Label") — when text is exact and unique`;
-            infoText += `\n  • tap(testID="id") or tap(component="Name") — when you know the identifier`;
-            infoText += `\n  • tap(x=<px>, y=<px>) — use coordinates from the pressable elements list above (reliable for icons and ambiguous elements)`;
-            infoText += `\n  • get_screen_layout — full component tree when you need more than pressables`;
-        }
-        else {
-            if (!canEnrich && connectedApps.size > 0) {
-                infoText += `\n\nℹ️ Pressable enrichment skipped: no RN app is connected to device ${deviceId ?? "(default)"}.`;
-                infoText += ` ${connectedApps.size} other app(s) are connected on different device(s) — their fiber data was intentionally not used to avoid mismatched output.`;
-            }
-            infoText += `\n\n💡 Next steps:`;
-            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
-            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
-            infoText += `\n  • android_describe_all — get full UI tree with exact tap coordinates`;
-            infoText += `\n  • android_find_element(text="...") — find element coordinates without tapping`;
-        }
-        // Check for LogBox overlay — only on the matching RN app; skip otherwise
-        // to avoid surfacing warnings from a different device's app.
-        if (canEnrich) {
-            try {
-                const logBoxState = await detectLogBox(targetDeviceName);
-                if (logBoxState && logBoxState.total > 0) {
-                    infoText += formatLogBoxWarning(logBoxState);
-                }
-            }
-            catch {
-                // Non-fatal: LogBox detection failure should not break screenshot
-            }
+            screenshotResult = await androidScreenshot(undefined, deviceId);
         }
-        imageBuffer.add({
-            id: `android-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-            image: result.data,
-            timestamp: Date.now(),
-            source: "android_screenshot",
-            metadata: {
-                width: result.originalWidth || 0,
-                height: result.originalHeight || 0,
-                scaleFactor: result.scaleFactor || 1,
-                platform: "android",
-            },
+        else {
+            screenshotResult = await iosScreenshot(undefined, deviceId);
+        }
+        if (!screenshotResult.success || !screenshotResult.data) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected (possible bundle error).\n\nScreenshot fallback failed: ${screenshotResult.error || "No image data"}`
+                    }
+                ]
+            };
+        }
+        // Calculate device pixel ratio for iOS
+        const devicePixelRatio = platform === "ios" && screenshotResult.originalWidth && screenshotResult.originalHeight
+            ? inferIOSDevicePixelRatio(screenshotResult.originalWidth, screenshotResult.originalHeight)
+            : 1;
+        // Run OCR on the screenshot
+        const ocrResult = await recognizeText(screenshotResult.data, {
+            scaleFactor: screenshotResult.scaleFactor || 1,
+            platform,
+            devicePixelRatio
         });
+        if (!ocrResult.success || !ocrResult.fullText) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected.\n\nScreenshot captured but OCR found no text. The screen may not show an error message.`
+                    }
+                ]
+            };
+        }
+        // Parse the OCR text for error information
+        const parsedError = parseErrorScreenText(ocrResult.fullText);
+        if (!parsedError.found || !parsedError.error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected.\n\nScreenshot OCR text:\n${ocrResult.fullText.substring(0, 1000)}${ocrResult.fullText.length > 1000 ? "..." : ""}\n\n(No error pattern detected in text)`
+                    }
+                ]
+            };
+        }
+        // Add the parsed error to the buffer for future reference
+        bundleErrorBuffer.add(parsedError.error);
         return {
             content: [
                 {
                     type: "text",
-                    text: infoText
-                },
+                    text: `Bundle Errors (1 captured via screenshot fallback):\n\n${formatParsedError(parsedError)}`
+                }
+            ]
+        };
+    }
+    catch (fallbackError) {
+        return {
+            content: [
                 {
-                    type: "image",
-                    data: result.data.toString("base64"),
-                    mimeType: "image/jpeg"
+                    type: "text",
+                    text: `Bundle Errors (0 captured):\n\nNo bundle errors captured via CDP.\n\nMetro is running on port(s) ${metroState.metroPorts.join(", ")} but no apps are connected.\n\nScreenshot fallback error: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`
                 }
             ]
         };
     }
+});
+// Tool: Clear bundle errors
+registerToolWithTelemetry("clear_bundle_errors", {
+    description: "Clear the bundle error buffer.\n" +
+        "PURPOSE: Reset captured Metro build errors after a fix so get_bundle_status/get_bundle_errors reflect the current state.\n" +
+        "WHEN TO USE: After fixing a bundling error and before re-triggering Metro to confirm the error is gone.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"bundle\") for the full bundle-check playbook.",
+    inputSchema: {}
+}, async () => {
+    const count = bundleErrorBuffer.clear();
     return {
         content: [
             {
                 type: "text",
-                text: `Screenshot saved to: ${result.result}`
+                text: `Cleared ${count} bundle errors from buffer.`
             }
         ]
     };
 });
+// ============================================================================
+// Android Tools
+// ============================================================================
+// Tool: List Android devices
+registerToolWithTelemetry("list_android_devices", {
+    description: "List connected Android devices and emulators via ADB.\n" +
+        "PURPOSE: Discover which physical devices and emulators are visible to adb so you can pick a target UDID/serial.\n" +
+        "WHEN TO USE: Before android_install_app / android_launch_app, or when a tool reports \"no device\" and you need to confirm visibility.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
+    inputSchema: {}
+}, async () => {
+    const result = await listAndroidDevices();
+    return {
+        content: [
+            {
+                type: "text",
+                text: result.success ? result.result : `Error: ${result.error}`
+            }
+        ],
+        isError: !result.success
+    };
+});
 // Tool: Android install app
 registerToolWithTelemetry("android_install_app", {
-    description: "Install an APK on an Android device/emulator",
+    description: "Install an APK on an Android device/emulator" +
+        platformUniqueBanner("installing an Android APK") +
+        "\nPURPOSE: Push a built APK to a connected Android device or emulator via adb." +
+        "\nWHEN TO USE: After producing a fresh build, when switching app variants, or when preparing a clean test run." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         apkPath: z.string().describe("Path to the APK file to install"),
         deviceId: z
@@ -3165,7 +3595,11 @@ registerToolWithTelemetry("android_install_app", {
 });
 // Tool: Android launch app
 registerToolWithTelemetry("android_launch_app", {
-    description: "Launch an app on an Android device/emulator by package name",
+    description: "Launch an app on an Android device/emulator by package name" +
+        platformUniqueBanner("launching an Android app by package name") +
+        "\nPURPOSE: Start an installed Android app by its package (and optional activity) so the next tool calls hit a running process." +
+        "\nWHEN TO USE: After android_install_app, after a force-stop, or when the app isn't foregrounded before interaction." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         packageName: z.string().describe("Package name of the app (e.g., com.example.myapp)"),
         activityName: z
@@ -3191,573 +3625,225 @@ registerToolWithTelemetry("android_launch_app", {
 });
 // Tool: Android list packages
 registerToolWithTelemetry("android_list_packages", {
-    description: "List installed packages on an Android device/emulator",
-    inputSchema: {
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified."),
-        filter: z.string().optional().describe("Optional filter to search packages by name (case-insensitive)")
-    }
-}, async ({ deviceId, filter }) => {
-    const result = await androidListPackages(deviceId, filter);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// ============================================================================
-// Android UI Input Tools (Phase 2)
-// ============================================================================
-// Tool: Android long press
-registerToolWithTelemetry("android_long_press", {
-    description: "Long press at specific coordinates on an Android device/emulator screen",
-    inputSchema: {
-        x: z.coerce.number().describe("X coordinate in pixels"),
-        y: z.coerce.number().describe("Y coordinate in pixels"),
-        durationMs: z.number().optional().default(1000).describe("Press duration in milliseconds (default: 1000)"),
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ x, y, durationMs, deviceId }) => {
-    const result = await androidLongPress(x, y, durationMs, deviceId);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: Android swipe
-registerToolWithTelemetry("android_swipe", {
-    description: "Swipe from one point to another on an Android device/emulator screen",
-    inputSchema: {
-        startX: z.coerce.number().describe("Starting X coordinate in pixels"),
-        startY: z.coerce.number().describe("Starting Y coordinate in pixels"),
-        endX: z.coerce.number().describe("Ending X coordinate in pixels"),
-        endY: z.coerce.number().describe("Ending Y coordinate in pixels"),
-        durationMs: z.number().optional().default(300).describe("Swipe duration in milliseconds (default: 300)"),
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ startX, startY, endX, endY, durationMs, deviceId }) => {
-    const result = await androidSwipe(startX, startY, endX, endY, durationMs, deviceId);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: Android input text
-registerToolWithTelemetry("android_input_text", {
-    description: "Type text on an Android device/emulator. The text will be input at the current focus point (tap an input field first).",
-    inputSchema: {
-        text: z.string().describe("Text to type"),
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ text, deviceId }) => {
-    const result = await androidInputText(text, deviceId);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: Android key event
-registerToolWithTelemetry("android_key_event", {
-    description: `Send a key event to an Android device/emulator. Common keys: ${Object.keys(ANDROID_KEY_EVENTS).join(", ")}`,
-    inputSchema: {
-        key: z.string().describe(`Key name (${Object.keys(ANDROID_KEY_EVENTS).join(", ")}) or numeric keycode`),
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ key, deviceId }) => {
-    // Try to parse as number first, otherwise treat as key name
-    const keyCode = /^\d+$/.test(key) ? parseInt(key, 10) : key.toUpperCase();
-    const result = await androidKeyEvent(keyCode, deviceId);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: Android get screen size
-registerToolWithTelemetry("android_get_screen_size", {
-    description: "Get the screen size (resolution) of an Android device/emulator",
-    inputSchema: {
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ deviceId }) => {
-    const result = await androidGetScreenSize(deviceId);
-    if (!result.success) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${result.error}`
-                }
-            ],
-            isError: true
-        };
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Screen size: ${result.width}x${result.height} pixels`
-            }
-        ]
-    };
-});
-// ============================================================================
-// Android Accessibility Tools (UI Hierarchy)
-// ============================================================================
-// Tool: Android describe all (UI hierarchy)
-server.registerTool("android_describe_all", {
-    description: "Get the full UI accessibility tree from the Android device using uiautomator. Returns a hierarchical view of all UI elements with their text, content-description, resource-id, bounds, and tap coordinates.",
+    description: "List installed packages on an Android device/emulator" +
+        platformUniqueBanner("listing installed Android packages") +
+        "\nPURPOSE: Enumerate package names visible to adb so you can confirm installation or pick the right target for android_launch_app." +
+        "\nWHEN TO USE: Before android_launch_app when you don't know the exact package name, or to verify an install succeeded." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         deviceId: z
             .string()
             .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ deviceId }) => {
-    const result = await androidDescribeAll(deviceId);
-    let text = result.success ? result.formatted : `Error: ${result.error}`;
-    // Check for LogBox overlay
-    if (result.success) {
-        try {
-            const logBoxState = await detectLogBox();
-            if (logBoxState && logBoxState.total > 0) {
-                text += formatLogBoxWarning(logBoxState);
-            }
-        }
-        catch {
-            // Non-fatal: LogBox detection failure should not break describe_all
-        }
+            .describe("Optional device ID. Uses first available device if not specified."),
+        filter: z.string().optional().describe("Optional filter to search packages by name (case-insensitive)")
     }
+}, async ({ deviceId, filter }) => {
+    const result = await androidListPackages(deviceId, filter);
     return {
         content: [
             {
                 type: "text",
-                text
+                text: result.success ? result.result : `Error: ${result.error}`
             }
         ],
         isError: !result.success
     };
 });
-// Tool: Android describe point
-server.registerTool("android_describe_point", {
-    description: "Get UI element info at specific coordinates on an Android device. Returns the element's text, content-description, resource-id, bounds, and state flags.",
+// ============================================================================
+// Android UI Input Tools (Phase 2)
+// ============================================================================
+// Tool: Android long press
+registerToolWithTelemetry("android_long_press", {
+    description: "Long press at specific coordinates on an Android device/emulator screen" +
+        platformFallbackBanner("`tap` for short taps; keep android_long_press for long-press gestures specifically") +
+        "\nPURPOSE: Emit a sustained touch at raw pixel coordinates to trigger long-press handlers (context menus, drag starts, multi-select)." +
+        "\nWHEN TO USE: Only when a long-press gesture is required — regular taps should go through `tap`." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook.",
     inputSchema: {
         x: z.coerce.number().describe("X coordinate in pixels"),
         y: z.coerce.number().describe("Y coordinate in pixels"),
+        durationMs: z.number().optional().default(1000).describe("Press duration in milliseconds (default: 1000)"),
         deviceId: z
             .string()
             .optional()
             .describe("Optional device ID. Uses first available device if not specified.")
     }
-}, async ({ x, y, deviceId }) => {
-    const result = await androidDescribePoint(x, y, deviceId);
+}, async ({ x, y, durationMs, deviceId }) => {
+    const result = await androidLongPress(x, y, durationMs, deviceId);
     return {
         content: [
             {
                 type: "text",
-                text: result.success ? result.formatted : `Error: ${result.error}`
+                text: result.success ? result.result : `Error: ${result.error}`
             }
         ],
         isError: !result.success
     };
 });
-// Tool: Android find element (no screenshot needed)
-server.registerTool("android_find_element", {
-    description: "Find a UI element on Android screen by text, content description, or resource ID. Returns element details including tap coordinates. Use this to check if an element exists without tapping it. Workflow: 1) wait_for_element, 2) find_element, 3) tap with returned coordinates. Prefer this over screenshots for button taps.",
-    inputSchema: {
-        text: z.string().optional().describe("Exact text match for the element"),
-        textContains: z.string().optional().describe("Partial text match (case-insensitive)"),
-        contentDesc: z.string().optional().describe("Exact content-description match"),
-        contentDescContains: z.string().optional().describe("Partial content-description match (case-insensitive)"),
-        resourceId: z
-            .string()
-            .optional()
-            .describe("Resource ID match (e.g., 'com.app:id/button' or just 'button')"),
-        index: z
-            .number()
-            .optional()
-            .describe("If multiple elements match, select the nth one (0-indexed, default: 0)"),
-        deviceId: z
-            .string()
-            .optional()
-            .describe("Optional device ID. Uses first available device if not specified.")
-    }
-}, async ({ text, textContains, contentDesc, contentDescContains, resourceId, index, deviceId }) => {
-    const result = await androidFindElement({ text, textContains, contentDesc, contentDescContains, resourceId, index }, deviceId);
-    if (!result.success) {
-        return {
-            content: [{ type: "text", text: `Error: ${result.error}` }],
-            isError: true
-        };
-    }
-    if (!result.found) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: result.error || "Element not found"
-                }
-            ]
-        };
-    }
-    const el = result.element;
-    const info = [
-        `Found element (${result.matchCount} match${result.matchCount > 1 ? "es" : ""})`,
-        `  Text: "${el.text}"`,
-        `  Content-desc: "${el.contentDesc}"`,
-        `  Resource ID: "${el.resourceId}"`,
-        `  Class: ${el.className}`,
-        `  Bounds: [${el.bounds.left},${el.bounds.top}][${el.bounds.right},${el.bounds.bottom}]`,
-        `  Center (tap coords): (${el.center.x}, ${el.center.y})`,
-        `  Clickable: ${el.clickable}, Enabled: ${el.enabled}`
-    ].join("\n");
-    return {
-        content: [{ type: "text", text: info }]
-    };
-});
-// Tool: Android wait for element
-server.registerTool("android_wait_for_element", {
-    description: "Wait for a UI element to appear on Android screen. Polls the accessibility tree until the element is found or timeout is reached. Use this FIRST after navigation to ensure screen is ready, then use find_element + tap.",
+// Tool: Android swipe
+registerToolWithTelemetry("android_swipe", {
+    description: "Swipe from one point to another on an Android device/emulator screen" +
+        platformFallbackBanner("`tap` for targeted interactions; keep android_swipe for raw-coordinate gestures") +
+        "\nPURPOSE: Perform a raw-coordinate swipe gesture for scrolling, paging, dismissing sheets, or drawer opens on Android." +
+        "\nWHEN TO USE: When you need a gesture rather than a tap — scroll lists, swipe carousels, or pull-to-refresh." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook.",
     inputSchema: {
-        text: z.string().optional().describe("Exact text match for the element"),
-        textContains: z.string().optional().describe("Partial text match (case-insensitive)"),
-        contentDesc: z.string().optional().describe("Exact content-description match"),
-        contentDescContains: z.string().optional().describe("Partial content-description match (case-insensitive)"),
-        resourceId: z
-            .string()
-            .optional()
-            .describe("Resource ID match (e.g., 'com.app:id/button' or just 'button')"),
-        index: z
-            .number()
-            .optional()
-            .describe("If multiple elements match, select the nth one (0-indexed, default: 0)"),
-        timeoutMs: z
-            .number()
-            .optional()
-            .default(10000)
-            .describe("Maximum time to wait in milliseconds (default: 10000)"),
-        pollIntervalMs: z
-            .number()
-            .optional()
-            .default(500)
-            .describe("Time between polls in milliseconds (default: 500)"),
+        startX: z.coerce.number().describe("Starting X coordinate in pixels"),
+        startY: z.coerce.number().describe("Starting Y coordinate in pixels"),
+        endX: z.coerce.number().describe("Ending X coordinate in pixels"),
+        endY: z.coerce.number().describe("Ending Y coordinate in pixels"),
+        durationMs: z.number().optional().default(300).describe("Swipe duration in milliseconds (default: 300)"),
         deviceId: z
             .string()
             .optional()
             .describe("Optional device ID. Uses first available device if not specified.")
     }
-}, async ({ text, textContains, contentDesc, contentDescContains, resourceId, index, timeoutMs, pollIntervalMs, deviceId }) => {
-    const result = await androidWaitForElement({
-        text,
-        textContains,
-        contentDesc,
-        contentDescContains,
-        resourceId,
-        index,
-        timeoutMs,
-        pollIntervalMs
-    }, deviceId);
-    if (!result.success) {
-        return {
-            content: [{ type: "text", text: `Error: ${result.error}` }],
-            isError: true
-        };
-    }
-    if (!result.found) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: result.timedOut
-                        ? `Timed out after ${result.elapsedMs}ms - element not found`
-                        : result.error || "Element not found"
-                }
-            ]
-        };
-    }
-    const el = result.element;
-    const info = [
-        `Element found after ${result.elapsedMs}ms`,
-        `  Text: "${el.text}"`,
-        `  Content-desc: "${el.contentDesc}"`,
-        `  Resource ID: "${el.resourceId}"`,
-        `  Center (tap coords): (${el.center.x}, ${el.center.y})`,
-        `  Clickable: ${el.clickable}, Enabled: ${el.enabled}`
-    ].join("\n");
-    return {
-        content: [{ type: "text", text: info }]
-    };
-});
-// ============================================================================
-// iOS Simulator Tools
-// ============================================================================
-// Tool: List iOS simulators
-registerToolWithTelemetry("list_ios_simulators", {
-    description: "List available iOS simulators",
-    inputSchema: {
-        onlyBooted: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Only show currently running simulators (default: false)")
-    }
-}, async ({ onlyBooted }) => {
-    const result = await listIOSSimulators(onlyBooted);
+}, async ({ startX, startY, endX, endY, durationMs, deviceId }) => {
+    const result = await androidSwipe(startX, startY, endX, endY, durationMs, deviceId);
     return {
         content: [
             {
                 type: "text",
                 text: result.success ? result.result : `Error: ${result.error}`
             }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: iOS screenshot
-registerToolWithTelemetry("ios_screenshot", {
-    description: "Take a screenshot from an iOS simulator. Returns the image plus two lists: (1) pressable elements — the tappable components on screen with ready-to-use pixel tap coordinates, testIDs, and labels; (2) screen layout — all visible React components for context. Prefer tap(text=\"...\") when text is exact and unique; otherwise use tap(x, y) with coordinates from the pressables list — this is the most reliable way to tap icons or visually-identified elements. Use component names from the layout for inspect_component/find_components.",
-    inputSchema: {
-        outputPath: z
-            .string()
-            .optional()
-            .describe("Optional path to save the screenshot. If not provided, saves to temp directory."),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID (from list_ios_simulators). Uses booted simulator if not specified.")
-    }
-}, async ({ outputPath, udid }) => {
-    const result = await iosScreenshot(outputPath, udid);
-    if (!result.success) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${result.error}`
-                }
-            ],
-            isError: true
-        };
-    }
-    // Include image data if available
-    if (result.data) {
-        // Build info text with coordinate guidance for iOS
-        const pixelWidth = result.originalWidth || 0;
-        const pixelHeight = result.originalHeight || 0;
-        // Resolve the RN app running on THIS simulator so enrichment pulls
-        // fiber/layout data from the right app (not the first-connected one,
-        // which may belong to a different simulator).
-        const resolvedUdid = udid || (await getActiveOrBootedSimulatorUdid());
-        const targetApp = resolvedUdid ? getConnectedAppBySimulatorUdid(resolvedUdid) : null;
-        const targetDeviceName = targetApp?.deviceInfo.deviceName;
-        // Store screenshot metadata on the matching app (not an arbitrary one)
-        if (targetApp) {
-            targetApp.lastScreenshot = {
-                originalWidth: pixelWidth,
-                originalHeight: pixelHeight,
-                scaleFactor: result.scaleFactor || 1,
-            };
-        }
-        // Try to get actual screen dimensions and safe area from accessibility tree
-        let pointWidth = 0;
-        let pointHeight = 0;
-        let scaleFactor = 3; // Default to 3x for modern iPhones
-        let safeAreaTop = 59; // Default safe area offset
-        try {
-            const describeResult = await iosDescribeAll(udid);
-            if (describeResult.success && describeResult.elements && describeResult.elements.length > 0) {
-                // First element is typically the Application with full screen frame
-                const rootElement = describeResult.elements[0];
-                // Try parsed frame first, then parse AXFrame string
-                if (rootElement.frame) {
-                    pointWidth = Math.round(rootElement.frame.width);
-                    pointHeight = Math.round(rootElement.frame.height);
-                    // The frame.y of the root element indicates where content starts (after status bar)
-                    if (rootElement.frame.y > 0) {
-                        safeAreaTop = Math.round(rootElement.frame.y);
-                    }
-                }
-                else if (rootElement.AXFrame) {
-                    // Parse format: "{{x, y}, {width, height}}"
-                    const match = rootElement.AXFrame.match(/\{\{([\d.]+),\s*([\d.]+)\},\s*\{([\d.]+),\s*([\d.]+)\}\}/);
-                    if (match) {
-                        const frameY = parseFloat(match[2]);
-                        pointWidth = Math.round(parseFloat(match[3]));
-                        pointHeight = Math.round(parseFloat(match[4]));
-                        if (frameY > 0) {
-                            safeAreaTop = Math.round(frameY);
-                        }
-                    }
-                }
-                // Calculate actual scale factor
-                if (pointWidth > 0) {
-                    scaleFactor = Math.round(pixelWidth / pointWidth);
-                }
-            }
-        }
-        catch {
-            // Fallback: use 3x scale for modern devices
-        }
-        // Fallback if we couldn't get dimensions
-        if (pointWidth === 0) {
-            pointWidth = Math.round(pixelWidth / scaleFactor);
-            pointHeight = Math.round(pixelHeight / scaleFactor);
-        }
-        const safeAreaOffsetPixels = safeAreaTop * scaleFactor;
-        // The Screen Layout tree was previously appended here but produced huge noisy
-        // output (nested Svg/G/Path duplicates). Agents should use get_screen_layout
-        // explicitly when they need the tree. The Pressable elements block below is
-        // the signal most consumers actually want.
-        let pressablesText = null;
-        const canEnrich = !!targetApp;
-        // Enrich with pressable elements (filtered list of tappable components, converted to screenshot pixel coords)
-        try {
-            if (!canEnrich)
-                throw new Error("skip");
-            const pressables = await getPressableElements({ device: targetDeviceName });
-            if (pressables.success && pressables.parsedElements && pressables.parsedElements.length > 0) {
-                const screenshotScale = result.scaleFactor || 1;
-                pressablesText = pressables.parsedElements.map((el) => {
-                    // See enrichScreenshotWithLayout: shift y when fiber reports the element
-                    // inside the safe-area band (a react-native-screens modal artifact).
-                    let centerYPoints = el.center.y;
-                    if (safeAreaTop > 0 && centerYPoints < safeAreaTop) {
-                        centerYPoints += safeAreaTop;
-                    }
-                    const px = Math.round((el.center.x * scaleFactor) / screenshotScale);
-                    const py = Math.round((centerYPoints * scaleFactor) / screenshotScale);
-                    const label = el.accessibilityLabel || el.text || el.testID || (el.intent ? `${el.intent} icon` : el.component);
-                    const idPart = el.testID ? ` testID="${el.testID}"` : "";
-                    const kindPart = el.isInput ? " [input]" : "";
-                    const wrapPart = el.isWrapper ? " [wrapper — skip]" : "";
-                    const nearPart = !el.text && !el.accessibilityLabel && el.nearbyText ? ` near "${el.nearbyText}"` : "";
-                    return `  (${px}, ${py}) ${el.component}: "${label}"${nearPart}${idPart}${kindPart}${wrapPart}`;
-                }).join("\n");
-            }
-        }
-        catch {
-            // Non-fatal: screenshot works without pressables enrichment
-        }
-        let infoText = `Screenshot captured (${pixelWidth}x${pixelHeight} pixels)`;
-        infoText += `\n📱 iOS screen: ${pointWidth}x${pointHeight} points (${scaleFactor}x scale)`;
-        infoText += `\n📐 tap() handles pixel-to-point conversion automatically — pass pixel coords from this image directly`;
-        infoText += `\n⚠️ Status bar + safe area: ${safeAreaTop} points (${safeAreaOffsetPixels} pixels) from top`;
-        if (result.scaleFactor && result.scaleFactor > 1) {
-            infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
-        }
-        if (pressablesText) {
-            infoText += `\n\n🎯 Pressable elements (ready-to-tap, coordinates in screenshot pixels):`;
-            infoText += `\n${pressablesText}`;
-            infoText += `\n\n💡 Next steps:`;
-            infoText += `\n  • tap(text="Button Label") — when text is exact and unique`;
-            infoText += `\n  • tap(testID="id") or tap(component="Name") — when you know the identifier`;
-            infoText += `\n  • tap(x=<px>, y=<px>) — use coordinates from the pressable elements list above (reliable for icons and ambiguous elements)`;
-            infoText += `\n  • get_screen_layout — full component tree when you need more than pressables`;
-        }
-        else {
-            if (!canEnrich && connectedApps.size > 0) {
-                infoText += `\n\nℹ️ Pressable enrichment skipped: no RN app is connected to simulator ${resolvedUdid}.`;
-                infoText += ` ${connectedApps.size} other app(s) are connected on different device(s) — their fiber data was intentionally not used to avoid mismatched output.`;
-            }
-            infoText += `\n\n💡 Next steps:`;
-            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
-            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
-            infoText += `\n  • ios_describe_all — get full UI tree with exact tap coordinates`;
-            infoText += `\n  • ios_find_element(label="...") — find element coordinates without tapping`;
-        }
-        // Check for LogBox overlay — only on the matching RN app; skip otherwise
-        // to avoid surfacing warnings from a different simulator's app.
-        if (canEnrich) {
-            try {
-                const logBoxState = await detectLogBox(targetDeviceName);
-                if (logBoxState && logBoxState.total > 0) {
-                    infoText += formatLogBoxWarning(logBoxState);
-                }
+        ],
+        isError: !result.success
+    };
+});
+// Tool: Android input text
+registerToolWithTelemetry("android_input_text", {
+    description: "Type text on an Android device/emulator." +
+        platformFallbackBanner("`tap(text=...)` — it auto-focuses TextInput via the fiber tree") +
+        " The text will be input at the current focus point (tap an input field first)." +
+        "\nPURPOSE: Send keystrokes to whichever input currently has focus on Android — the tool does NOT focus a field itself." +
+        "\nWHEN TO USE: Only after an input is already focused, or when `tap(text=...)` on the input didn't take focus for some reason." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook.",
+    inputSchema: {
+        text: z.string().describe("Text to type"),
+        deviceId: z
+            .string()
+            .optional()
+            .describe("Optional device ID. Uses first available device if not specified.")
+    }
+}, async ({ text, deviceId }) => {
+    const result = await androidInputText(text, deviceId);
+    return {
+        content: [
+            {
+                type: "text",
+                text: result.success ? result.result : `Error: ${result.error}`
             }
-            catch {
-                // Non-fatal: LogBox detection failure should not break screenshot
+        ],
+        isError: !result.success
+    };
+});
+// Tool: Android key event
+registerToolWithTelemetry("android_key_event", {
+    description: "Send a key event to an Android device/emulator." +
+        platformUniqueBanner("sending Android key events (BACK, HOME, MENU, etc.)") +
+        ` Common keys: ${Object.keys(ANDROID_KEY_EVENTS).join(", ")}` +
+        "\nPURPOSE: Dispatch Android system keys (BACK, HOME, MENU, ENTER, DEL, etc.) that aren't reachable via on-screen tap." +
+        "\nWHEN TO USE: Navigate back from a screen, submit a form with ENTER, dismiss the keyboard, or press hardware-style keys during a flow." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook.",
+    inputSchema: {
+        key: z.string().describe(`Key name (${Object.keys(ANDROID_KEY_EVENTS).join(", ")}) or numeric keycode`),
+        deviceId: z
+            .string()
+            .optional()
+            .describe("Optional device ID. Uses first available device if not specified.")
+    }
+}, async ({ key, deviceId }) => {
+    // Try to parse as number first, otherwise treat as key name
+    const keyCode = /^\d+$/.test(key) ? parseInt(key, 10) : key.toUpperCase();
+    const result = await androidKeyEvent(keyCode, deviceId);
+    return {
+        content: [
+            {
+                type: "text",
+                text: result.success ? result.result : `Error: ${result.error}`
             }
-        }
-        imageBuffer.add({
-            id: `ios-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-            image: result.data,
-            timestamp: Date.now(),
-            source: "ios_screenshot",
-            metadata: {
-                width: result.originalWidth || 0,
-                height: result.originalHeight || 0,
-                scaleFactor: result.scaleFactor || 1,
-                platform: "ios",
-            },
-        });
+        ],
+        isError: !result.success
+    };
+});
+// Tool: Android get screen size
+registerToolWithTelemetry("android_get_screen_size", {
+    description: "Get the screen size (resolution) of an Android device/emulator" +
+        platformUniqueBanner("reading Android device pixel resolution") +
+        "\nPURPOSE: Return the device's pixel width and height so you can compute safe tap/swipe coordinates." +
+        "\nWHEN TO USE: Before scripting raw-coordinate gestures on an unfamiliar device, or when normalizing coordinates across devices." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook.",
+    inputSchema: {
+        deviceId: z
+            .string()
+            .optional()
+            .describe("Optional device ID. Uses first available device if not specified.")
+    }
+}, async ({ deviceId }) => {
+    const result = await androidGetScreenSize(deviceId);
+    if (!result.success) {
         return {
             content: [
                 {
                     type: "text",
-                    text: infoText
-                },
-                {
-                    type: "image",
-                    data: result.data.toString("base64"),
-                    mimeType: "image/jpeg"
+                    text: `Error: ${result.error}`
                 }
-            ]
+            ],
+            isError: true
         };
     }
     return {
         content: [
             {
                 type: "text",
-                text: `Screenshot saved to: ${result.result}`
+                text: `Screen size: ${result.width}x${result.height} pixels`
             }
         ]
     };
 });
+// ============================================================================
+// Android Accessibility Tools (UI Hierarchy)
+// ============================================================================
+// ============================================================================
+// iOS Simulator Tools
+// ============================================================================
+// Tool: List iOS simulators
+registerToolWithTelemetry("list_ios_simulators", {
+    description: "List available iOS simulators.\n" +
+        "PURPOSE: Enumerate installed iOS simulators with their UDIDs and boot state so you can boot or install into the right one.\n" +
+        "WHEN TO USE: Before ios_boot_simulator / ios_install_app, or when you need a UDID for a specific device name.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
+    inputSchema: {
+        onlyBooted: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Only show currently running simulators (default: false)")
+    }
+}, async ({ onlyBooted }) => {
+    const result = await listIOSSimulators(onlyBooted);
+    return {
+        content: [
+            {
+                type: "text",
+                text: result.success ? result.result : `Error: ${result.error}`
+            }
+        ],
+        isError: !result.success
+    };
+});
 // Tool: OCR Screenshot - Extract text with coordinates from screenshot
 registerToolWithTelemetry("ocr_screenshot", {
     description: "RECOMMENDED: Use this tool FIRST when you need to find and tap UI elements. Takes a screenshot and extracts all visible text with tap-ready coordinates using OCR. " +
         "ADVANTAGES over accessibility trees: (1) Works on ANY visible text regardless of accessibility labels, (2) Returns ready-to-use tapX/tapY coordinates - no conversion needed, (3) Faster than parsing accessibility hierarchies, (4) Works consistently across iOS and Android. " +
-        "USE THIS FOR: Finding buttons, labels, menu items, tab bars, or any text you need to tap. Simply find the text in the results and use its tapX/tapY with the tap command.",
+        "USE THIS FOR: Finding buttons, labels, menu items, tab bars, or any text you need to tap. Simply find the text in the results and use its tapX/tapY with the tap command.\n" +
+        "PURPOSE: Visually locate text on screen and return coordinates safe to pass straight into tap.\n" +
+        "WHEN TO USE: Non-RN surfaces, third-party WebViews, accessibility-poor screens, or when fiber/testID strategies have failed.\n" +
+        "WORKFLOW: ocr_screenshot(platform=\"ios\") -> scan results for the label -> tap(x=tapX, y=tapY) -> ios_screenshot to verify.\n" +
+        "LIMITATIONS: OCR accuracy degrades on very small or stylized text; icons with no label won't appear — use tap(component=...) instead.\n" +
+        "GOOD: ocr_screenshot({ platform: \"ios\" })\n" +
+        "BAD: ocr_screenshot used just to view the screen — plain ios_screenshot / android_screenshot is cheaper when you don't need OCR text.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full device-interaction playbook.",
     inputSchema: {
         platform: z.enum(["ios", "android"]).describe("Platform to capture screenshot from"),
         deviceId: z
@@ -3874,7 +3960,11 @@ registerToolWithTelemetry("ocr_screenshot", {
 });
 // Tool: iOS install app
 registerToolWithTelemetry("ios_install_app", {
-    description: "Install an app bundle (.app) on an iOS simulator",
+    description: "Install an app bundle (.app) on an iOS simulator" +
+        platformUniqueBanner("installing an iOS .app/.ipa bundle") +
+        "\nPURPOSE: Deploy a built .app bundle onto a booted iOS simulator via simctl." +
+        "\nWHEN TO USE: After producing a fresh simulator build, when switching app variants, or when preparing a clean test run." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         appPath: z.string().describe("Path to the .app bundle to install"),
         udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
@@ -3893,7 +3983,11 @@ registerToolWithTelemetry("ios_install_app", {
 });
 // Tool: iOS launch app
 registerToolWithTelemetry("ios_launch_app", {
-    description: "Launch an app on an iOS simulator by bundle ID",
+    description: "Launch an app on an iOS simulator by bundle ID" +
+        platformUniqueBanner("launching an iOS app by bundle ID") +
+        "\nPURPOSE: Start an installed iOS app by its bundle ID so the next tool calls hit a running process." +
+        "\nWHEN TO USE: After ios_install_app, after ios_terminate_app, or when the app isn't foregrounded before interaction." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         bundleId: z.string().describe("Bundle ID of the app (e.g., com.example.myapp)"),
         udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
@@ -3912,7 +4006,14 @@ registerToolWithTelemetry("ios_launch_app", {
 });
 // Tool: iOS open URL
 registerToolWithTelemetry("ios_open_url", {
-    description: "Open a URL in the iOS simulator (opens in default handler or Safari)",
+    description: "Open a URL in the iOS simulator (opens in default handler or Safari).\n" +
+        "PURPOSE: Drive an iOS simulator into a deep link or universal link entry point so you can exercise routing from an external entry.\n" +
+        "WHEN TO USE: Testing deep-link handlers, universal link routing, OAuth/SSO callback URLs, or any flow that enters the app via a URL.\n" +
+        "WORKFLOW: ios_boot_simulator -> ios_launch_app (or have the app running) -> ios_open_url -> ios_screenshot / get_screen_layout to verify the target screen rendered.\n" +
+        "GOOD: ios_open_url(url=\"myapp://product/42\") to land directly on a product screen.\n" +
+        "BAD: ios_open_url(url=\"...\") used as a substitute for in-app navigation when the user would normally tap — prefer `tap` for normal interaction flows.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook." +
+        platformUniqueBanner("testing iOS deep links or universal links"),
     inputSchema: {
         url: z.string().describe("URL to open (e.g., https://example.com or myapp://path)"),
         udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
@@ -3931,7 +4032,11 @@ registerToolWithTelemetry("ios_open_url", {
 });
 // Tool: iOS terminate app
 registerToolWithTelemetry("ios_terminate_app", {
-    description: "Terminate a running app on an iOS simulator",
+    description: "Terminate a running app on an iOS simulator" +
+        platformUniqueBanner("force-terminating an iOS app") +
+        "\nPURPOSE: Force-kill an iOS app process so the next launch starts from a cold state." +
+        "\nWHEN TO USE: To reset app state fully (beyond what reload_app does), or before reinstalling a new build." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook.",
     inputSchema: {
         bundleId: z.string().describe("Bundle ID of the app to terminate"),
         udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
@@ -3950,7 +4055,12 @@ registerToolWithTelemetry("ios_terminate_app", {
 });
 // Tool: iOS boot simulator
 registerToolWithTelemetry("ios_boot_simulator", {
-    description: "Boot an iOS simulator by UDID. Use list_ios_simulators to find available simulators.",
+    description: "Boot an iOS simulator by UDID.\n" +
+        "PURPOSE: Bring a specific simulator online so you can install/launch an app in it.\n" +
+        "WHEN TO USE: At session start when no simulator is running, or after switching between device models.\n" +
+        "SEE ALSO: call get_usage_guide(topic=\"setup\") for the full session-setup playbook." +
+        platformUniqueBanner("booting an iOS simulator") +
+        " Use list_ios_simulators to find available simulators.",
     inputSchema: {
         udid: z.string().describe("UDID of the simulator to boot (from list_ios_simulators)")
     }
@@ -3971,57 +4081,14 @@ registerToolWithTelemetry("ios_boot_simulator", {
 // Recommended: AXe — brew install cameroncooke/axe/axe (set IOS_DRIVER=axe)
 // Alternative: IDB — brew install idb-companion (default)
 // ============================================================================
-// Tool: iOS swipe
-server.registerTool("ios_swipe", {
-    description: "Swipe gesture on an iOS simulator screen. Pass screenshot pixel coordinates directly — the same values returned by ios_screenshot pressable elements and screen layout. Coordinates are auto-converted to native iOS points internally. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
-    inputSchema: {
-        startX: z.coerce.number().describe("Starting X coordinate in screenshot pixels (from ios_screenshot output)"),
-        startY: z.coerce.number().describe("Starting Y coordinate in screenshot pixels (from ios_screenshot output)"),
-        endX: z.coerce.number().describe("Ending X coordinate in screenshot pixels (from ios_screenshot output)"),
-        endY: z.coerce.number().describe("Ending Y coordinate in screenshot pixels (from ios_screenshot output)"),
-        duration: z.coerce.number().optional().describe("Optional swipe duration in seconds"),
-        delta: z.coerce.number().optional().describe("Optional delta between touch events (step size)"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ startX, startY, endX, endY, duration, delta, udid }) => {
-    const dpr = await getDevicePixelRatio(udid);
-    const firstApp = connectedApps.values().next().value;
-    const scaleFactor = firstApp?.lastScreenshot?.scaleFactor ?? 1;
-    const start = convertScreenshotToTapCoords(startX, startY, "ios", dpr, scaleFactor);
-    const end = convertScreenshotToTapCoords(endX, endY, "ios", dpr, scaleFactor);
-    const result = await iosSwipe(start.x, start.y, end.x, end.y, { duration, delta, udid });
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: iOS input text
-server.registerTool("ios_input_text", {
-    description: "Type text into the active input field on an iOS simulator. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
-    inputSchema: {
-        text: z.string().describe("Text to type into the active input field"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ text, udid }) => {
-    const result = await iosInputText(text, udid);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
 // Tool: iOS button
 server.registerTool("ios_button", {
-    description: "Press a hardware button on an iOS simulator. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
+    description: "Press a hardware button on an iOS simulator." +
+        platformUniqueBanner("pressing iOS hardware buttons (HOME, LOCK, SIRI, APPLE_PAY)") +
+        " Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion)." +
+        "\nPURPOSE: Trigger iOS hardware buttons (HOME, LOCK, SIDE_BUTTON, SIRI, APPLE_PAY) that aren't reachable via on-screen tap." +
+        "\nWHEN TO USE: Send the app to background (HOME), lock the simulator (LOCK), or exercise Siri/Apple Pay flows." +
+        "\nSEE ALSO: call get_usage_guide(topic=\"interact\") for the full UI-interaction playbook.",
     inputSchema: {
         button: z
             .enum(IOS_BUTTON_TYPES)
@@ -4041,210 +4108,6 @@ server.registerTool("ios_button", {
         isError: !result.success
     };
 });
-// Tool: iOS key event
-server.registerTool("ios_key_event", {
-    description: "Send a key event to an iOS simulator by keycode. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
-    inputSchema: {
-        keycode: z.coerce.number().describe("iOS keycode to send"),
-        duration: z.coerce.number().optional().describe("Optional key press duration in seconds"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ keycode, duration, udid }) => {
-    const result = await iosKeyEvent(keycode, { duration, udid });
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: iOS key sequence
-server.registerTool("ios_key_sequence", {
-    description: "Send a sequence of key events to an iOS simulator. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
-    inputSchema: {
-        keycodes: z.array(z.coerce.number()).describe("Array of iOS keycodes to send in sequence"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ keycodes, udid }) => {
-    const result = await iosKeySequence(keycodes, udid);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: iOS describe all (accessibility tree)
-server.registerTool("ios_describe_all", {
-    description: "Get accessibility information for the entire iOS simulator screen. Returns a nested tree of UI elements with labels, values, and frames. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
-    inputSchema: {
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ udid }) => {
-    const result = await iosDescribeAll(udid);
-    let text = result.success ? result.result : `Error: ${result.error}`;
-    // Check for LogBox overlay
-    if (result.success) {
-        try {
-            const logBoxState = await detectLogBox();
-            if (logBoxState && logBoxState.total > 0) {
-                text += formatLogBoxWarning(logBoxState);
-            }
-        }
-        catch {
-            // Non-fatal: LogBox detection failure should not break describe_all
-        }
-    }
-    return {
-        content: [
-            {
-                type: "text",
-                text
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: iOS describe point
-server.registerTool("ios_describe_point", {
-    description: "Get accessibility information for the UI element at a specific point on the iOS simulator screen. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion).",
-    inputSchema: {
-        x: z.coerce.number().describe("X coordinate in pixels"),
-        y: z.coerce.number().describe("Y coordinate in pixels"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ x, y, udid }) => {
-    const result = await iosDescribePoint(x, y, udid);
-    return {
-        content: [
-            {
-                type: "text",
-                text: result.success ? result.result : `Error: ${result.error}`
-            }
-        ],
-        isError: !result.success
-    };
-});
-// Tool: iOS find element (no screenshot needed)
-server.registerTool("ios_find_element", {
-    description: "Find a UI element on iOS simulator by accessibility label or value. Returns element details including tap coordinates. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion). Workflow: 1) wait_for_element, 2) find_element, 3) tap with returned coordinates. Prefer this over screenshots for button taps.",
-    inputSchema: {
-        label: z.string().optional().describe("Exact accessibility label match"),
-        labelContains: z.string().optional().describe("Partial label match (case-insensitive)"),
-        value: z.string().optional().describe("Exact accessibility value match"),
-        valueContains: z.string().optional().describe("Partial value match (case-insensitive)"),
-        type: z.string().optional().describe("Element type to match (e.g., 'Button', 'TextField')"),
-        index: z
-            .number()
-            .optional()
-            .describe("If multiple elements match, select the nth one (0-indexed, default: 0)"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ label, labelContains, value, valueContains, type, index, udid }) => {
-    const result = await iosFindElement({ label, labelContains, value, valueContains, type, index }, udid);
-    if (!result.success) {
-        return {
-            content: [{ type: "text", text: `Error: ${result.error}` }],
-            isError: true
-        };
-    }
-    if (!result.found) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: result.error || "Element not found"
-                }
-            ]
-        };
-    }
-    const el = result.element;
-    const info = [
-        `Found element (${result.matchCount} match${result.matchCount > 1 ? "es" : ""})`,
-        `  Label: "${el.label}"`,
-        `  Value: "${el.value}"`,
-        `  Type: ${el.type}`,
-        `  Frame: {x: ${el.frame.x}, y: ${el.frame.y}, w: ${el.frame.width}, h: ${el.frame.height}}`,
-        `  Center (tap coords): (${el.center.x}, ${el.center.y}) — iOS points. Use tap(text="...") or tap(testID="...") for reliable targeting.`,
-        `  Enabled: ${el.enabled}`
-    ].join("\n");
-    return {
-        content: [{ type: "text", text: info }]
-    };
-});
-// Tool: iOS wait for element
-server.registerTool("ios_wait_for_element", {
-    description: "Wait for a UI element to appear on iOS simulator. Polls until found or timeout. Requires an iOS UI driver: AXe (recommended: brew install cameroncooke/axe/axe) or IDB (brew install idb-companion). Use this FIRST after navigation to ensure screen is ready, then use find_element + tap.",
-    inputSchema: {
-        label: z.string().optional().describe("Exact accessibility label match"),
-        labelContains: z.string().optional().describe("Partial label match (case-insensitive)"),
-        value: z.string().optional().describe("Exact accessibility value match"),
-        valueContains: z.string().optional().describe("Partial value match (case-insensitive)"),
-        type: z.string().optional().describe("Element type to match (e.g., 'Button', 'TextField')"),
-        index: z
-            .number()
-            .optional()
-            .describe("If multiple elements match, select the nth one (0-indexed, default: 0)"),
-        timeoutMs: z
-            .number()
-            .optional()
-            .default(10000)
-            .describe("Maximum time to wait in milliseconds (default: 10000)"),
-        pollIntervalMs: z
-            .number()
-            .optional()
-            .default(500)
-            .describe("Time between polls in milliseconds (default: 500)"),
-        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
-    }
-}, async ({ label, labelContains, value, valueContains, type, index, timeoutMs, pollIntervalMs, udid }) => {
-    const result = await iosWaitForElement({
-        label,
-        labelContains,
-        value,
-        valueContains,
-        type,
-        index,
-        timeoutMs,
-        pollIntervalMs
-    }, udid);
-    if (!result.success) {
-        return {
-            content: [{ type: "text", text: `Error: ${result.error}` }],
-            isError: true
-        };
-    }
-    if (!result.found) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: result.timedOut
-                        ? `Timed out after ${result.elapsedMs}ms - element not found`
-                        : result.error || "Element not found"
-                }
-            ]
-        };
-    }
-    const el = result.element;
-    const info = [
-        `Element found after ${result.elapsedMs}ms`,
-        `  Label: "${el.label}"`,
-        `  Value: "${el.value}"`,
-        `  Type: ${el.type}`,
-        `  Center (tap coords): (${el.center.x}, ${el.center.y}) — iOS points. Use tap(text="...") or tap(testID="...") for reliable targeting.`,
-        `  Enabled: ${el.enabled}`
-    ].join("\n");
-    return {
-        content: [{ type: "text", text: info }]
-    };
-});
 // Tool: Activate Pro license
 registerToolWithTelemetry("activate_license", getActivateLicenseConfig(), handleActivateLicense);
 // Tool: Delete account
@@ -4345,10 +4208,15 @@ async function main() {
         console.error("[rn-ai-debugger] Server started on stdio");
     }
 }
-main().catch((error) => {
-    console.error("[rn-ai-debugger] Fatal error:", error);
-    process.exit(1);
-});
+// Skip boot when loaded by unit tests — tests import this module purely to
+// enumerate `toolRegistry`. Jest sets JEST_WORKER_ID; RN_AI_DEVTOOLS_TEST_MODE
+// is a manual escape hatch. Production + dev:mcp leave both unset and boot.
+if (!process.env.RN_AI_DEVTOOLS_TEST_MODE && !process.env.JEST_WORKER_ID) {
+    main().catch((error) => {
+        console.error("[rn-ai-debugger] Fatal error:", error);
+        process.exit(1);
+    });
+}
 // Graceful shutdown: close CDP connections so the slot is freed for other sessions
 function gracefulShutdown() {
     suppressReconnection();