mcp-web-inspector 0.1.0 → 0.1.2

package/README.md

@@ -449,15 +449,6 @@ Detailed visibility diagnostics showing exactly why elements are or aren't visib
 - Detecting elements covered by modals or overlays
 - Checking if elements are clipped by parent containers
 
-#### `get_position`
-Get precise element coordinates and dimensions (x, y, width, height). Shows position relative to viewport.
-
-**Use Cases:**
-- Finding exact click coordinates
-- Checking element layout
-- Calculating distances between elements
-- Debugging overlapping elements
-
 #### `compare_positions`
 Compare positions and alignment of two elements. Validates if elements are aligned (top, left, right, bottom) or have matching dimensions (width, height).
 
@@ -703,8 +694,8 @@ Regular CSS selectors, text selectors (`text=Login`), and Playwright selectors w
    → Found 3 matches, 2 are hidden (display:none)
 3. check_visibility({ selector: ".submit-button:nth-child(1)" })
    → Element is clipped by parent overflow:hidden
-4. get_position({ selector: ".submit-button:nth-child(1)" })
-   → Element is at x:1500, y:300 (outside viewport)
+4. measure_element({ selector: ".submit-button:nth-child(1)" })
+   → @ (1500,300) 100x40px (outside viewport)
 ```
 
 ### Understanding Page Structure
@@ -774,9 +765,9 @@ These step-by-step recipes show how to chain tools together for common testing a
 1. navigate({ url: "https://dashboard.example.com" })
 2. inspect_dom({ selector: "testid:sidebar" })
    → Understand the structure of the problematic area
-3. get_position({ selector: "testid:logo" })
+3. measure_element({ selector: "testid:logo" })
    → @ (20,10) 150x40px
-4. get_position({ selector: "testid:menu" })
+4. measure_element({ selector: "testid:menu" })
    → @ (20,60) 200x300px
 5. compare_positions({
      selector1: "testid:logo",
@@ -870,9 +861,9 @@ These step-by-step recipes show how to chain tools together for common testing a
      checkAlignment: "height"
    })
    → ✗ not aligned (difference: 20px)
-5. get_position({ selector: ".card:nth-child(1)" })
+5. measure_element({ selector: ".card:nth-child(1)" })
    → @ (20,100) 400x300px
-6. get_position({ selector: ".card:nth-child(2)" })
+6. measure_element({ selector: ".card:nth-child(2)" })
    → @ (440,100) 400x320px  ← 20px taller!
 ```
 
@@ -926,7 +917,7 @@ These step-by-step recipes show how to chain tools together for common testing a
 3. wait_for_element({ selector: "testid:tooltip", state: "visible", timeout: 2000 })
 4. check_visibility({ selector: "testid:tooltip" })
    → ✓ visible
