mcp-web-inspector 0.4.4 → 0.5.0

package/README.md

@@ -997,14 +997,13 @@ Upload a file to an input[type='file'] element on the page
 ### Content
 
 #### `get_html`
-⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements), shows preview with token-based confirmation if larger. Scripts removed by default for security/size. Supports testid shortcuts.
+⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output. Scripts removed by default for security/size. Supports testid shortcuts.
 
 - Parameters:
   - selector (string, optional): CSS selector, text selector, or testid shorthand to limit HTML extraction to a specific container. Omit to get entire page HTML. Example: 'testid:main-content' or '#app'
   - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
   - clean (boolean, optional): Remove noise from HTML: false (default) = remove scripts only, true = remove scripts + styles + comments + meta tags for minimal markup
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
-  - confirmToken (string, optional): Confirmation token from preview response (required to retrieve large HTML). Get this token by calling without confirmToken first - the preview will include the token to use.
 
 #### `get_text`
 ⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Returns plain text up to 20000 chars (truncated if longer). Supports testid shortcuts.
@@ -1044,24 +1043,40 @@ Screenshots saved to ./.mcp-web-inspector/screenshots. Example: { name: "login-p
 
 ### Console
 
+#### `clear_console_logs`
+Clears captured console logs and returns the number of entries cleared.
+
 #### `get_console_logs`
-Retrieve console logs from the browser with filtering options
+Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
 
 - Parameters:
   - type (string, optional): Type of logs to retrieve (all, error, warning, log, info, debug, exception)
   - search (string, optional): Text to search for in logs (handles text with square brackets)
-  - limit (number, optional): Maximum number of logs to return
-  - since (string, optional): Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.)
-  - clear (boolean, optional): Whether to clear logs after retrieval (default: false)
+  - limit (number, optional): Maximum entries to return (groups when grouped, lines when raw). Default: 20
+  - since (string, optional): Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.). Default: 'last-interaction'
+  - format (string, optional): Output format: 'grouped' (default, deduped with counts) or 'raw' (chronological, ungrouped)
 
 ### Evaluation
 
 #### `evaluate`
-⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return the result (JSON-stringified). ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_positions). Use ONLY when specialized tools cannot accomplish the task. Essential for: custom page interactions, complex calculations not covered by other tools. Automatically detects common patterns and suggests better alternatives. High flexibility but less efficient than specialized tools.
+⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return a compact, token-efficient summary of the result. Includes a large-output preview guard with a one-time token. ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_element_alignment). Use ONLY when specialized tools cannot accomplish the task. Automatically detects common patterns and suggests better alternatives.
 
 - Parameters:
   - script (string, required): JavaScript code to execute
 
+- Output Format:
+  - Header: '✓ JavaScript execution result:'
+  - Default result: compact summary string (arrays/objects/dom nodes summarized)
+  - Array summary: 'Array(n) [first, second, third…]' (shows first 3 items)
+  - Object summary (large): 'Object(n keys): key1, key2, key3…' (top-level keys only)
+  - DOM node summary: '<tag id=#id class=.a.b> @ (x,y) WxH' (rounded ints)
+  - NodeList/HTMLCollection summary: 'NodeList(n) [<div…>, <span…>, <a…>…]'
+  - Preview guard when result is large (≥ ~2000 chars):
+    - 'Preview (first 500 chars):' followed by excerpt
+    - Counts: 'totalLength: N, shownLength: M, truncated: true'
+    - One-time token string to fetch full output
+  - Suggestions block (conditional): compact tips for specialized tools based on script patterns
+
 ### Network
 
 #### `get_request_details`
@@ -1103,6 +1118,18 @@ Set the browser color scheme that controls CSS prefers-color-scheme. Defaults to
 
 - Parameters:
   - scheme (string, required): Color scheme to emulate: 'system', 'dark', 'light', or 'no-preference'. Example: { scheme: 'dark' }
+
+### Other
+
+#### `confirm_output`
+Return full output for a previously previewed large result using a one-time token. Use when a tool responded with a preview + token. Safer than resending original parameters.
+
+- Parameters:
+  - token (string, required): One-time token obtained from a tool's preview response
+
+- Output Format:
+  - Full original payload if token is valid (one-time)
+  - Error: 'Invalid or expired token'
 ## Selector Shortcuts ⭐ Time-Saver
 
 All browser tools support **convenient test ID shortcuts** that save typing and improve readability:

package/dist/tools/browser/base.d.ts

@@ -24,6 +24,11 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * @returns Normalized selector
      */
     protected normalizeSelector(selector: string): string;