-5. get_position({ selector: "testid:tooltip" })
+5. measure_element({ selector: "testid:tooltip" })
    → @ (300,150) 200x50px
 6. get_computed_styles({
      selector: "testid:tooltip",

package/dist/toolHandler.js

@@ -4,7 +4,6 @@ import { ScreenshotTool, NavigationTool, CloseBrowserTool, ConsoleLogsTool } fro
 import { ClickTool, FillTool, SelectTool, HoverTool, EvaluateTool, UploadFileTool } from './tools/browser/interaction.js';
 import { VisibleTextTool, VisibleHtmlTool } from './tools/browser/visiblePage.js';
 import { ElementVisibilityTool } from './tools/browser/elementVisibility.js';
-import { ElementPositionTool } from './tools/browser/elementPosition.js';
 import { InspectDomTool } from './tools/browser/inspectDom.js';
 import { GetTestIdsTool } from './tools/browser/getTestIds.js';
 import { QuerySelectorAllTool } from './tools/browser/querySelectorAll.js';
@@ -12,7 +11,7 @@ import { FindByTextTool } from './tools/browser/findByText.js';
 import { GetComputedStylesTool } from './tools/browser/computedStyles.js';
 import { MeasureElementTool } from './tools/browser/measureElement.js';
 import { ElementExistsTool } from './tools/browser/elementExists.js';
-import { ComparePositionsTool } from './tools/browser/comparePositions.js';
+import { CompareElementAlignmentTool } from './tools/browser/compareElementAlignment.js';
 import { GoBackTool, GoForwardTool } from './tools/browser/navigation.js';
 import { DragTool, PressKeyTool } from './tools/browser/interaction.js';
 import { WaitForElementTool } from './tools/browser/waitForElement.js';
@@ -90,7 +89,6 @@ let goForwardTool;
 let dragTool;
 let pressKeyTool;
 let elementVisibilityTool;
-let elementPositionTool;
 let inspectDomTool;
 let getTestIdsTool;
 let querySelectorAllTool;
@@ -98,7 +96,7 @@ let findByTextTool;
 let getComputedStylesTool;
 let measureElementTool;
 let elementExistsTool;
-let comparePositionsTool;
+let compareElementAlignmentTool;
 let waitForElementTool;
 let waitForNetworkIdleTool;
 let listNetworkRequestsTool;
@@ -219,6 +217,21 @@ export async function ensureBrowser(browserSettings) {
             // Reset browser and page references
             resetBrowserState();
         }
+        // If browser exists and viewport settings changed, resize the viewport
+        if (browser && page && !page.isClosed() && browserSettings?.viewport) {
+            const { width, height } = browserSettings.viewport;
+            // Only resize if width or height are explicitly provided
+            if (width !== undefined || height !== undefined) {
+                const currentViewport = page.viewportSize();
+                const targetWidth = width ?? currentViewport?.width ?? 1280;
+                const targetHeight = height ?? currentViewport?.height ?? 720;
+                // Check if viewport size actually changed
+                if (!currentViewport || currentViewport.width !== targetWidth || currentViewport.height !== targetHeight) {
+                    console.error(`Resizing viewport to ${targetWidth}x${targetHeight}`);
+                    await page.setViewportSize({ width: targetWidth, height: targetHeight });
+                }
+            }
+        }
         // Launch new browser if needed
         if (!browser) {
             const { viewport, userAgent, headless = false, browserType = 'chromium', device } = browserSettings ?? {};
@@ -483,8 +496,6 @@ function initializeTools(server) {
         pressKeyTool = new PressKeyTool(server);
     if (!elementVisibilityTool)
         elementVisibilityTool = new ElementVisibilityTool(server);
-    if (!elementPositionTool)
-        elementPositionTool = new ElementPositionTool(server);
     if (!inspectDomTool)
         inspectDomTool = new InspectDomTool(server);
     if (!getTestIdsTool)
@@ -499,8 +510,8 @@ function initializeTools(server) {
         measureElementTool = new MeasureElementTool(server);
     if (!elementExistsTool)
         elementExistsTool = new ElementExistsTool(server);
-    if (!comparePositionsTool)
-        comparePositionsTool = new ComparePositionsTool(server);
+    if (!compareElementAlignmentTool)
+        compareElementAlignmentTool = new CompareElementAlignmentTool(server);
     if (!waitForElementTool)
         waitForElementTool = new WaitForElementTool(server);
     if (!waitForNetworkIdleTool)
@@ -626,8 +637,6 @@ export async function handleToolCall(name, args, server) {
                 return await pressKeyTool.execute(args, context);
             case "check_visibility":
                 return await elementVisibilityTool.execute(args, context);
-            case "get_position":
-                return await elementPositionTool.execute(args, context);
             case "inspect_dom":
                 return await inspectDomTool.execute(args, context);
             case "get_test_ids":
@@ -642,8 +651,8 @@ export async function handleToolCall(name, args, server) {
                 return await measureElementTool.execute(args, context);
             case "element_exists":
                 return await elementExistsTool.execute(args, context);
-            case "compare_positions":
-                return await comparePositionsTool.execute(args, context);
+            case "compare_element_alignment":
+                return await compareElementAlignmentTool.execute(args, context);
             case "wait_for_element":
                 return await waitForElementTool.execute(args, context);
             case "wait_for_network_idle":

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

@@ -0,0 +1,11 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for comparing alignment of two elements
+ */
+export declare class CompareElementAlignmentTool extends BrowserToolBase {
+    /**
+     * Execute the compare element alignment tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/compareElementAlignment.js

@@ -0,0 +1,171 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for comparing alignment of two elements
+ */
+export class CompareElementAlignmentTool extends BrowserToolBase {
+    /**
+     * Execute the compare element alignment tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const selector1 = this.normalizeSelector(args.selector1);
+            const selector2 = this.normalizeSelector(args.selector2);
+            try {
+                // Get locators for both elements
+                const locator1 = page.locator(selector1);
+                const locator2 = page.locator(selector2);
+                // Check if both elements exist
+                const count1 = await locator1.count();
+                const count2 = await locator2.count();
+                if (count1 === 0) {
+                    return createErrorResponse(`First element not found: ${args.selector1}`);
+                }
+                if (count2 === 0) {
+                    return createErrorResponse(`Second element not found: ${args.selector2}`);
+                }
+                // Handle multiple matches by using first() - show warning
+                const targetLocator1 = count1 > 1 ? locator1.first() : locator1;
+                const targetLocator2 = count2 > 1 ? locator2.first() : locator2;
+                let warnings = '';
+                if (count1 > 1) {
+                    warnings += `⚠ Warning: First selector matched ${count1} elements, using first\n`;
+                }
+                if (count2 > 1) {
+                    warnings += `⚠ Warning: Second selector matched ${count2} elements, using first\n`;
+                }
+                if (warnings) {
+                    warnings += '\n';
+                }
+                // Get bounding boxes
+                const box1 = await targetLocator1.boundingBox();
+                const box2 = await targetLocator2.boundingBox();
+                // Get element descriptors
+                const getDescriptor = async (locator) => {
+                    return await locator.evaluate((element) => {
+                        const tagName = element.tagName.toLowerCase();
+                        const testId = element.getAttribute('data-testid') || element.getAttribute('data-test') || element.getAttribute('data-cy');
+                        const id = element.id ? `#${element.id}` : '';
+                        const classes = element.className && typeof element.className === 'string'
+                            ? `.${element.className.split(' ').filter(c => c).join('.')}`
+                            : '';
+                        let descriptor = `<${tagName}`;
+                        if (testId)
+                            descriptor += ` data-testid="${testId}"`;
+                        else if (id)
+                            descriptor += id;
+                        else if (classes)
+                            descriptor += classes;
+                        descriptor += '>';
+                        return descriptor;
+                    });
+                };
+                const descriptor1 = await getDescriptor(targetLocator1);
+                const descriptor2 = await getDescriptor(targetLocator2);
+                // Handle hidden elements
+                if (!box1) {
+                    return createErrorResponse(`First element is hidden or has no dimensions: ${descriptor1}`);
+                }
+                if (!box2) {
+                    return createErrorResponse(`Second element is hidden or has no dimensions: ${descriptor2}`);
+                }
+                // Extract short name from descriptor for compact output
+                const getShortName = (descriptor, selector) => {
+                    const testIdMatch = descriptor.match(/data-testid="([^"]+)"/);
+                    if (testIdMatch)
+                        return testIdMatch[1];
+                    const idMatch = descriptor.match(/#([^>]+)/);
+                    if (idMatch)
+                        return idMatch[1];
+                    // Use original selector if available
+                    return selector;
+                };
+                const name1 = getShortName(descriptor1, args.selector1);
+                const name2 = getShortName(descriptor2, args.selector2);
+                // Calculate all alignment values
+                const tolerance = 2; // Allow 2px tolerance for rounding
+                // Edge positions
+                const top1 = Math.round(box1.y);
+                const top2 = Math.round(box2.y);
+                const topDiff = Math.abs(top1 - top2);
+                const topAligned = topDiff <= tolerance;
+                const left1 = Math.round(box1.x);
+                const left2 = Math.round(box2.x);
+                const leftDiff = Math.abs(left1 - left2);
+                const leftAligned = leftDiff <= tolerance;
+                const right1 = Math.round(box1.x + box1.width);
+                const right2 = Math.round(box2.x + box2.width);
+                const rightDiff = Math.abs(right1 - right2);
+                const rightAligned = rightDiff <= tolerance;
+                const bottom1 = Math.round(box1.y + box1.height);
+                const bottom2 = Math.round(box2.y + box2.height);
+                const bottomDiff = Math.abs(bottom1 - bottom2);
+                const bottomAligned = bottomDiff <= tolerance;
+                // Center positions
+                const centerH1 = Math.round(box1.x + box1.width / 2);
+                const centerH2 = Math.round(box2.x + box2.width / 2);
+                const centerHDiff = Math.abs(centerH1 - centerH2);
+                const centerHAligned = centerHDiff <= tolerance;
+                const centerV1 = Math.round(box1.y + box1.height / 2);
+                const centerV2 = Math.round(box2.y + box2.height / 2);
+                const centerVDiff = Math.abs(centerV1 - centerV2);
+                const centerVAligned = centerVDiff <= tolerance;
+                // Dimensions
+                const width1 = Math.round(box1.width);
+                const width2 = Math.round(box2.width);
+                const widthDiff = Math.abs(width1 - width2);
+                const widthSame = widthDiff <= tolerance;
+                const height1 = Math.round(box1.height);
+                const height2 = Math.round(box2.height);
+                const heightDiff = Math.abs(height1 - height2);
+                const heightSame = heightDiff <= tolerance;
+                // Format compact output
+                const formatAlignment = (aligned, val1, val2, diff, unit = 'px') => {
+                    const symbol = aligned ? '✓' : '✗';
+                    const status = aligned ? 'aligned' : 'not aligned';
+                    if (aligned) {
+                        return `${symbol} ${status} (both @ ${val1}${unit})`;
+                    }
+                    else {
+                        return `${symbol} ${status} (${val1}${unit} vs ${val2}${unit}, diff: ${diff}${unit})`;
+                    }
+                };
+                const formatDimension = (same, val1, val2, diff, unit = 'px') => {
+                    const symbol = same ? '✓' : '✗';
+                    const status = same ? 'same' : 'different';
+                    if (same) {
+                        return `${symbol} ${status} (${val1}${unit})`;
+                    }
+                    else {
+                        return `${symbol} ${status} (${val1}${unit} vs ${val2}${unit}, diff: ${diff}${unit})`;
+                    }
+                };
+                // Build output
+                const lines = [
+                    warnings,
+                    `Alignment: ${descriptor1} vs ${descriptor2}`,
+                    `  ${name1}: @ (${left1},${top1}) ${width1}×${height1}px`,
+                    `  ${name2}: @ (${left2},${top2}) ${width2}×${height2}px`,
+                    '',
+                    'Edges:',
+                    `  Top:    ${formatAlignment(topAligned, top1, top2, topDiff)}`,
+                    `  Left:   ${formatAlignment(leftAligned, left1, left2, leftDiff)}`,
+                    `  Right:  ${formatAlignment(rightAligned, right1, right2, rightDiff)}`,
+                    `  Bottom: ${formatAlignment(bottomAligned, bottom1, bottom2, bottomDiff)}`,
+                    '',
+                    'Centers:',
+                    `  Horizontal: ${formatAlignment(centerHAligned, centerH1, centerH2, centerHDiff)}`,
+                    `  Vertical:   ${formatAlignment(centerVAligned, centerV1, centerV2, centerVDiff)}`,
+                    '',
+                    'Dimensions:',
+                    `  Width:  ${formatDimension(widthSame, width1, width2, widthDiff)}`,
+                    `  Height: ${formatDimension(heightSame, height1, height2, heightDiff)}`
+                ];
+                return createSuccessResponse(lines.filter(l => l !== undefined).join('\n'));
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to compare element alignment: ${error.message}`);
+            }
+        });
+    }
+}

package/dist/tools/browser/inspectDom.js

@@ -391,6 +391,13 @@ export class InspectDomTool extends BrowserToolBase {
                         lines.push(`${prefix} ${tag}${roleInfo}`);
                         // Position
                         lines.push(`    @ (${child.position.x},${child.position.y}) ${child.position.width}x${child.position.height}px`);
+                        // Calculate distances from all parent edges
+                        const fromLeft = child.position.x - target.position.x;
+                        const fromRight = (target.position.x + target.position.width) - (child.position.x + child.position.width);
+                        const fromTop = child.position.y - target.position.y;
+                        const fromBottom = (target.position.y + target.position.height) - (child.position.y + child.position.height);
+                        // Format edge distances (centering is obvious: equal left/right = horizontal center, equal top/bottom = vertical center)
+                        lines.push(`    from edges: ←${fromLeft}px →${fromRight}px ↑${fromTop}px ↓${fromBottom}px`);
                         // Calculate offset from previous sibling
                         if (index > 0) {
                             const prev = children[index - 1];

package/dist/tools.d.ts

@@ -48,7 +48,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "screenshot";
-    readonly description: `Take a screenshot of the current page or a specific element. Screenshots are saved to ${string} by default. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`;
+    readonly description: `\u26A0\uFE0F RARELY NEEDED: Screenshots are NOT useful for LLMs to analyze layouts, margins, or alignment issues. Use inspect_dom(), compare_positions(), or measure_element() instead - they provide precise numerical data. Only take screenshots for: (1) sharing with humans for visual confirmation, (2) documenting test results, or (3) verifying colors/images. Screenshots are saved to ${string}. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`;
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -150,7 +150,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "evaluate";
-    readonly description: "Execute JavaScript in the browser console";
+    readonly description: "Execute JavaScript in the browser console. ⚠️ AVOID for common tasks - use specialized tools instead: inspect_dom() for page structure, compare_positions() for alignment, measure_element() for spacing, query_selector() for finding elements. Only use evaluate() for custom logic not covered by other tools.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -210,7 +210,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "get_html";
-    readonly description: "Get the HTML content of the current page. By default, all <script> tags are removed from the output unless removeScripts is explicitly set to false.";
+    readonly description: "Get raw HTML content of the page or specific element. ⚠️ For understanding page structure, use inspect_dom() instead - it's more efficient and filters out noise. Use get_html() only when you need the actual HTML markup (e.g., to check specific attributes or element nesting).";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -312,22 +312,9 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
         };
         readonly required: readonly ["selector"];
     };
-}, {
-    readonly name: "get_position";
-    readonly description: "Get the position and size of an element. Returns x, y coordinates and width/height in pixels. Useful for finding where to click or checking element layout. Supports testid shortcuts (e.g., 'testid:submit-button').";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly selector: {
-                readonly type: "string";
-                readonly description: "CSS selector, text selector, or testid shorthand (e.g., 'testid:login-button', '#submit', 'text=Click here')";
-            };
-        };
-        readonly required: readonly ["selector"];
-    };
 }, {
     readonly name: "inspect_dom";
-    readonly description: "Progressive DOM inspection with semantic filtering and spatial layout info. This is the PRIMARY tool for understanding page structure. Returns immediate semantic children only (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.) while automatically drilling through non-semantic wrapper elements (div, span, etc.) up to maxDepth levels. Use without selector for page overview, then drill down by calling again with a child's selector. Returns compact text format with position, visibility, and layout pattern detection. Supports testid shortcuts.";
+    readonly description: "START HERE FOR LAYOUT DEBUGGING: Progressive DOM inspection that shows parent-child relationships, centering issues, and spacing gaps. Skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.).\n\nWORKFLOW: Call without selector for page overview, then drill down by calling with child's selector.\n\nDETECTS: Parent-relative positioning, vertical/horizontal centering, sibling spacing gaps, layout patterns.\n\nOUTPUT FORMAT:\n[0] <button data-testid=\"menu\">\n    @ (16,8) 40×40px                         ← Absolute viewport position (x,y) and size\n    from edges: ←16px →1144px ↑8px ↓8px      ← Distance from parent edges (↑8px = ↓8px means vertically centered)\n    \"Menu\"\n    ✓ visible, ⚡ interactive\n\n[1] <div data-testid=\"title\">\n    @ (260,2) 131×28px\n    from edges: ←244px →244px ↑2px ↓42px     ← Equal left/right (244px) = horizontally centered, unequal top/bottom = NOT vertically centered\n    gap from [0]: →16px                      ← Spacing between siblings\n    \"Title\"\n    ✓ visible, 2 children\n\nSYMBOLS: ✓=visible, ✗=hidden, ⚡=interactive, ←→=horizontal edges, ↑↓=vertical edges\nCENTERING: Equal left/right distances = horizontally centered, equal top/bottom = vertically centered\n\nRELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use compare_element_alignment(). For box model (padding/margin), use measure_element().\n\nMore efficient than get_html() or evaluate(). Supports testid shortcuts.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -423,7 +410,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "get_computed_styles";
-    readonly description: "Get computed CSS styles for an element. Essential for understanding why elements behave unexpectedly and debugging layout issues. Returns styles grouped by category (Layout, Visibility, Spacing, Typography). Use properties parameter to request specific CSS properties, or omit for common layout properties.";
+    readonly description: "INSPECT CSS PROPERTIES: Get computed CSS values for specific properties (display, position, width, etc.). Use when you need raw CSS values or specific properties not shown by measure_element(). Returns styles grouped by category (Layout, Visibility, Spacing, Typography). For box model visualization (padding/margin), use measure_element() instead.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -440,7 +427,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "measure_element";
-    readonly description: "Get box model measurements (position, size, margin, padding, border) for an element. Use for layout debugging, spacing validation, and understanding CSS box model. Returns compact visual representation of content, padding, border, and margin with directional arrows.";
+    readonly description: "DEBUG SPACING ISSUES: See padding, margin, and border measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content → padding → border → margin with directional arrows (↑24px for top margin, etc.). For parent-child centering issues, use inspect_dom() first (shows if child is centered in parent). For comparing alignment between two elements, use compare_element_alignment(). More readable than get_computed_styles() for box model debugging.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -465,8 +452,8 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
         readonly required: readonly ["selector"];
     };
 }, {
-    readonly name: "compare_positions";
-    readonly description: "Compare positions and alignment of two elements. Validates layout consistency by checking if elements are aligned (top, left, right, bottom) or have the same dimensions (width, height). Essential for visual regression testing and ensuring consistent spacing across components. Returns compact text format with alignment status and difference in pixels.";
+    readonly name: "compare_element_alignment";
+    readonly description: "COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in one call. Shows edge alignment (top, left, right, bottom), center alignment (horizontal, vertical), and dimensions (width, height). Perfect for debugging 'are these headers aligned?' or 'do these panels match?'. Returns all alignment info with ✓/✗ symbols and pixel differences. For parent-child centering, use inspect_dom() instead (automatically shows if children are centered in parent). More efficient than evaluate() with manual getBoundingClientRect() calculations.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -478,13 +465,8 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
                 readonly type: "string";
                 readonly description: "CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')";
             };
-            readonly checkAlignment: {
-                readonly type: "string";
-                readonly description: "What to check: 'top', 'left', 'right', 'bottom' (edge alignment), or 'width', 'height' (dimension matching)";
-                readonly enum: readonly ["top", "left", "right", "bottom", "width", "height"];
-            };
         };
-        readonly required: readonly ["selector1", "selector2", "checkAlignment"];
+        readonly required: readonly ["selector1", "selector2"];
     };
 }, {
     readonly name: "wait_for_element";

package/dist/tools.js

@@ -31,7 +31,7 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "screenshot",
-            description: `Take a screenshot of the current page or a specific element. Screenshots are saved to ${screenshotsDir} by default. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`,
+            description: `⚠️ RARELY NEEDED: Screenshots are NOT useful for LLMs to analyze layouts, margins, or alignment issues. Use inspect_dom(), compare_positions(), or measure_element() instead - they provide precise numerical data. Only take screenshots for: (1) sharing with humans for visual confirmation, (2) documenting test results, or (3) verifying colors/images. Screenshots are saved to ${screenshotsDir}. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -115,7 +115,7 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "evaluate",
-            description: "Execute JavaScript in the browser console",
+            description: "Execute JavaScript in the browser console. ⚠️ AVOID for common tasks - use specialized tools instead: inspect_dom() for page structure, compare_positions() for alignment, measure_element() for spacing, query_selector() for finding elements. Only use evaluate() for custom logic not covered by other tools.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -176,7 +176,7 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "get_html",
-            description: "Get the HTML content of the current page. By default, all <script> tags are removed from the output unless removeScripts is explicitly set to false.",
+            description: "Get raw HTML content of the page or specific element. ⚠️ For understanding page structure, use inspect_dom() instead - it's more efficient and filters out noise. Use get_html() only when you need the actual HTML markup (e.g., to check specific attributes or element nesting).",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -248,23 +248,34 @@ export function createToolDefinitions(sessionConfig) {
                 required: ["selector"],
             },
         },
-        {
-            name: "get_position",
-            description: "Get the position and size of an element. Returns x, y coordinates and width/height in pixels. Useful for finding where to click or checking element layout. Supports testid shortcuts (e.g., 'testid:submit-button').",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    selector: {
-                        type: "string",
-                        description: "CSS selector, text selector, or testid shorthand (e.g., 'testid:login-button', '#submit', 'text=Click here')"
-                    },
-                },
-                required: ["selector"],
-            },
-        },
         {
             name: "inspect_dom",
-            description: "Progressive DOM inspection with semantic filtering and spatial layout info. This is the PRIMARY tool for understanding page structure. Returns immediate semantic children only (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.) while automatically drilling through non-semantic wrapper elements (div, span, etc.) up to maxDepth levels. Use without selector for page overview, then drill down by calling again with a child's selector. Returns compact text format with position, visibility, and layout pattern detection. Supports testid shortcuts.",
+            description: `START HERE FOR LAYOUT DEBUGGING: Progressive DOM inspection that shows parent-child relationships, centering issues, and spacing gaps. Skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.).
+
+WORKFLOW: Call without selector for page overview, then drill down by calling with child's selector.
+
+DETECTS: Parent-relative positioning, vertical/horizontal centering, sibling spacing gaps, layout patterns.
+
+OUTPUT FORMAT:
+[0] <button data-testid="menu">
+    @ (16,8) 40×40px                         ← Absolute viewport position (x,y) and size
+    from edges: ←16px →1144px ↑8px ↓8px      ← Distance from parent edges (↑8px = ↓8px means vertically centered)
+    "Menu"
+    ✓ visible, ⚡ interactive
+
+[1] <div data-testid="title">
+    @ (260,2) 131×28px
+    from edges: ←244px →244px ↑2px ↓42px     ← Equal left/right (244px) = horizontally centered, unequal top/bottom = NOT vertically centered
+    gap from [0]: →16px                      ← Spacing between siblings
+    "Title"
+    ✓ visible, 2 children
+
+SYMBOLS: ✓=visible, ✗=hidden, ⚡=interactive, ←→=horizontal edges, ↑↓=vertical edges
+CENTERING: Equal left/right distances = horizontally centered, equal top/bottom = vertically centered
+
+RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use compare_element_alignment(). For box model (padding/margin), use measure_element().
+
+More efficient than get_html() or evaluate(). Supports testid shortcuts.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -364,7 +375,7 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "get_computed_styles",
-            description: "Get computed CSS styles for an element. Essential for understanding why elements behave unexpectedly and debugging layout issues. Returns styles grouped by category (Layout, Visibility, Spacing, Typography). Use properties parameter to request specific CSS properties, or omit for common layout properties.",
+            description: "INSPECT CSS PROPERTIES: Get computed CSS values for specific properties (display, position, width, etc.). Use when you need raw CSS values or specific properties not shown by measure_element(). Returns styles grouped by category (Layout, Visibility, Spacing, Typography). For box model visualization (padding/margin), use measure_element() instead.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -382,7 +393,7 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "measure_element",
-            description: "Get box model measurements (position, size, margin, padding, border) for an element. Use for layout debugging, spacing validation, and understanding CSS box model. Returns compact visual representation of content, padding, border, and margin with directional arrows.",
+            description: "DEBUG SPACING ISSUES: See padding, margin, and border measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content → padding → border → margin with directional arrows (↑24px for top margin, etc.). For parent-child centering issues, use inspect_dom() first (shows if child is centered in parent). For comparing alignment between two elements, use compare_element_alignment(). More readable than get_computed_styles() for box model debugging.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -409,8 +420,8 @@ export function createToolDefinitions(sessionConfig) {
             },
         },
         {
-            name: "compare_positions",
-            description: "Compare positions and alignment of two elements. Validates layout consistency by checking if elements are aligned (top, left, right, bottom) or have the same dimensions (width, height). Essential for visual regression testing and ensuring consistent spacing across components. Returns compact text format with alignment status and difference in pixels.",
+            name: "compare_element_alignment",
+            description: "COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in one call. Shows edge alignment (top, left, right, bottom), center alignment (horizontal, vertical), and dimensions (width, height). Perfect for debugging 'are these headers aligned?' or 'do these panels match?'. Returns all alignment info with ✓/✗ symbols and pixel differences. For parent-child centering, use inspect_dom() instead (automatically shows if children are centered in parent). More efficient than evaluate() with manual getBoundingClientRect() calculations.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -421,14 +432,9 @@ export function createToolDefinitions(sessionConfig) {
                     selector2: {
                         type: "string",
                         description: "CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')"
-                    },
-                    checkAlignment: {
-                        type: "string",
-                        description: "What to check: 'top', 'left', 'right', 'bottom' (edge alignment), or 'width', 'height' (dimension matching)",
-                        enum: ["top", "left", "right", "bottom", "width", "height"]
                     }
                 },
-                required: ["selector1", "selector2", "checkAlignment"],
+                required: ["selector1", "selector2"],
             },
         },
         {
@@ -516,8 +522,7 @@ export const BROWSER_TOOLS = [
     "find_by_text",
     // Visibility & Position
     "check_visibility",
-    "get_position",
-    "compare_positions",
+    "compare_element_alignment",
     "element_exists",
     "wait_for_element",
     "wait_for_network_idle",

package/package.json

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