+    /**
+     * Sanitize verbose Playwright selector engine messages by removing stack traces and
+     * keeping only the essential syntax error information.
+     */
+    private sanitizeSelectorEngineMessage;
     /**
      * Ensures a page is available and returns it
      * @param context The tool context containing browser and page

package/dist/tools/browser/base.js

@@ -33,7 +33,7 @@ export class BrowserToolBase {
             }
         }
         // Clean up common escaping mistakes that LLMs make in CSS selectors
-        // These characters don't need to be escaped in CSS selectors: [ ] :
+        // These characters don't need to be escaped in many selector contexts: [ ] :
         let cleaned = selector;
         // Remove backslash escapes before brackets and colons
         // Handle both single escapes (\[) and double escapes (\\[)
@@ -42,6 +42,29 @@ export class BrowserToolBase {
         cleaned = cleaned.replace(/\\+:/g, ':');
         return cleaned;
     }
+    /**
+     * Sanitize verbose Playwright selector engine messages by removing stack traces and
+     * keeping only the essential syntax error information.
+     */
+    sanitizeSelectorEngineMessage(msg) {
+        if (!msg)
+            return '';
+        // Prefer to cut at the common phrase used by the browser
+        const cutoffPhrases = [
+            "is not a valid selector.",
+            "is not a valid selector",
+        ];
+        for (const phrase of cutoffPhrases) {
+            const idx = msg.indexOf(phrase);
+            if (idx !== -1) {
+                return msg.slice(0, idx + phrase.length).trim();
+            }
+        }
+        // Otherwise remove stack-like lines (e.g., " at query (…)")
+        const lines = msg.split(/\r?\n/);
+        const filtered = lines.filter(l => !/^\s*at\b/.test(l) && !/<anonymous>:\d+:\d+/.test(l));
+        return filtered.join('\n').trim();
+    }
     /**
      * Ensures a page is available and returns it
      * @param context The tool context containing browser and page
@@ -164,20 +187,23 @@ export class BrowserToolBase {
                 errorMsg.includes('Invalid selector') ||
                 errorMsg.includes('SyntaxError') ||
                 errorMsg.includes('selector')) {
+                const conciseMsg = this.sanitizeSelectorEngineMessage(errorMsg);
+                // Helpful, accurate guidance with Tailwind-style examples
+                const tips = [
+                    '💡 Tips:',
+                    '  • Tailwind arbitrary values need escaping in class selectors: .min-w-\\[300px\\]',
+                    '  • Colons in class names must be escaped: .dark\\:bg-gray-700',
+                    '  • Prefer robust selectors: use testid:name or [data-testid="..."]',
+                    '  • Attribute selectors avoid escaping issues: [class*="min-w-[300px]"]',
+                    '',
+                    'Examples:',
+                    '  ✓ .min-w-\\[300px\\] .flex-1',
+                    '  ✓ testid:submit-button',
+                    '  ✓ #login-form'
+                ].join('\n');
                 throw new Error(`Invalid CSS selector: "${selector}"\n\n` +
-                    `Selector syntax error: ${errorMsg}\n\n` +
-                    `💡 Tips:\n` +
-                    `  • CSS selectors don't need backslash escapes for [ ] or :\n` +
-                    `  • Use .class-name or #id without escaping\n` +
-                    `  • For data attributes, use [data-attr="value"]\n` +
-                    `  • For testid shortcuts, use testid:name\n\n` +
-                    `Examples:\n` +
-                    `  ✓ .dark:bg-gray-700\n` +
-                    `  ✓ .top-[36px]\n` +
-                    `  ✓ testid:submit-button\n` +
-                    `  ✓ #login-form\n` +
-                    `  ✗ .dark\\:bg-gray-700 (unnecessary escape)\n` +
-                    `  ✗ .top-\\[36px\\] (unnecessary escape)`);
+                    (conciseMsg ? `Selector syntax error: ${conciseMsg}\n\n` : '') +
+                    tips);
             }
             // Re-throw other errors as-is
             throw error;

package/dist/tools/browser/console/__tests__/console.test.js

@@ -1,4 +1,4 @@
-import { GetConsoleLogsTool } from '../get_console_logs.js';
+import { GetConsoleLogsTool, ClearConsoleLogsTool } from '../get_console_logs.js';
 import { jest } from '@jest/globals';
 // Mock the server
 const mockServer = {
@@ -67,16 +67,14 @@ describe('GetConsoleLogsTool', () => {
         const logText = result.content[1].text;
         expect(logText).toContain('Test log message');
     });
-    test('should clear console logs when requested', async () => {
+    test('should clear console logs using clear_console_logs tool', async () => {
         consoleLogsTool.registerConsoleMessage('log', 'Test log message');
         consoleLogsTool.registerConsoleMessage('error', 'Test error message');
-        const args = {
-            clear: true
-        };
-        const result = await consoleLogsTool.execute(args, mockContext);
+        const clearer = new ClearConsoleLogsTool(mockServer);
+        const result = await clearer.execute({}, mockContext);
         expect(result.isError).toBe(false);
-        expect(result.content[0].text).toContain('Retrieved 2 console log(s)');
-        // Logs should be cleared after retrieval
+        expect(result.content[0].text).toContain('Cleared 2 console log(s)');
+        // Logs should be cleared
         const logs = consoleLogsTool.getConsoleLogs();
         expect(logs.length).toBe(0);
     });

package/dist/tools/browser/console/get_console_logs.d.ts

@@ -8,6 +8,8 @@ export declare class GetConsoleLogsTool extends BrowserToolBase {
     private lastCallTimestamp;
     private lastNavigationTimestamp;
     private lastInteractionTimestamp;
+    static latestInstance: GetConsoleLogsTool | null;
+    constructor(server: any);
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     /**
      * Register a console message
@@ -35,3 +37,10 @@ export declare class GetConsoleLogsTool extends BrowserToolBase {
      */
     getLogsSinceLastNavigation(): string[];
 }
+/**
+ * Tool for clearing console logs (atomic operation)
+ */
+export declare class ClearConsoleLogsTool extends BrowserToolBase {
+    static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/console/get_console_logs.js

@@ -1,20 +1,23 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse } from '../../common/types.js';
+import { makeConfirmPreview } from '../../common/confirmHelpers.js';
 /**
  * Tool for retrieving and filtering console logs from the browser
  */
 export class GetConsoleLogsTool extends BrowserToolBase {
-    constructor() {
-        super(...arguments);
+    constructor(server) {
+        super(server);
+        // Stored logs and timestamps
         this.consoleLogs = [];
         this.lastCallTimestamp = 0;
         this.lastNavigationTimestamp = 0;
         this.lastInteractionTimestamp = 0;
+        GetConsoleLogsTool.latestInstance = this;
     }
     static getMetadata(sessionConfig) {
         return {
             name: "get_console_logs",
-            description: "Retrieve console logs from the browser with filtering options",
+            description: "Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -29,17 +32,18 @@ export class GetConsoleLogsTool extends BrowserToolBase {
                     },
                     limit: {
                         type: "number",
-                        description: "Maximum number of logs to return"
+                        description: "Maximum entries to return (groups when grouped, lines when raw). Default: 20"
                     },
                     since: {
                         type: "string",
-                        description: "Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.)",
+                        description: "Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.). Default: 'last-interaction'",
                         enum: ["last-call", "last-navigation", "last-interaction"]
                     },
-                    clear: {
-                        type: "boolean",
-                        description: "Whether to clear logs after retrieval (default: false)"
-                    }
+                    format: {
+                        type: "string",
+                        description: "Output format: 'grouped' (default, deduped with counts) or 'raw' (chronological, ungrouped)",
+                        enum: ["grouped", "raw"]
+                    },
                 },
                 required: [],
             },
@@ -68,11 +72,16 @@ export class GetConsoleLogsTool extends BrowserToolBase {
         this.lastInteractionTimestamp = Date.now();
     }
     async execute(args, context) {
+        // Defaults
+        const format = args.format === 'raw' ? 'raw' : 'grouped';
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.floor(args.limit) : 20;
+        const sinceArg = args.since || 'last-interaction';
+        const PREVIEW_THRESHOLD = 2000; // chars
         let logs = [...this.consoleLogs];
         // Filter by timestamp if 'since' parameter is specified
-        if (args.since) {
+        if (sinceArg) {
             let sinceTimestamp;
-            switch (args.since) {
+            switch (sinceArg) {
                 case 'last-call':
                     sinceTimestamp = this.lastCallTimestamp;
                     break;
@@ -83,7 +92,7 @@ export class GetConsoleLogsTool extends BrowserToolBase {
                     sinceTimestamp = this.lastInteractionTimestamp;
                     break;
                 default:
-                    return createSuccessResponse(`Invalid 'since' value: ${args.since}. Must be one of: last-call, last-navigation, last-interaction`);
+                    return createSuccessResponse(`Invalid 'since' value: ${sinceArg}. Must be one of: last-call, last-navigation, last-interaction`);
             }
             logs = logs.filter(log => log.timestamp > sinceTimestamp);
         }
@@ -97,26 +106,71 @@ export class GetConsoleLogsTool extends BrowserToolBase {
         if (args.search) {
             logs = logs.filter(log => log.message.includes(args.search));
         }
-        // Limit the number of logs if specified
-        if (args.limit && args.limit > 0) {
-            logs = logs.slice(-args.limit);
+        // Build output according to format
+        if (format === 'raw') {
+            // Chronological lines, limit applied to last N entries
+            const limited = limit > 0 ? logs.slice(-limit) : logs;
+            const messages = limited.map(l => l.message);
+            if (messages.length === 0) {
+                return createSuccessResponse("No console logs matching the criteria");
+            }
+            // Guard large outputs by character size
+            const header = `Retrieved ${messages.length} console log(s):`;
+            const textPayload = [header, ...messages].join('\n');
+            if (textPayload.length >= PREVIEW_THRESHOLD) {
+                const previewLines = [
+                    `Matched ${logs.length} log(s). Showing ${Math.min(messages.length, 10)} line(s) preview.`,
+                    ...messages.slice(0, Math.min(messages.length, 10)),
+                ];
+                const preview = makeConfirmPreview(textPayload, {
+                    counts: { totalLength: textPayload.length, shownLength: previewLines.join('\n').length, totalMatched: logs.length, shownCount: Math.min(messages.length, 10), truncated: true },
+                    previewLines,
+                    extraTips: ['Tip: refine with search/type/since/limit or prefer grouped format.'],
+                });
+                return createSuccessResponse(preview.lines.join('\n'));
+            }
+            return createSuccessResponse([header, ...messages]);
         }
-        // Extract messages from log entries
-        const messages = logs.map(log => log.message);
-        // Clear logs if requested
-        if (args.clear) {
-            this.consoleLogs = [];
+        // Grouped format (default)
+        const groups = new Map();
+        for (const l of logs) {
+            const key = l.message; // includes [type] prefix per registerConsoleMessage
+            const g = groups.get(key);
+            if (g) {
+                g.count += 1;
+                g.lastTs = l.timestamp;
+            }
+            else {
+                groups.set(key, { count: 1, firstTs: l.timestamp, lastTs: l.timestamp, example: l.message });
+            }
         }
-        // Format the response
-        if (messages.length === 0) {
+        if (groups.size === 0) {
             return createSuccessResponse("No console logs matching the criteria");
         }
-        else {
-            return createSuccessResponse([
-                `Retrieved ${messages.length} console log(s):`,
-                ...messages
-            ]);
+        // Order groups by first occurrence time
+        const ordered = Array.from(groups.entries()).sort((a, b) => a[1].firstTs - b[1].firstTs);
+        const limitedGroups = limit > 0 ? ordered.slice(0, limit) : ordered;
+        const lines = [];
+        lines.push(`Retrieved ${limitedGroups.length} console log(s):`);
+        for (const [msg, info] of limitedGroups) {
+            const line = `${msg} (× ${info.count})`;
+            lines.push(line);
         }
+        // Guard large grouped outputs
+        const textPayload = lines.join('\n');
+        if (textPayload.length >= PREVIEW_THRESHOLD) {
+            const previewLines = [
+                `Matched ${groups.size} group(s). Showing ${limitedGroups.length}.`,
+                ...lines.slice(0, Math.min(lines.length, 12)),
+            ];
+            const preview = makeConfirmPreview(textPayload, {
+                counts: { totalLength: textPayload.length, shownLength: previewLines.join('\n').length, totalMatched: groups.size, shownCount: limitedGroups.length, truncated: true },
+                previewLines,
+                extraTips: ['Tip: refine with search/type/since/limit.'],
+            });
+            return createSuccessResponse(preview.lines.join('\n'));
+        }
+        return createSuccessResponse(lines);
     }
     /**
      * Get all console logs
@@ -140,3 +194,30 @@ export class GetConsoleLogsTool extends BrowserToolBase {
             .map(log => log.message);
     }
 }
+// Track latest instance for sibling tool access (module-level singleton pattern)
+GetConsoleLogsTool.latestInstance = null;
+/**
+ * Tool for clearing console logs (atomic operation)
+ */
+export class ClearConsoleLogsTool extends BrowserToolBase {
+    static getMetadata(sessionConfig) {
+        return {
+            name: "clear_console_logs",
+            description: "Clears captured console logs and returns the number of entries cleared.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        };
+    }
+    async execute(args, context) {
+        const inst = GetConsoleLogsTool.latestInstance;
+        if (!inst) {
+            return createSuccessResponse('Cleared 0 console log(s)');
+        }
+        const count = inst.getConsoleLogs().length;
+        inst.clearConsoleLogs();
+        return createSuccessResponse(`Cleared ${count} console log(s)`);
+    }
+}

package/dist/tools/browser/console/index.d.ts

@@ -1 +1 @@
-export { GetConsoleLogsTool } from './get_console_logs.js';
+export { GetConsoleLogsTool, ClearConsoleLogsTool } from './get_console_logs.js';

package/dist/tools/browser/console/index.js

@@ -1 +1 @@
-export { GetConsoleLogsTool } from './get_console_logs.js';
+export { GetConsoleLogsTool, ClearConsoleLogsTool } from './get_console_logs.js';

package/dist/tools/browser/content/__tests__/visiblePage.test.js

@@ -392,9 +392,9 @@ describe('GetHtmlTool', () => {
         expect(result.content[0].text).toContain('⚠️ Full HTML not returned to save tokens');
         expect(result.content[0].text).toContain('💡 RECOMMENDED: Use token-efficient alternatives');
         expect(result.content[0].text).toContain('inspect_dom()');
-        expect(result.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+        expect(result.content[0].text).toMatch(/confirm_output\(\{ token: \"[\w\d]+\" \}\)/);
     });
-    test('should return full HTML with valid confirmToken', async () => {
+    test('should return full HTML with valid token via confirm_output', async () => {
         const args = {};
         // Large HTML
         const largeHtml = '<div>' + 'Y'.repeat(3000) + '</div>';
@@ -402,29 +402,22 @@ describe('GetHtmlTool', () => {
         // First call - get preview and token
         const previewResult = await visibleHtmlTool.execute(args, mockContext);
         expect(previewResult.isError).toBe(false);
-        // Extract token from preview
-        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        // Extract token from preview and confirm using confirm_output tool
+        const tokenMatch = previewResult.content[0].text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
         expect(tokenMatch).toBeTruthy();
         const token = tokenMatch[1];
-        // Second call - with token
-        const fullResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const fullResult = await confirmTool.execute({ token }, {});
         expect(fullResult.isError).toBe(false);
         expect(fullResult.content[0].text).toContain(largeHtml);
-        expect(fullResult.content[0].text).not.toContain('Preview (first 500 chars)');
-        expect(fullResult.content[0].text).toContain('💡 TIP: If you need structured inspection');
     });
-    test('should generate new token for invalid confirmToken', async () => {
-        const args = { confirmToken: 'invalid123' };
-        // Large HTML
-        const largeHtml = '<div>' + 'Z'.repeat(3000) + '</div>';
-        mockEvaluate.mockImplementationOnce(() => Promise.resolve(largeHtml));
-        const result = await visibleHtmlTool.execute(args, mockContext);
-        expect(result.isError).toBe(false);
-        expect(result.content[0].text).toContain('HTML size:');
-        expect(result.content[0].text).toContain('Preview (first 500 chars)');
-        expect(result.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
-        // Should not return full HTML
-        expect(result.content[0].text).not.toContain('Z'.repeat(3000));
+    test('confirm_output should error on invalid token', async () => {
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const res = await confirmTool.execute({ token: 'invalid123' }, {});
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain('Invalid or expired token');
     });
     test('should return small HTML directly without token requirement', async () => {
         const args = {};
@@ -445,22 +438,20 @@ describe('GetHtmlTool', () => {
         mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
         // First call - get token
         const previewResult = await visibleHtmlTool.execute(args, mockContext);
-        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        const tokenMatch = previewResult.content[0].text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
         const token = tokenMatch[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
         // Second call - use token (should work)
-        const fullResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        const fullResult = await confirmTool.execute({ token }, {});
         expect(fullResult.isError).toBe(false);
         expect(fullResult.content[0].text).toContain(largeHtml);
-        // Third call - try to reuse same token (should fail, get new preview)
-        const retryResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
-        expect(retryResult.isError).toBe(false);
-        expect(retryResult.content[0].text).toContain('Preview (first 500 chars)');
-        expect(retryResult.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
-        // Should have different token
-        const newTokenMatch = retryResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
-        expect(newTokenMatch[1]).not.toBe(token);
-    });
-    test('should handle large HTML with selector and confirmToken', async () => {
+        // Third call - try to reuse same token (should fail)
+        const retryResult = await confirmTool.execute({ token }, {});
+        expect(retryResult.isError).toBe(true);
+        expect(retryResult.content[0].text).toContain('Invalid or expired token');
+    });
+    test('should handle large HTML with selector and confirm_output', async () => {
         const largeHtml = '<section>' + 'S'.repeat(3000) + '</section>';
         const args = { selector: 'testid:large-section' };
         mockLocator.mockImplementation(() => ({}));
@@ -474,10 +465,12 @@ describe('GetHtmlTool', () => {
         // First call - get preview
         const previewResult = await visibleHtmlTool.execute(args, mockContext);
         expect(previewResult.content[0].text).toContain('(from "testid:large-section")');
-        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        const tokenMatch = previewResult.content[0].text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
         const token = tokenMatch[1];
-        // Second call - with token
-        const fullResult = await visibleHtmlTool.execute({ selector: 'testid:large-section', confirmToken: token }, mockContext);
+        // Second call - with token via confirm tool
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const fullResult = await confirmTool.execute({ token }, {});
         expect(fullResult.isError).toBe(false);
         expect(fullResult.content[0].text).toContain(largeHtml);
         selectSpy.mockRestore();

package/dist/tools/browser/content/get_html.d.ts

@@ -4,7 +4,6 @@ import { ToolContext, ToolResponse, ToolMetadata, SessionConfig } from '../../co
  * Tool for getting HTML from the page
  */
 export declare class GetHtmlTool extends BrowserToolBase {
-    private confirmTokens;
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     execute(args: any, context: ToolContext): Promise<ToolResponse>;
 }

package/dist/tools/browser/content/get_html.js

@@ -1,17 +1,14 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse, createErrorResponse, } from '../../common/types.js';
+import { makeConfirmPreview } from '../../common/confirmHelpers.js';
 /**
  * Tool for getting HTML from the page
  */
 export class GetHtmlTool extends BrowserToolBase {
-    constructor() {
-        super(...arguments);
-        this.confirmTokens = new Map(); // Stores tokens for two-step confirmation
-    }
     static getMetadata(sessionConfig) {
         return {
             name: "get_html",
-            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements), shows preview with token-based confirmation if larger. Scripts removed by default for security/size. Supports testid shortcuts.",
+            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output. Scripts removed by default for security/size. Supports testid shortcuts.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -30,10 +27,6 @@ export class GetHtmlTool extends BrowserToolBase {
                     maxLength: {
                         type: "number",
                         description: "Maximum number of characters to return (default: 20000)"
-                    },
-                    confirmToken: {
-                        type: "string",
-                        description: "Confirmation token from preview response (required to retrieve large HTML). Get this token by calling without confirmToken first - the preview will include the token to use."
                     }
                 },
                 required: [],
@@ -45,7 +38,6 @@ export class GetHtmlTool extends BrowserToolBase {
             ? Math.floor(args.maxLength)
             : 20000;
         const clean = args.clean ?? false;
-        const confirmToken = args.confirmToken;
         const PREVIEW_THRESHOLD = 2000;
         if (!context.page) {
             return createErrorResponse('Page is not available');
@@ -111,37 +103,27 @@ export class GetHtmlTool extends BrowserToolBase {
                 const processedHtml = sanitizedHtml ?? '';
                 const originalLength = processedHtml.length;
                 // Generate key for this HTML request
-                const tokenKey = `${args.selector || 'page'}:${originalLength}`;
-                // Check if HTML is too large
+                // Check if HTML is too large => return preview + token for confirm_output
                 if (originalLength >= PREVIEW_THRESHOLD) {
-                    // Verify if confirmToken matches
-                    const expectedToken = this.confirmTokens.get(tokenKey);
-                    if (confirmToken && expectedToken && confirmToken === expectedToken) {
-                        // Valid token - delete it (one-time use) and proceed to return HTML
-                        this.confirmTokens.delete(tokenKey);
-                    }
-                    else {
-                        // No token or invalid token - show preview and generate new token
-                        const newToken = Math.random().toString(36).substring(2, 10);
-                        this.confirmTokens.set(tokenKey, newToken);
-                        lines.push(`HTML size: ${originalLength.toLocaleString()} characters (exceeds ${PREVIEW_THRESHOLD} char threshold)`);
-                        lines.push('');
-                        lines.push('Preview (first 500 chars):');
-                        lines.push(processedHtml.slice(0, 500));
-                        if (originalLength > 500) {
-                            lines.push('...');
-                        }
-                        lines.push('');
-                        lines.push('⚠️ Full HTML not returned to save tokens (~' + Math.round(originalLength / 3) + ' tokens)');
-                        lines.push('');
-                        lines.push('💡 RECOMMENDED: Use token-efficient alternatives:');
-                        lines.push('   • inspect_dom() - structured view with positions and layout');
-                        lines.push('   • query_selector_all() - find specific elements');
-                        lines.push('   • get_computed_styles() - CSS values for debugging');
-                        lines.push('');
-                        lines.push(`To get full HTML anyway, call again with: confirmToken: "${newToken}"`);
-                        return createSuccessResponse(lines.join('\n'));
-                    }
+                    const preview = makeConfirmPreview(processedHtml, {
+                        counts: { totalLength: originalLength, shownLength: Math.min(500, originalLength), truncated: true },
+                        previewLines: [
+                            'Preview (first 500 chars):',
+                            processedHtml.slice(0, 500),
+                            ...(originalLength > 500 ? ['...'] : []),
+                            '',
+                            '⚠️ Full HTML not returned to save tokens',
+                            '',
+                            '💡 RECOMMENDED: Use token-efficient alternatives:',
+                            '   • inspect_dom() - structured view with positions and layout',
+                            '   • query_selector_all() - find specific elements',
+                            '   • get_computed_styles() - CSS values for debugging',
+                        ],
+                    });
+                    lines.push(`HTML size: ${originalLength.toLocaleString()} characters (exceeds ${PREVIEW_THRESHOLD} char threshold)`);
+                    lines.push('');
+                    lines.push(...preview.lines);
+                    return createSuccessResponse(lines.join('\n'));
                 }
                 // Return full HTML (either small or explicitly requested)
                 let displayHtml = processedHtml;

package/dist/tools/browser/evaluation/evaluate.js

@@ -1,5 +1,6 @@
 import { BrowserToolBase } from '../base.js';
-import { createSuccessResponse } from '../../common/types.js';
+import { createSuccessResponse, createErrorResponse, } from '../../common/types.js';
+import { makeConfirmPreview } from '../../common/confirmHelpers.js';
 /**
  * Tool for executing JavaScript in the browser
  */
@@ -7,7 +8,20 @@ export class EvaluateTool extends BrowserToolBase {
     static getMetadata(sessionConfig) {
         return {
             name: "evaluate",
-            description: "⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return the result (JSON-stringified). ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_positions). Use ONLY when specialized tools cannot accomplish the task. Essential for: custom page interactions, complex calculations not covered by other tools. Automatically detects common patterns and suggests better alternatives. High flexibility but less efficient than specialized tools.",
+            description: "⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return a compact, token-efficient summary of the result. Includes a large-output preview guard with a one-time token. ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_element_alignment). Use ONLY when specialized tools cannot accomplish the task. Automatically detects common patterns and suggests better alternatives.",
+            outputs: [
+                "Header: '✓ JavaScript execution result:'",
+                "Default result: compact summary string (arrays/objects/dom nodes summarized)",
+                "Array summary: 'Array(n) [first, second, third…]' (shows first 3 items)",
+                "Object summary (large): 'Object(n keys): key1, key2, key3…' (top-level keys only)",
+                "DOM node summary: '<tag id=#id class=.a.b> @ (x,y) WxH' (rounded ints)",
+                "NodeList/HTMLCollection summary: 'NodeList(n) [<div…>, <span…>, <a…>…]'",
+                "Preview guard when result is large (≥ ~2000 chars):",
+                "  - 'Preview (first 500 chars):' followed by excerpt",
+                "  - Counts: 'totalLength: N, shownLength: M, truncated: true'",
+                "  - One-time token string to fetch full output",
+                "Suggestions block (conditional): compact tips for specialized tools based on script patterns",
+            ],
             inputSchema: {
                 type: "object",
                 properties: {
@@ -32,7 +46,7 @@ export class EvaluateTool extends BrowserToolBase {
         // Pattern: Getting text content
         if (scriptLower.match(/textcontent|innertext/)) {
             suggestions.push('📝 Text Content\n' +
-                '   • get_visible_text() - Extract all visible text\n' +
+                '   • get_text - Extract all visible text\n' +
                 '   • find_by_text({ text: "..." }) - Locate elements by content');
         }
         // Pattern: Checking if element is scrollable (scrollHeight > clientHeight)
@@ -60,7 +74,7 @@ export class EvaluateTool extends BrowserToolBase {
         }
         // Pattern: Checking visibility
         if (scriptLower.match(/offsetparent|visibility|display.*none|opacity/)) {
-            suggestions.push('👁️  Visibility Check - Use element_visibility({ selector: "..." })\n' +
+            suggestions.push('👁️  Visibility Check - Use check_visibility({ selector: "..." })\n' +
                 '   Returns: isVisible, inViewport, opacity, display, visibility properties\n' +
                 '   More reliable: Handles edge cases (opacity:0, visibility:hidden, etc.)');
         }
@@ -85,7 +99,7 @@ export class EvaluateTool extends BrowserToolBase {
         // Pattern: Comparing positions/alignment
         if (scriptLower.match(/getboundingclientrect.*getboundingclientrect/) ||
             (scriptLower.match(/\.left|\.top|\.right|\.bottom/) && scriptLower.match(/===|==|!==|!=/))) {
-            suggestions.push('⚖️  Position Comparison - Use compare_positions({ selector1: "...", selector2: "..." })\n' +
+            suggestions.push('⚖️  Position Comparison - Use compare_element_alignment({ selector1: "...", selector2: "..." })\n' +
                 '   Returns: Alignment status (left/right/top/bottom/center), pixel gaps\n' +
                 '   Perfect for: Checking if elements are aligned or overlapping');
         }
@@ -104,21 +118,182 @@ export class EvaluateTool extends BrowserToolBase {
     async execute(args, context) {
         this.recordInteraction();
         return this.safeExecute(context, async (page) => {
-            const result = await page.evaluate(args.script);
-            // Convert result to string for display
+            const PREVIEW_THRESHOLD = 2000; // chars
+            // Execute the script and produce a compact textual summary entirely in the page context
+            // to safely handle DOM nodes and browser-specific objects.
+            const evalReturn = await page.evaluate(async (userScript) => {
+                const toInt = (n) => Math.max(0, Math.round(n || 0));
+                // Summarize a DOM element
+                const summarizeElement = (el) => {
+                    try {
+                        const tag = (el.tagName || '').toLowerCase();
+                        const id = el.id ? ` #${el.id}` : '';
+                        const cls = el.classList?.length
+                            ? ' ' + Array.from(el.classList)
+                                .map(c => `.${c}`)
+                                .join('')
+                            : '';
+                        const rect = el.getBoundingClientRect?.();
+                        const x = toInt(rect?.left ?? 0);
+                        const y = toInt(rect?.top ?? 0);
+                        const w = toInt(rect?.width ?? 0);
+                        const h = toInt(rect?.height ?? 0);
+                        return `<${tag}${id}${cls}> @ (${x},${y}) ${w}x${h}`;
+                    }
+                    catch {
+                        const tag = (el.tagName || '').toLowerCase();
+                        return `<${tag}>`;
+                    }
+                };
+                // Render values compactly
+                const render = (val, depth, seen) => {
+                    const MAX_DEPTH = 3;
+                    const ARRAY_PREVIEW = 3;
+                    const LARGE_ARRAY_THRESHOLD = 10;
+                    const LARGE_OBJECT_THRESHOLD = 15;
+                    const t = Object.prototype.toString.call(val);
+                    if (val === null)
+                        return 'null';
+                    if (val === undefined)
+                        return 'undefined';
+                    if (typeof val === 'string')
+                        return JSON.stringify(val);
+                    if (typeof val === 'number' || typeof val === 'boolean')
+                        return String(val);
+                    if (typeof val === 'bigint')
+                        return `${String(val)}n`;
+                    if (typeof val === 'function')
+                        return `[Function ${val.name || 'anonymous'}]`;
+                    if (t === '[object Date]')
+                        return `Date(${val.toISOString?.() || String(val)})`;
+                    if (t === '[object RegExp]')
+                        return String(val);
+                    if (t === '[object Error]')
+                        return `${val.name || 'Error'}: ${val.message || String(val)}`;
+                    // DOM element
+                    if (typeof Element !== 'undefined' && val instanceof Element) {
+                        return summarizeElement(val);
+                    }
+                    // NodeList / HTMLCollection
+                    if ((typeof NodeList !== 'undefined' && val instanceof NodeList) ||
+                        (typeof HTMLCollection !== 'undefined' && val instanceof HTMLCollection)) {
+                        const arr = Array.from(val);
+                        const head = arr.slice(0, ARRAY_PREVIEW).map((e) => typeof Element !== 'undefined' && e instanceof Element ? summarizeElement(e) : render(e, depth + 1, seen));
+                        const more = arr.length > ARRAY_PREVIEW ? '…' : '';
+                        return `NodeList(${arr.length}) [${head.join(', ')}${more}]`;
+                    }
+                    if (depth >= MAX_DEPTH) {
+                        if (Array.isArray(val))
+                            return `Array(${val.length}) […]`;
+                        if (val && typeof val === 'object')
+                            return `Object(${Object.keys(val).length} keys) …`;
+                        return String(val);
+                    }
+                    // Avoid circular structures
+                    if (val && typeof val === 'object') {
+                        if (seen.has(val))
+                            return '[Circular]';
+                        seen.add(val);
+                    }
+                    if (Array.isArray(val)) {
+                        if (val.length > LARGE_ARRAY_THRESHOLD) {
+                            const head = val.slice(0, ARRAY_PREVIEW).map((v) => render(v, depth + 1, seen));
+                            const more = val.length > ARRAY_PREVIEW ? '…' : '';
+                            return `Array(${val.length}) [${head.join(', ')}${more}]`;
+                        }
+                        return `[${val.map((v) => render(v, depth + 1, seen)).join(', ')}]`;
+                    }
+                    // Map / Set
+                    if (t === '[object Map]') {
+                        const m = val;
+                        const entries = Array.from(m.entries()).slice(0, ARRAY_PREVIEW).map(([k, v]) => `${render(k, depth + 1, seen)} => ${render(v, depth + 1, seen)}`);
+                        const more = m.size > ARRAY_PREVIEW ? '…' : '';
+                        return `Map(${m.size}) {${entries.join(', ')}${more}}`;
+                    }
+                    if (t === '[object Set]') {
+                        const s = val;
+                        const entries = Array.from(s.values()).slice(0, ARRAY_PREVIEW).map((v) => render(v, depth + 1, seen));
+                        const more = s.size > ARRAY_PREVIEW ? '…' : '';
+                        return `Set(${s.size}) {${entries.join(', ')}${more}}`;
+                    }
+                    if (val && typeof val === 'object') {
+                        const keys = Object.keys(val);
+                        if (keys.length > LARGE_OBJECT_THRESHOLD) {
+                            const head = keys.slice(0, ARRAY_PREVIEW).join(', ');
+                            const more = keys.length > ARRAY_PREVIEW ? '…' : '';
+                            return `Object(${keys.length} keys): ${head}${more}`;
+                        }
+                        // Render small object inline key: value
+                        const parts = [];
+                        for (const k of keys) {
+                            try {
+                                parts.push(`${k}: ${render(val[k], depth + 1, seen)}`);
+                            }
+                            catch (e) {
+                                parts.push(`${k}: [Unserializable]`);
+                            }
+                        }
+                        return `{ ${parts.join(', ')} }`;
+                    }
+                    return String(val);
+                };
+                try {
+                    // Build an async function so both sync and async scripts are supported
+                    const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+                    const fn = new AsyncFunction(userScript);
+                    const result = await fn();
+                    const text = render(result, 0, new WeakSet());
+                    return { ok: true, text };
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }, args.script);
+            // Backward compatibility: if the page evaluation returns a raw value (string/any)
+            // instead of the { ok, text } envelope, treat it as the final result string.
             let resultStr;
-            try {
-                resultStr = JSON.stringify(result, null, 2);
+            if (evalReturn && typeof evalReturn === 'object' && 'ok' in evalReturn) {
+                const { ok, text, error: execError } = evalReturn;
+                if (!ok) {
+                    return createErrorResponse(`JavaScript execution failed: ${execError}`);
+                }
+                resultStr = text || '';
             }
-            catch (error) {
-                resultStr = String(result);
+            else {
+                try {
+                    resultStr = typeof evalReturn === 'string' ? evalReturn : JSON.stringify(evalReturn, null, 2);
+                }
+                catch {
+                    resultStr = String(evalReturn);
+                }
             }
-            const messages = [
-                `✓ JavaScript execution result:`,
-                `${resultStr}`
-            ];
-            // Detect if specialized tools would be better
+            // Guard for large outputs: preview + confirm
+            const totalLength = resultStr.length;
+            const lines = [];
             const suggestions = this.detectBetterToolSuggestions(args.script);
+            if (totalLength >= PREVIEW_THRESHOLD) {
+                const previewLen = Math.min(500, totalLength);
+                const preview = resultStr.slice(0, previewLen);
+                const previewBlock = makeConfirmPreview(resultStr, {
+                    headerLine: '✓ JavaScript execution result (preview):',
+                    counts: { totalLength, shownLength: previewLen, truncated: true },
+                    previewLines: [
+                        'Preview (first 500 chars):',
+                        preview,
+                        ...(totalLength > previewLen ? ['...'] : []),
+                    ],
+                    extraTips: ['Tip: Prefer specialized tools or narrow the script when possible.'],
+                });
+                lines.push(...previewBlock.lines);
+                if (suggestions.length > 0) {
+                    lines.push('');
+                    lines.push('💡 Consider specialized tools:');
+                    suggestions.forEach(s => lines.push(`   ${s}`));
+                }
+                return createSuccessResponse(lines);
+            }
+            const messages = [`✓ JavaScript execution result:`, resultStr];
+            // Detect if specialized tools would be better
             if (suggestions.length > 0) {
                 messages.push('');
                 messages.push('💡 Consider using specialized tools instead:');

package/dist/tools/browser/inspection/__tests__/measureElement.test.js

@@ -330,4 +330,27 @@ describe('MeasureElementTool', () => {
         expect(text).toContain('Margin:');
         expect(text).toMatch(/↑15px|↓15px|←15px|→15px/); // Should show margin with arrows
     });
+    it('returns clean error for invalid CSS selector without stack trace', async () => {
+        await page.setContent(`
+      <html>
+        <body>
+          <div class="flex min-w-[300px] flex-1">Hello</div>
+        </body>
+      </html>
+    `);
+        // Intentionally pass an invalid selector (missing escapes for [ ])
+        const result = await tool.execute({ selector: '.flex.min-w-[300px].flex-1' }, { page, browser });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        // Should present a concise, user-friendly error without stack traces
+        expect(text).toContain('Invalid CSS selector:');
+        expect(text).toContain('Selector syntax error:');
+        expect(text).toContain('not a valid selector');
+        // No internal stack frames from the selector engine
+        expect(text).not.toMatch(/\n\s*at\b/);
+        expect(text).not.toContain('<anonymous>:');
+        // Provide helpful guidance for Tailwind-style class names
+        expect(text).toContain('Tailwind arbitrary values need escaping');
+        expect(text).toContain('.min-w-\\[300px\\]');
+    });
 });

package/dist/tools/browser/interaction/__tests__/interaction.test.js

@@ -219,7 +219,11 @@ describe('Browser Interaction Tools', () => {
                 script: 'return document.title'
             };
             const result = await evaluateTool.execute(args, mockContext);
-            expect(mockEvaluate).toHaveBeenCalledWith('return document.title');
+            // evaluate() wraps script inside a function passed to page.evaluate
+            expect(mockEvaluate).toHaveBeenCalled();
+            const argsPassed = mockEvaluate.mock.calls[0];
+            expect(typeof argsPassed[0]).toBe('function');
+            expect(argsPassed[1]).toBe('return document.title');
             expect(result.isError).toBe(false);
             expect(result.content[0].text).toContain('JavaScript execution result');
         });
@@ -233,7 +237,7 @@ describe('Browser Interaction Tools', () => {
             expect(fullResponse).toContain('💡 Consider using specialized tools instead');
             expect(fullResponse).toContain('inspect_dom');
         });
-        test('should suggest get_visible_text for textContent usage', async () => {
+        test('should suggest get_text for textContent usage', async () => {
             const args = {
                 script: 'document.body.textContent'
             };
@@ -241,7 +245,7 @@ describe('Browser Interaction Tools', () => {
             const fullResponse = result.content.map(c => c.text).join('\n');
             expect(result.isError).toBe(false);
             expect(fullResponse).toContain('💡 Consider using specialized tools instead');
-            expect(fullResponse).toContain('get_visible_text');
+            expect(fullResponse).toContain('get_text');
         });
         test('should suggest measure_element for getBoundingClientRect usage', async () => {
             const args = {
@@ -253,7 +257,7 @@ describe('Browser Interaction Tools', () => {
             expect(fullResponse).toContain('💡 Consider using specialized tools instead');
             expect(fullResponse).toContain('measure_element');
         });
-        test('should suggest element_visibility for visibility checks', async () => {
+        test('should suggest check_visibility for visibility checks', async () => {
             const args = {
                 script: 'window.getComputedStyle(document.querySelector("#el")).visibility'
             };
@@ -261,7 +265,7 @@ describe('Browser Interaction Tools', () => {
             const fullResponse = result.content.map(c => c.text).join('\n');
             expect(result.isError).toBe(false);
             expect(fullResponse).toContain('💡 Consider using specialized tools instead');
-            expect(fullResponse).toContain('element_visibility');
+            expect(fullResponse).toContain('check_visibility');
         });
         test('should suggest get_computed_styles for getComputedStyle usage', async () => {
             const args = {
@@ -293,7 +297,7 @@ describe('Browser Interaction Tools', () => {
             expect(fullResponse).toContain('💡 Consider using specialized tools instead');
             expect(fullResponse).toContain('get_test_ids');
         });
-        test('should suggest compare_positions for position comparison', async () => {
+        test('should suggest compare_element_alignment for position comparison', async () => {
             const args = {
                 script: 'document.querySelector("#a").getBoundingClientRect().top === document.querySelector("#b").getBoundingClientRect().top'
             };
@@ -301,7 +305,7 @@ describe('Browser Interaction Tools', () => {
             const fullResponse = result.content.map(c => c.text).join('\n');
             expect(result.isError).toBe(false);
             expect(fullResponse).toContain('💡 Consider using specialized tools instead');
-            expect(fullResponse).toContain('compare_positions');
+            expect(fullResponse).toContain('compare_element_alignment');
         });
         test('should suggest scroll tools for scrolling operations', async () => {
             const args = {

package/dist/tools/browser/register.js

@@ -33,7 +33,7 @@ import { GetComputedStylesTool } from './inspection/get_computed_styles.js';
 // Evaluation
 import { EvaluateTool } from './evaluation/evaluate.js';
 // Console
-import { GetConsoleLogsTool } from './console/get_console_logs.js';
+import { GetConsoleLogsTool, ClearConsoleLogsTool } from './console/get_console_logs.js';
 // Network
 import { ListNetworkRequestsTool } from './network/list_network_requests.js';
 import { GetRequestDetailsTool } from './network/get_request_details.js';
@@ -75,8 +75,9 @@ export const BROWSER_TOOL_CLASSES = [
     GetComputedStylesTool,
     // Evaluation (1)
     EvaluateTool,
-    // Console (1)
+    // Console (2)
     GetConsoleLogsTool,
+    ClearConsoleLogsTool,
     // Network (2)
     ListNetworkRequestsTool,
     GetRequestDetailsTool,

package/dist/tools/common/confirmHelpers.d.ts

@@ -0,0 +1,16 @@
+export interface PreviewCounts {
+    totalLength?: number;
+    shownLength?: number;
+    totalMatched?: number;
+    shownCount?: number;
+    truncated?: boolean;
+}
+export declare function makeConfirmPreview(payload: string, options: {
+    headerLine?: string;
+    previewLines: string[];
+    counts?: PreviewCounts;
+    extraTips?: string[];
+}): {
+    token: string;
+    lines: string[];
+};

package/dist/tools/common/confirmHelpers.js

@@ -0,0 +1,37 @@
+import { registerPayload } from './confirmStore.js';
+export function makeConfirmPreview(payload, options) {
+    const token = registerPayload(payload);
+    const lines = [];
+    if (options.headerLine) {
+        lines.push(options.headerLine);
+    }
+    const parts = [];
+    const c = options.counts || {};
+    if (typeof c.totalLength === 'number')
+        parts.push(`totalLength=${c.totalLength}`);
+    if (typeof c.shownLength === 'number')
+        parts.push(`shownLength=${c.shownLength}`);
+    if (typeof c.totalMatched === 'number')
+        parts.push(`totalMatched=${c.totalMatched}`);
+    if (typeof c.shownCount === 'number')
+        parts.push(`shownCount=${c.shownCount}`);
+    if (typeof c.truncated === 'boolean')
+        parts.push(`truncated=${c.truncated}`);
+    if (parts.length) {
+        lines.push(`counts: ${parts.join(', ')}`);
+    }
+    if (lines.length)
+        lines.push('');
+    // Caller provides preview content lines (e.g., label + excerpt or list)
+    for (const l of options.previewLines)
+        lines.push(l);
+    if (options.previewLines.length)
+        lines.push('');
+    const estTokens = Math.round((typeof c.totalLength === 'number' ? c.totalLength : payload.length) / 3);
+    lines.push(`Output is large (~${estTokens} tokens). To fetch full content without resending parameters, call confirm_output({ token: "${token}" }).`);
+    if (options.extraTips && options.extraTips.length) {
+        for (const tip of options.extraTips)
+            lines.push(tip);
+    }
+    return { token, lines };
+}

package/dist/tools/common/confirmStore.d.ts

@@ -0,0 +1,8 @@
+export declare function registerPayload(payload: string, ttlMs?: number): string;
+export declare function consumePayload(token: string): {
+    ok: true;
+    payload: string;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/tools/common/confirmStore.js

@@ -0,0 +1,31 @@
+const STORE = new Map();
+function now() {
+    return Date.now();
+}
+function purgeExpired() {
+    const t = now();
+    for (const [k, v] of STORE.entries()) {
+        if (v.expiresAt <= t)
+            STORE.delete(k);
+    }
+}
+function genToken(len = 12) {
+    return Math.random().toString(36).slice(2, 2 + len);
+}
+export function registerPayload(payload, ttlMs = 120000) {
+    purgeExpired();
+    const token = genToken();
+    const expiresAt = now() + Math.max(1000, ttlMs);
+    STORE.set(token, { payload, expiresAt });
+    return token;
+}
+export function consumePayload(token) {
+    purgeExpired();
+    const entry = STORE.get(token);
+    if (!entry)
+        return { ok: false, error: 'Invalid or expired token' };
+    STORE.delete(token);
+    if (entry.expiresAt <= now())
+        return { ok: false, error: 'Invalid or expired token' };
+    return { ok: true, payload: entry.payload };
+}

package/dist/tools/common/confirm_output.d.ts

@@ -0,0 +1,7 @@
+import type { ToolHandler, ToolContext, ToolResponse, ToolMetadata, SessionConfig } from './types.js';
+export declare class ConfirmOutputTool implements ToolHandler {
+    private server;
+    constructor(server: any);
+    static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/common/confirm_output.js

@@ -0,0 +1,40 @@
+import { createSuccessResponse, createErrorResponse } from './types.js';
+import { consumePayload } from './confirmStore.js';
+export class ConfirmOutputTool {
+    constructor(server) {
+        this.server = server;
+    }
+    static getMetadata(sessionConfig) {
+        return {
+            name: 'confirm_output',
+            description: "Return full output for a previously previewed large result using a one-time token. Use when a tool responded with a preview + token. Safer than resending original parameters.",
+            outputs: [
+                "Full original payload if token is valid (one-time)",
+                "Error: 'Invalid or expired token'",
+            ],
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    token: {
+                        type: 'string',
+                        description: "One-time token obtained from a tool's preview response",
+                    },
+                },
+                required: ['token'],
+            },
+            priority: 2,
+            category: 'Other',
+        };
+    }
+    async execute(args, context) {
+        const token = typeof args.token === 'string' ? args.token : '';
+        if (!token)
+            return createErrorResponse('Token is required');
+        const res = consumePayload(token);
+        if (!res.ok) {
+            const err = res.error;
+            return createErrorResponse(err);
+        }
+        return createSuccessResponse(res.payload);
+    }
+}

package/dist/tools/common/registry.js

@@ -1,6 +1,7 @@
 import { createErrorResponse } from './types.js';
 import { BrowserToolBase } from '../browser/base.js';
 import { BROWSER_TOOL_CLASSES } from '../browser/register.js';
+import { ConfirmOutputTool } from './confirm_output.js';
 const toolClasses = new Map();
 const toolInstances = new Map();
 const browserToolNames = new Set();
@@ -46,3 +47,4 @@ export function clearToolInstances() {
     toolInstances.clear();
 }
 registerTools(BROWSER_TOOL_CLASSES);
+registerTools([ConfirmOutputTool]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-web-inspector",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Web Inspector MCP: Give LLMs visual superpowers to see, debug, and test any web page.",
   "license": "MIT",
   "author": "Anton",