chrome-bridge-mcp 1.9.0 → 1.10.0

package/README.md

@@ -1,6 +1,6 @@
 # Chrome Bridge
 
-![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-128%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
+![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-131%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
 
 **Chrome Bridge is an MCP server that connects Claude Code to your real, logged-in Chrome browser — measured 2.75× fewer turns and 2.28× lower cost than the official "Claude in Chrome" extension on a form-filling task, with ~3× the toolset and no paid plan.**
 
@@ -63,7 +63,7 @@ Claude Code calls `navigate` (returning clickable element refs), `accessibility_
 
 ## Token-Efficient Design
 
-- **Opt-in Surface**: 31 core tools cost ≈5.7k tokens of `tools/list`, all 60 cost ≈10.8k; specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`. That core figure was ≈3.8k in 1.8.0 — MCP annotations on every tool and fuller descriptions added ≈1.8k, deliberately: the win here is fewer round trips, not a smaller prefix (Playwright MCP's 23 core tools measured ≈4.6k in July 2026, so on this metric alone it is now the leaner one). Measure it yourself with `npm run measure`.
+- **Opt-in Surface**: 31 core tools cost ≈7.4k tokens of `tools/list`, all 60 cost ≈14.1k; specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`. That core figure was ≈3.8k in 1.8.0 and roughly doubled in 1.10.0: MCP annotations on every tool, rewritten descriptions, and a documented `.describe()` on all 254 parameters (coverage went from 35% to 100%). The trade is deliberate and it is not free — on the form benchmark it adds ≈8% to the cache-read tokens per turn — but the measured advantage was never prefix size, it was round trips: 2.75× fewer turns. Playwright MCP's 23 core tools measured ≈4.6k in July 2026, so on prefix size alone it is the leaner one. Measure ours with `npm run measure`.
 - **Act-from-Result**: Tools attach a capped preview of interactive elements with short refs. Actions only report a `page_changed` delta when the URL or title actually changes.
 - **Optimized Media**: Screenshots are downscaled to ≤1568px. Full-page captures are sliced into readable segments.
 - **Zero-Token Escape Hatches**: The [CLI](#cli) skips MCP schemas entirely, and recorded flows [replay](#launch-mode-headless--ci) without any model in the loop.

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Bridge your browser to Claude Code: 60 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
   "homepage_url": "https://github.com/frsorrentino/chrome-bridge",
   "minimum_chrome_version": "135",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "MCP server with 60 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",

package/server/protocol.js

@@ -81,7 +81,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.9.0';
+export const VERSION               = '1.10.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;

package/server/tools.js

@@ -185,6 +185,18 @@ export const TOOL_CAPS = {
   files: ['save_page', 'manage_downloads', 'extract_table', 'session_record'],
 };
 
+// Parametri ubiqui: un solo testo, così `tab_id` non significa una cosa in un
+// tool e un'altra nel gemello. test/unit/tool-parameters.test.js lo verifica.
+const selectorField = (extra = '') => z.string()
+  .describe(('CSS selector; ">>>" pierces shadow DOM. ' + extra).trim());
+const waitAfter = z.enum(['none', 'navigation', 'networkidle']).optional().default('none')
+  .describe('Settle before returning: navigation waits for a page load, networkidle for quiet traffic');
+
+const tabId = z.number().optional()
+  .describe('Target tab; omitted = last tab navigated in this session, else the active one');
+const frameId = z.number().optional()
+  .describe('Target iframe id from get_frames; omitted = main frame');
+
 const TOOL_TO_CAP = new Map();
 for (const [group, names] of Object.entries(TOOL_CAPS)) {
   for (const n of names) TOOL_TO_CAP.set(n, group);
@@ -472,8 +484,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'navigate',
     'Navigate a Chrome tab to a URL. Returns a preview of interactive elements with refs usable in click/type_text/hover.',
     {
-      url:    z.string(),
-      tab_id: z.number().optional(),
+      url:    z.string().describe('Absolute URL, or a path resolved against the current page'),
+      tab_id: tabId,
     },
     async ({ url, tab_id }) => {
       const data = await send(MessageType.NAVIGATE, { url, tab_id });
@@ -492,9 +504,11 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- screenshot ---
   server.tool(
     'screenshot',
-    'Screenshot a tab (PNG). Activates the tab in the background without stealing window focus, then restores the previous tab.',
+    'Screenshot of the visible viewport only (PNG), at the current scroll position. Read-only. '
+      + 'Activates the tab in the background without stealing window focus, then restores the previous tab. '
+      + 'Downscaled to ≤1568px, so fine print may not survive.',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.SCREENSHOT, { tab_id });
@@ -522,9 +536,9 @@ export function registerTools(server, wsManager, caps = 'all') {
     'execute_js',
     'Run JavaScript in the page (MAIN world). Requires the extension\'s "Allow user scripts" toggle; errors explain setup if disabled.',
     {
-      code:       z.string(),
-      tab_id:     z.number().optional(),
-      frame_id:   z.number().optional(),
+      code:       z.string().describe('JS evaluated in the page; the value of the last expression is returned'),
+      tab_id:     tabId,
+      frame_id:   frameId,
       max_length: z.number().optional().default(20000).describe('Max output chars'),
     },
     async ({ code, tab_id, frame_id, max_length }) => {
@@ -545,12 +559,12 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'pointer sequence, so it can submit, open a dialog or navigate away — use wait_after to let that settle. '
       + 'Not idempotent, and a click that triggers a native confirm() blocks the bridge: install handle_dialogs first.',
     {
-      selector: z.string().optional(),
+      selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Ignored when ref is given'),
       ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
       force:    z.boolean().optional().default(false).describe('Click even if occluded'),
-      wait_after: z.enum(['none', 'navigation', 'networkidle']).optional().default('none'),
-      tab_id:   z.number().optional(),
-      frame_id: z.number().optional(),
+      wait_after: waitAfter,
+      tab_id:   tabId,
+      frame_id: frameId,
     },
     async ({ selector, ref, force, wait_after, tab_id, frame_id }) => {
       const target = resolveTarget(selector, ref, tab_id);
@@ -574,13 +588,13 @@ export function registerTools(server, wsManager, caps = 'all') {
     'type_text',
     'Type text into an input, by CSS selector or by ref from get_interactives.',
     {
-      selector: z.string().optional(),
+      selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Ignored when ref is given'),
       ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
-      text:     z.string(),
+      text:     z.string().describe('Value to type; empty string clears the field'),
       mode:     z.enum(['set', 'keys']).optional().default('set').describe('set = assign value; keys = per-char events (autocomplete/masked)'),
-      wait_after: z.enum(['none', 'navigation', 'networkidle']).optional().default('none'),
-      tab_id:   z.number().optional(),
-      frame_id: z.number().optional(),
+      wait_after: waitAfter,
+      tab_id:   tabId,
+      frame_id: frameId,
     },
     async ({ selector, ref, text, mode, wait_after, tab_id, frame_id }) => {
       const target = resolveTarget(selector, ref, tab_id);
@@ -603,9 +617,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'HTML on a big table costs tens of thousands of tokens for data you then filter anyway — prefer '
       + 'extract_table or extract for tabular and repeated content, and get_interactives to find click targets.',
     {
-      mode:       z.enum(['text', 'html', 'accessibility']).default('text'),
-      tab_id:     z.number().optional(),
-      frame_id:   z.number().optional(),
+      mode:       z.enum(['text', 'html', 'accessibility']).default('text').describe('text strips markup, html keeps it (costly), accessibility returns the a11y tree'),
+      tab_id:     tabId,
+      frame_id:   frameId,
       max_length: z.number().optional().default(50000).describe('Max output chars'),
     },
     async ({ mode, tab_id, frame_id, max_length }) => {
@@ -624,8 +638,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'get_page_info',
     'Get page metadata: meta tags, scripts, stylesheets, links, and forms',
     {
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ tab_id, frame_id }) => {
       const data = await send(MessageType.GET_PAGE_INFO, { tab_id, frame_id });
@@ -645,8 +659,8 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'Cookies come with domain, path, expiry and the httpOnly/secure flags, so this also answers whether a '
       + 'session cookie is present — write them back with set_storage, or snapshot a logged-in state with session_fixture.',
     {
-      type:   z.enum(['all', 'localStorage', 'sessionStorage', 'cookies']).default('all'),
-      tab_id: z.number().optional(),
+      type:   z.enum(['all', 'localStorage', 'sessionStorage', 'cookies']).default('all').describe('all returns the three together'),
+      tab_id: tabId,
     },
     async ({ type, tab_id }) => {
       const data = await send(MessageType.GET_STORAGE, { type, tab_id });
@@ -664,9 +678,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'get_performance',
     'Navigation timing, paint metrics, JS heap size and per-resource load times, as measured since the current '
       + 'document loaded. Read-only, no reload triggered — numbers are only meaningful once loading has settled, '
-      + 'so on a page still fetching call wait_for(network_idle) first. For CLS/LCP/INP use web_vitals.',
+      + 'so on a page still fetching wait for network idle first. Covers how fast the document arrived, '
+      + 'not the layout-shift and interaction metrics that accumulate afterwards.',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.GET_PERFORMANCE, { tab_id });
@@ -684,11 +699,11 @@ export function registerTools(server, wsManager, caps = 'all') {
     'query_dom',
     'Query DOM elements by CSS selector, returning structure, attributes, bounding rect, and computed styles.',
     {
-      selector: z.string(),
+      selector: z.string().describe('CSS selector; ">>>" pierces shadow DOM. Matches all, not just the first'),
       properties: z.array(z.string()).optional().describe('Computed styles to include, e.g. ["color"]'),
-      limit: z.number().optional().default(50),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      limit: z.number().optional().default(50).describe('Max elements returned, from the top of the match list'),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ selector, properties, limit, tab_id, frame_id }) => {
       const data = await send(MessageType.QUERY_DOM, { selector, properties, limit, tab_id, frame_id });
@@ -708,13 +723,13 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'setTextContent. Nothing is persisted — the next reload restores the page as the server sends it. '
       + 'For styling many elements at once inject_css is one call instead of N.',
     {
-      selector: z.string(),
-      action: z.enum(['setAttribute', 'removeAttribute', 'addClass', 'removeClass', 'setStyle', 'setTextContent']),
+      selector: z.string().describe('CSS selector; ">>>" pierces shadow DOM. Only the first match is changed'),
+      action: z.enum(['setAttribute', 'removeAttribute', 'addClass', 'removeClass', 'setStyle', 'setTextContent']).describe('setStyle takes a CSS declaration in value; addClass/removeClass take className'),
       name: z.string().optional().describe('Attribute name'),
-      value: z.string().optional(),
-      className: z.string().optional(),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      value: z.string().optional().describe('Attribute value, style declaration, or text, per action'),
+      className: z.string().optional().describe('Class to add or remove (addClass/removeClass)'),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ selector, action, name, value, className, tab_id, frame_id }) => {
       const data = await send(MessageType.MODIFY_DOM, { selector, action, name, value, className, tab_id, frame_id });
@@ -733,8 +748,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'Inject a CSS rule into the page. Stays until the next navigation or reload, and re-injecting the same id '
       + 'replaces it rather than stacking. Affects only what is rendered — the stylesheet of the site is untouched.',
     {
-      css: z.string(),
-      tab_id: z.number().optional(),
+      css: z.string().describe('One or more CSS rules, as they would appear in a stylesheet'),
+      tab_id: tabId,
     },
     async ({ css, tab_id }) => {
       const data = await send(MessageType.INJECT_CSS, { css, tab_id });
@@ -753,10 +768,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'Read console messages captured since page load, incl. uncaught errors and unhandled rejections.',
     {
       clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
-      level: z.enum(['all', 'log', 'warn', 'error', 'info', 'debug']).optional().default('all'),
+      level: z.enum(['all', 'log', 'warn', 'error', 'info', 'debug']).optional().default('all').describe('all merges every level in one chronological list'),
       limit: z.number().optional().default(50).describe('Most recent; buffer 1000'),
-      format: z.enum(['lines', 'json']).optional().default('lines'),
-      tab_id: z.number().optional(),
+      format: z.enum(['lines', 'json']).optional().default('lines').describe('lines is compact; json keeps timestamps and stack traces'),
+      tab_id: tabId,
     },
     async ({ clear, level, limit, format, tab_id }) => {
       // limit va all'estensione: taglia in pagina e cancella (con clear) solo
@@ -788,10 +803,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'Monitor network requests. source=page: XHR/fetch hook (installed on first call); source=browser: all requests incl. static assets. format=har exports HAR 1.2.',
     {
       clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
-      source: z.enum(['page', 'browser']).optional().default('page'),
-      format: z.enum(['lines', 'json', 'har']).optional().default('lines'),
+      source: z.enum(['page', 'browser']).optional().default('page').describe('page sees XHR/fetch only; browser also sees static assets'),
+      format: z.enum(['lines', 'json', 'har']).optional().default('lines').describe('har exports HAR 1.2 for external tooling'),
       limit: z.number().optional().default(100).describe('Most recent; buffer 1000'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ clear, source, format, limit, tab_id }) => {
       // limit va all'estensione (taglia in pagina, clear solo del restituito);
@@ -827,7 +842,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'Each call creates another tab: reuse a tab_id or navigate() to move an existing one instead of piling up tabs.',
     {
       url: z.string().optional().describe('URL to open (default: new tab page)'),
-      active: z.boolean().optional().default(true),
+      active: z.boolean().optional().default(true).describe('false opens the tab in the background, leaving the current one focused'),
     },
     async ({ url, active }) => {
       const data = await send(MessageType.CREATE_TAB, { url, active });
@@ -846,7 +861,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'wait_for',
     'Wait for: element (selector in DOM), function (JS expression truthy; needs "Allow user scripts"), navigation (mode=spa for route changes), network_idle.',
     {
-      condition: z.enum(['element', 'function', 'navigation', 'network_idle']),
+      condition: z.enum(['element', 'function', 'navigation', 'network_idle']).describe('function needs expression; element needs selector'),
       selector: z.string().optional().describe('condition=element'),
       expression: z.string().optional().describe('JS expression (condition=function)'),
       visible: z.boolean().optional().default(false).describe('Element must also be visible'),
@@ -854,8 +869,8 @@ export function registerTools(server, wsManager, caps = 'all') {
       idle_ms: z.number().optional().default(500).describe('Quiet period ms (network_idle)'),
       timeout: z.number().optional().describe('Max ms (default 10000; 15000 navigation/network_idle)'),
       interval: z.number().optional().describe('Poll ms, min 50'),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ condition, selector, expression, visible, mode, idle_ms, timeout, interval, tab_id, frame_id }) => {
       let data;
@@ -885,18 +900,18 @@ export function registerTools(server, wsManager, caps = 'all') {
     'scroll',
     'Scroll. action=to: once to element/coordinates; action=until: repeatedly until element visible, network idle, or no new content (infinite scroll).',
     {
-      action: z.enum(['to', 'until']).optional().default('to'),
+      action: z.enum(['to', 'until']).optional().default('to').describe('to jumps to a position or element; until scrolls repeatedly to load more'),
       selector: z.string().optional().describe('Target (to) or stop element (until=element)'),
-      x: z.number().optional(),
-      y: z.number().optional(),
-      behavior: z.enum(['smooth', 'instant', 'auto']).optional().default('auto'),
+      x: z.number().optional().describe('Absolute horizontal position in px (action=to, without selector)'),
+      y: z.number().optional().describe('Absolute vertical position in px (action=to, without selector)'),
+      behavior: z.enum(['smooth', 'instant', 'auto']).optional().default('auto').describe('instant avoids waiting for smooth-scroll animations'),
       offset_y: z.number().optional().default(0).describe('px offset for fixed headers (to)'),
-      until: z.enum(['element', 'network_idle', 'no_new_content']).optional().default('no_new_content'),
-      max_scrolls: z.number().optional().default(20),
+      until: z.enum(['element', 'network_idle', 'no_new_content']).optional().default('no_new_content').describe('no_new_content stops when the page height stops growing'),
+      max_scrolls: z.number().optional().default(20).describe('Cap on scroll steps, so an infinite feed terminates'),
       step_px: z.number().optional().describe('px per step, default viewport height'),
       settle_ms: z.number().optional().default(400).describe('Pause ms after each step'),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional().describe('action=to only'),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ action, selector, x, y, behavior, offset_y, until, max_scrolls, step_px, settle_ms, tab_id, frame_id }) => {
       const data = (action ?? 'to') === 'until'
@@ -913,17 +928,17 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'action=clear wipes every entry of that type for the origin and cannot be undone — on a site the user is '
       + 'logged into, clearing cookies logs them out. Read the current values first with get_storage.',
     {
-      type: z.enum(['localStorage', 'sessionStorage', 'cookie']),
-      action: z.enum(['set', 'delete', 'clear']),
+      type: z.enum(['localStorage', 'sessionStorage', 'cookie']).describe('cookie writes a real cookie, not a storage key'),
+      action: z.enum(['set', 'delete', 'clear']).describe('clear ignores key and wipes every entry of that type'),
       key: z.string().optional().describe('Required for set/delete'),
-      value: z.string().optional(),
+      value: z.string().optional().describe('Required for action=set'),
       path: z.string().optional().describe('Cookie path (default /)'),
       domain: z.string().optional().describe('Cookie domain'),
       expires: z.string().optional().describe('UTC date string (cookie)'),
-      secure: z.boolean().optional(),
-      sameSite: z.enum(['Strict', 'Lax', 'None']).optional(),
-      http_only: z.boolean().optional(),
-      tab_id: z.number().optional(),
+      secure: z.boolean().optional().describe('Cookie sent over HTTPS only'),
+      sameSite: z.enum(['Strict', 'Lax', 'None']).optional().describe('None requires secure=true'),
+      http_only: z.boolean().optional().describe('Cookie hidden from page JS'),
+      tab_id: tabId,
     },
     async ({ type, action, key, value, path, domain, expires, secure, sameSite, http_only, tab_id }) => {
       const data = await send(MessageType.SET_STORAGE, { type, action, key, value, path, domain, expires, secure, sameSite, http_only, tab_id });
@@ -946,9 +961,9 @@ export function registerTools(server, wsManager, caps = 'all') {
         value: z.string(),
       })).describe('{selector, value} pairs'),
       submit_selector: z.string().optional().describe('Submit button to click after filling'),
-      wait_after: z.enum(['none', 'navigation', 'networkidle']).optional().default('none'),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      wait_after: waitAfter,
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ fields, submit_selector, wait_after, tab_id, frame_id }) => {
       const before = await tabSnapshot(tab_id);
@@ -973,7 +988,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       preset: z.enum(['mobile', 'tablet', 'desktop']).optional().describe('375x812, 768x1024, 1440x900'),
       width: z.number().optional().describe('Overrides preset'),
       height: z.number().optional().describe('Overrides preset'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ preset, width, height, tab_id }) => {
       const data = await send(MessageType.VIEWPORT_RESIZE, { preset, width, height, tab_id });
@@ -989,10 +1004,12 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- element_screenshot ---
   server.tool(
     'element_screenshot',
-    'Screenshot a single element (scrolled into view, cropped). PNG.',
+    'Screenshot cropped to one element (PNG), scrolled into view first. Read-only. '
+      + 'The cheapest image in the set, because it carries only the box you asked for: '
+      + 'a component, a chart, a table cell.',
     {
-      selector: z.string(),
-      tab_id: z.number().optional(),
+      selector: z.string().describe('CSS selector; ">>>" pierces shadow DOM. The element is scrolled into view first'),
+      tab_id: tabId,
     },
     async ({ selector, tab_id }) => {
       const data = await send(MessageType.ELEMENT_SCREENSHOT, { selector, tab_id });
@@ -1011,12 +1028,12 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'max_segments are returned and the rest need segment_offset. On a long page, reading the text you actually need '
       + 'is cheaper by an order of magnitude — prefer read_page, extract or find_text unless the layout itself is the question.',
     {
-      max_scrolls: z.number().optional().default(20),
+      max_scrolls: z.number().optional().default(20).describe('Cap on scroll steps: a taller page is captured only up to here'),
       delay: z.number().optional().default(500).describe('ms between captures (min 500, Chrome quota)'),
       stitch: z.boolean().optional().default(true).describe('false = one image per viewport'),
       max_segments: z.number().optional().default(3).describe('Images returned, from the top (each ≈2.7k image tokens); raise or use segment_offset for the rest'),
       segment_offset: z.number().optional().default(0).describe('Skip the first N segments'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ max_scrolls, delay, stitch, max_segments, segment_offset, tab_id }) => {
       const data = await send(MessageType.FULL_PAGE_SCREENSHOT, { max_scrolls, delay, stitch, tab_id });
@@ -1057,12 +1074,12 @@ export function registerTools(server, wsManager, caps = 'all') {
     'highlight_elements',
     'Add colored overlay on elements matching a CSS selector. remove=true clears all highlights.',
     {
-      selector: z.string().optional(),
-      color: z.string().optional().default('rgba(255,0,0,0.3)'),
-      border: z.string().optional().default('2px solid red'),
+      selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Every match is outlined'),
+      color: z.string().optional().default('rgba(255,0,0,0.3)').describe('Any CSS color for the overlay label'),
+      border: z.string().optional().default('2px solid red').describe('CSS border shorthand, e.g. "2px solid red"'),
       label: z.boolean().optional().default(false).describe('Show tag.class (WxH) label'),
-      remove: z.boolean().optional().default(false),
-      tab_id: z.number().optional(),
+      remove: z.boolean().optional().default(false).describe('Remove previously injected highlights instead of adding'),
+      tab_id: tabId,
     },
     async ({ selector, color, border, label, remove, tab_id }) => {
       const data = await send(MessageType.HIGHLIGHT_ELEMENTS, { selector, color, border, label, remove, tab_id });
@@ -1081,8 +1098,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'A11y audit: missing alt, empty links, heading hierarchy, ARIA, contrast (approximate), form labels.',
     {
       scope: z.string().optional().describe('Limit scope (CSS selector)'),
-      checks: z.array(z.enum(['images', 'links', 'headings', 'aria', 'contrast', 'forms', 'all'])).optional().default(['all']),
-      tab_id: z.number().optional(),
+      checks: z.array(z.enum(['images', 'links', 'headings', 'aria', 'contrast', 'forms', 'all'])).optional().default(['all']).describe('Subset to run; fewer checks means a shorter answer'),
+      tab_id: tabId,
     },
     async ({ scope, checks, tab_id }) => {
       const data = await send(MessageType.ACCESSIBILITY_AUDIT, { scope, checks, tab_id });
@@ -1100,12 +1117,12 @@ export function registerTools(server, wsManager, caps = 'all') {
     'check_links',
     'Check page links for broken URLs, verified server-side (no CORS limits, real HTTP status).',
     {
-      scope: z.enum(['same-origin', 'all', 'external']).optional().default('all'),
-      selector: z.string().optional().default('a[href]'),
+      scope: z.enum(['same-origin', 'all', 'external']).optional().default('all').describe('same-origin skips third-party links, which are the slow ones'),
+      selector: z.string().optional().default('a[href]').describe('CSS selector; ">>>" pierces shadow DOM. Restricts which links are collected'),
       timeout: z.number().optional().default(5000).describe('Per-link ms'),
-      max_links: z.number().optional().default(50),
-      format: z.enum(['lines', 'json']).optional().default('lines'),
-      tab_id: z.number().optional(),
+      max_links: z.number().optional().default(50).describe('Cap on links fetched: each one is a real HTTP request'),
+      format: z.enum(['lines', 'json']).optional().default('lines').describe('lines is compact; json keeps per-link status and timing'),
+      tab_id: tabId,
     },
     async ({ scope, selector, timeout, max_links, format, tab_id }) => {
       const data = await send(MessageType.COLLECT_LINKS, { scope, selector, max_links, tab_id });
@@ -1136,9 +1153,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'Read-only. Values come from the current layout, so zoom and viewport size change them: set_zoom(1) and a '
       + 'fixed viewport_resize make results comparable across runs.',
     {
-      selector1: z.string(),
-      selector2: z.string(),
-      tab_id: z.number().optional(),
+      selector1: z.string().describe('First element; distances are measured from its box'),
+      selector2: z.string().describe('Second element; ">>>" pierces shadow DOM'),
+      tab_id: tabId,
     },
     async ({ selector1, selector2, tab_id }) => {
       const data = await send(MessageType.MEASURE_SPACING, { selector1, selector2, tab_id });
@@ -1156,15 +1173,15 @@ export function registerTools(server, wsManager, caps = 'all') {
     'watch_dom',
     'Watch DOM mutations (MutationObserver). First call installs the watcher; later calls read accumulated mutations.',
     {
-      selector: z.string().optional().default('body'),
-      attributes: z.boolean().optional().default(true),
-      childList: z.boolean().optional().default(true),
-      characterData: z.boolean().optional().default(false),
-      subtree: z.boolean().optional().default(true),
+      selector: z.string().optional().default('body').describe('Subtree to observe; ">>>" pierces shadow DOM'),
+      attributes: z.boolean().optional().default(true).describe('Report attribute changes'),
+      childList: z.boolean().optional().default(true).describe('Report added and removed children'),
+      characterData: z.boolean().optional().default(false).describe('Report text content changes'),
+      subtree: z.boolean().optional().default(true).describe('Observe descendants too, not just the matched node'),
       clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
       stop: z.boolean().optional().default(false).describe('Disconnect observer'),
       limit: z.number().optional().default(100).describe('Most recent mutations; buffer 1000'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ selector, attributes, childList, characterData, subtree, clear, stop, limit, tab_id }) => {
       const data = await send(MessageType.WATCH_DOM, { selector, attributes, childList, characterData, subtree, clear, stop, limit, tab_id });
@@ -1185,12 +1202,12 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'user_agent only changes what page JS reads — the request header is a separate thing, set it with '
       + 'network_rules(action=modify_header, header="User-Agent"). Pair with viewport_resize to emulate a device.',
     {
-      colorScheme: z.enum(['dark', 'light', 'no-preference']).optional(),
-      reducedMotion: z.enum(['reduce', 'no-preference']).optional(),
-      printMode: z.boolean().optional().default(false),
+      colorScheme: z.enum(['dark', 'light', 'no-preference']).optional().describe('Value reported to prefers-color-scheme queries'),
+      reducedMotion: z.enum(['reduce', 'no-preference']).optional().describe('Value reported to prefers-reduced-motion queries'),
+      printMode: z.boolean().optional().default(false).describe('Make print media queries match, without opening a print dialog'),
       user_agent: z.string().optional().describe('Overrides navigator.userAgent and appVersion in the page (not the HTTP header)'),
       reset: z.boolean().optional().default(false).describe('Remove all emulations'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ colorScheme, reducedMotion, printMode, user_agent, reset, tab_id }) => {
       const data = await send(MessageType.EMULATE_MEDIA, { colorScheme, reducedMotion, printMode, user_agent, reset, tab_id });
@@ -1208,10 +1225,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'hover',
     'Hover over an element (mouseenter/mouseover), by CSS selector or ref.',
     {
-      selector: z.string().optional(),
+      selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Triggers CSS and JS hover handlers'),
       ref: z.string().optional().describe('From get_interactives'),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ selector, ref, tab_id, frame_id }) => {
       const data = await send(MessageType.HOVER, { selector: resolveTarget(selector, ref, tab_id), tab_id, frame_id });
@@ -1233,12 +1250,12 @@ export function registerTools(server, wsManager, caps = 'all') {
     {
       key: z.string().describe('e.g. "Enter", "Escape", "Tab", "ArrowDown"'),
       selector: z.string().optional().describe('Target (default: activeElement)'),
-      ctrl: z.boolean().optional().default(false),
-      shift: z.boolean().optional().default(false),
-      alt: z.boolean().optional().default(false),
-      meta: z.boolean().optional().default(false),
-      tab_id: z.number().optional(),
-      frame_id: z.number().optional(),
+      ctrl: z.boolean().optional().default(false).describe('Hold Control'),
+      shift: z.boolean().optional().default(false).describe('Hold Shift'),
+      alt: z.boolean().optional().default(false).describe('Hold Alt'),
+      meta: z.boolean().optional().default(false).describe('Hold Meta (Command/Windows)'),
+      tab_id: tabId,
+      frame_id: frameId,
     },
     async ({ key, selector, ctrl, shift, alt, meta, tab_id, frame_id }) => {
       const data = await send(MessageType.PRESS_KEY, { key, selector, ctrl, shift, alt, meta, tab_id, frame_id });
@@ -1256,7 +1273,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'get_frames',
     'List frames (main + iframes) with frameId, parent, URL — for the frame_id parameter of DOM tools.',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.GET_FRAMES, { tab_id });
@@ -1271,9 +1288,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'tab and anything unsaved in it, and cannot be undone — it may be a tab the user is working in. '
       + 'reload and navigation drop injected CSS, emulations and page hooks.',
     {
-      action: z.enum(['close', 'activate', 'reload', 'back', 'forward']),
+      action: z.enum(['close', 'activate', 'reload', 'back', 'forward']).describe('close cannot be undone; reload drops injected CSS and page hooks'),
       bypass_cache: z.boolean().optional().default(false).describe('reload only'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ action, bypass_cache, tab_id }) => {
       const data = await send(MessageType.TAB_ACTION, { action, bypass_cache, tab_id });
@@ -1288,10 +1305,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'upload_file',
     'Set a file on input[type=file] from the server filesystem via DataTransfer (max 10MB).',
     {
-      selector: z.string(),
+      selector: z.string().describe('The file input to fill; ">>>" pierces shadow DOM'),
       path: z.string().describe('Absolute path on the server machine'),
       mime_type: z.string().optional().describe('Default: inferred from extension'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ selector, path, mime_type, tab_id }) => {
       const buf = await readFile(path);
@@ -1309,7 +1326,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'dismiss_overlays',
     'Dismiss cookie banners/modal overlays: OneTrust, Cookiebot, Usercentrics, then generic heuristic. Idempotent.',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.DISMISS_OVERLAYS, { tab_id });
@@ -1322,9 +1339,9 @@ export function registerTools(server, wsManager, caps = 'all') {
     'handle_dialogs',
     'Auto-accept/dismiss future JS dialogs (alert/confirm/prompt), logging them. reset restores native dialogs and returns the log.',
     {
-      action: z.enum(['accept', 'dismiss', 'reset']).optional().default('accept'),
+      action: z.enum(['accept', 'dismiss', 'reset']).optional().default('accept').describe('accept/dismiss auto-answer future dialogs; reset restores native behaviour'),
       prompt_text: z.string().optional().describe('Returned by window.prompt on accept'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ action, prompt_text, tab_id }) => {
       const data = await send(MessageType.HANDLE_DIALOGS, { action, prompt_text, tab_id });
@@ -1337,10 +1354,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'find_text',
     'Find text on the page: parent selector, context, visibility, position per match. Attaches nearby interactive elements (with refs for click/type_text/hover) for the first visible match.',
     {
-      text: z.string(),
-      case_sensitive: z.boolean().optional().default(false),
-      max_results: z.number().optional().default(20),
-      tab_id: z.number().optional(),
+      text: z.string().describe('Literal text to find, not a regex'),
+      case_sensitive: z.boolean().optional().default(false).describe('Match case exactly'),
+      max_results: z.number().optional().default(20).describe('Cap on matches returned, in document order'),
+      tab_id: tabId,
     },
     async ({ text, case_sensitive, max_results, tab_id }) => {
       const data = await send(MessageType.FIND_TEXT, { text, case_sensitive, max_results, tab_id });
@@ -1381,16 +1398,16 @@ export function registerTools(server, wsManager, caps = 'all') {
     'network_rules',
     'Network interception, browser-wide, survives reloads until cleared: block requests, redirect URLs, set/remove request headers, or stub responses with a synthetic body (served by a local helper; from HTTPS pages the stub host must be trustworthy).',
     {
-      action: z.enum(['block', 'redirect', 'modify_header', 'stub', 'list', 'clear']),
+      action: z.enum(['block', 'redirect', 'modify_header', 'stub', 'list', 'clear']).describe('list and clear inspect and drop the rules already installed'),
       url_filter: z.string().optional().describe('declarativeNetRequest urlFilter, e.g. "||example.com/api/*"'),
-      redirect_url: z.string().optional(),
-      header: z.string().optional(),
+      redirect_url: z.string().optional().describe('Destination for action=redirect'),
+      header: z.string().optional().describe('Header name for action=modify_header, e.g. "User-Agent"'),
       header_value: z.string().optional().describe('Omit to remove header'),
       header_target: z.enum(['request', 'response']).optional().default('request').describe("response = strip content-security-policy / x-frame-options, inject CORS"),
       body: z.string().optional().describe('Response body (action=stub)'),
       status: z.number().optional().default(200).describe('action=stub'),
       content_type: z.string().optional().default('application/json').describe('action=stub'),
-      resource_types: z.array(z.enum(['main_frame', 'sub_frame', 'stylesheet', 'script', 'image', 'font', 'object', 'xmlhttprequest', 'ping', 'csp_report', 'media', 'websocket', 'other'])).optional(),
+      resource_types: z.array(z.enum(['main_frame', 'sub_frame', 'stylesheet', 'script', 'image', 'font', 'object', 'xmlhttprequest', 'ping', 'csp_report', 'media', 'websocket', 'other'])).optional().describe('Limit the rule to these request types; omitted = all of them'),
     },
     async ({ action, url_filter, redirect_url, header, header_value, header_target, body, status, content_type, resource_types }) => {
       if (action === 'stub') {
@@ -1417,11 +1434,11 @@ export function registerTools(server, wsManager, caps = 'all') {
     'screenshot_diff',
     'Visual regression: save a named baseline (viewport or element), compare later — returns changed-pixel % and red-highlighted diff image. Baselines are in-memory (lost on service worker restart).',
     {
-      action: z.enum(['baseline', 'compare', 'list', 'clear']),
-      name: z.string().optional().default('default'),
+      action: z.enum(['baseline', 'compare', 'list', 'clear']).describe('baseline stores, compare measures against it, clear drops baselines'),
+      name: z.string().optional().default('default').describe('Baseline id: reuse the same one to compare across runs'),
       selector: z.string().optional().describe('Capture one element (default viewport)'),
       threshold: z.number().optional().default(10).describe('Per-channel tolerance 0-255'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ action, name, selector, threshold, tab_id }) => {
       const data = await send(MessageType.SCREENSHOT_DIFF, { action, name, selector, threshold, tab_id });
@@ -1443,9 +1460,10 @@ export function registerTools(server, wsManager, caps = 'all') {
     'web_vitals',
     'Core Web Vitals accumulated since the current document loaded: CLS, LCP, FCP, TTFB, long tasks and an INP '
       + 'approximation. Read-only. Needs the page instrumentation active from before load, so it reports whether it '
-      + 'was hooked instead of silently returning zeros — navigate() installs it. For timing and resources use get_performance.',
+      + 'was hooked instead of silently returning zeros — navigate() installs it. '
+      + 'Covers user-perceived stability and responsiveness after load, not the load timings themselves.',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.WEB_VITALS, { tab_id });
@@ -1459,8 +1477,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'List addEventListener registrations since page load: counts by type + recent entries.',
     {
       type: z.string().optional().describe('e.g. "click"'),
-      limit: z.number().optional().default(100),
-      tab_id: z.number().optional(),
+      limit: z.number().optional().default(100).describe('Max listeners returned, from the top of the match list'),
+      tab_id: tabId,
     },
     async ({ type, limit, tab_id }) => {
       const data = await send(MessageType.LIST_EVENT_LISTENERS, { type, limit, tab_id });
@@ -1474,7 +1492,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'Monitor WebSocket connections/messages (500-char previews). Hook installs on first call; earlier connections are missed.',
     {
       clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ clear, tab_id }) => {
       const data = await send(MessageType.MONITOR_WEBSOCKET, { clear, tab_id });
@@ -1487,7 +1505,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'seo_audit',
     'SEO audit: title/description lengths, canonical, robots, h1 count, Open Graph, Twitter card, JSON-LD validity, hreflang, lang, viewport, favicon',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.SEO_AUDIT, { tab_id });
@@ -1498,16 +1516,19 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- extract_table ---
   server.tool(
     'extract_table',
-    'Extract an HTML table as JSON (thead headers, rows as objects). Use `where` to pull only matching rows from a large table without reading it all (server-side filter). `row_count` is always the table total; `match_count` is how many rows pass the filter. index picks among multiple matches.',
+    'Read a real <table> as JSON: thead cells become keys, each row an object. Read-only. '
+      + 'Only for tabular markup — `where` filters rows server-side, so one matching row out of 1500 '
+      + 'costs a few hundred bytes instead of the whole document. `row_count` is the table total, '
+      + '`match_count` how many rows passed the filter.',
     {
-      selector: z.string().optional().default('table'),
-      index: z.number().optional().default(0),
+      selector: z.string().optional().default('table').describe('The table to read; ">>>" pierces shadow DOM'),
+      index: z.number().optional().default(0).describe('Which table to take when the selector matches several, 0-based'),
       max_rows: z.number().optional().default(100).describe('Max rows returned to you (output cap).'),
-      where: z.record(z.string(), z.string()).optional().describe('Keep only rows where each {column: substring} matches (case-insensitive contains). Use key "any" (or when the table has no headers) to match against any cell.'),
+      where: z.record(z.string(), z.string()).optional().describe('{column: substring} rows must match, case-insensitive contains. Key "any" matches any cell.'),
       columns: z.array(z.string()).optional().describe('Return only these columns per row.'),
       offset: z.number().optional().default(0).describe('Skip N rows of the (filtered) set before applying max_rows.'),
       scan_rows: z.number().optional().default(2000).describe('Max rows materialized in-page to scan/filter; raise for very large tables.'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ selector, index, max_rows, where, columns, offset, scan_rows, tab_id }) => {
       const data = await send(MessageType.EXTRACT_TABLE, { selector, index, scan_rows, tab_id });
@@ -1521,8 +1542,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'unused_css',
     'List CSS selectors matching nothing in the current DOM (approximate; cross-origin sheets unreadable).',
     {
-      max_selectors: z.number().optional().default(200),
-      tab_id: z.number().optional(),
+      max_selectors: z.number().optional().default(200).describe('Cap on unused selectors reported: a large stylesheet has thousands'),
+      tab_id: tabId,
     },
     async ({ max_selectors, tab_id }) => {
       const data = await send(MessageType.UNUSED_CSS, { max_selectors, tab_id });
@@ -1535,11 +1556,11 @@ export function registerTools(server, wsManager, caps = 'all') {
     'drag_and_drop',
     'Drag an element onto another. html5 = DragEvent+DataTransfer; pointer = pointer/mouse events (sortable libraries).',
     {
-      source_selector: z.string(),
-      target_selector: z.string(),
-      mode: z.enum(['html5', 'pointer']).optional().default('html5'),
-      frame_id: z.number().optional(),
-      tab_id: z.number().optional(),
+      source_selector: z.string().describe('Element to drag; ">>>" pierces shadow DOM'),
+      target_selector: z.string().describe('Drop target; ">>>" pierces shadow DOM'),
+      mode: z.enum(['html5', 'pointer']).optional().default('html5').describe('Which event family to emit, since libraries listen to different ones'),
+      frame_id: frameId,
+      tab_id: tabId,
     },
     async ({ source_selector, target_selector, mode, frame_id, tab_id }) => {
       const data = await send(MessageType.DRAG_AND_DROP, { source_selector, target_selector, mode, frame_id, tab_id });
@@ -1552,9 +1573,9 @@ export function registerTools(server, wsManager, caps = 'all') {
     'clipboard',
     'Read or write the system clipboard (text). Activates the tab first.',
     {
-      action: z.enum(['read', 'write']),
+      action: z.enum(['read', 'write']).describe('write takes text; read returns the current clipboard contents'),
       text: z.string().optional().describe('For write'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ action, text, tab_id }) => {
       const data = await send(MessageType.CLIPBOARD, { action, text, tab_id });
@@ -1567,11 +1588,11 @@ export function registerTools(server, wsManager, caps = 'all') {
     'set_geolocation',
     'Override navigator.geolocation with fixed coordinates (page-level patch). reset restores native.',
     {
-      latitude: z.number().optional(),
-      longitude: z.number().optional(),
+      latitude: z.number().optional().describe('Decimal degrees, -90 to 90'),
+      longitude: z.number().optional().describe('Decimal degrees, -180 to 180'),
       accuracy: z.number().optional().default(10).describe('Meters'),
-      reset: z.boolean().optional().default(false),
-      tab_id: z.number().optional(),
+      reset: z.boolean().optional().default(false).describe('Restore the real position and stop overriding'),
+      tab_id: tabId,
     },
     async ({ latitude, longitude, accuracy, reset, tab_id }) => {
       const data = await send(MessageType.SET_GEOLOCATION, { latitude, longitude, accuracy, reset, tab_id });
@@ -1584,9 +1605,9 @@ export function registerTools(server, wsManager, caps = 'all') {
     'manage_downloads',
     'List downloads or wait for one to complete. Files land in the browser Downloads folder, not on the server.',
     {
-      action: z.enum(['list', 'wait_for_complete']),
+      action: z.enum(['list', 'wait_for_complete']).describe('wait_for_complete blocks until the newest download finishes or times out'),
       timeout: z.number().optional().default(30000).describe('Max ms (wait_for_complete)'),
-      limit: z.number().optional().default(10),
+      limit: z.number().optional().default(10).describe('Max download entries returned, newest first'),
     },
     async ({ action, timeout, limit }) => {
       const data = await send(MessageType.MANAGE_DOWNLOADS, { action, timeout, limit });
@@ -1600,7 +1621,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'Save the full page (DOM, styles, images) as an MHTML archive file on the server filesystem.',
     {
       output_path: z.string().describe('Absolute file path to write (e.g. /tmp/page.mhtml)'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ output_path, tab_id }) => {
       const data = await send(MessageType.SAVE_PAGE, { tab_id });
@@ -1618,7 +1639,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'which is how you read a PDF — Chrome renders PDFs in a viewer no content script can reach, so read_page returns nothing on a PDF tab.',
     {
       url: z.string().describe('Absolute URL. Cookies are sent for its origin'),
-      method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']).optional().default('GET'),
+      method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']).optional().default('GET').describe('HEAD fetches headers only, without the body'),
       headers: z.record(z.string(), z.string()).optional().describe('Extra request headers'),
       body: z.string().optional().describe('Request body (POST/PUT/PATCH)'),
       save_to: z.string().optional().describe('Absolute path: write the response bytes here instead of returning them (PDF, images, archives)'),
@@ -1673,8 +1694,8 @@ export function registerTools(server, wsManager, caps = 'all') {
     'Get or set tab zoom (0.25–5). No factor = read current; reset restores default.',
     {
       factor: z.number().optional().describe('1 = 100%'),
-      reset: z.boolean().optional().default(false),
-      tab_id: z.number().optional(),
+      reset: z.boolean().optional().default(false).describe('Restore the default zoom for this origin'),
+      tab_id: tabId,
     },
     async ({ factor, reset, tab_id }) => {
       const data = await send(MessageType.SET_ZOOM, { factor, reset, tab_id });
@@ -1687,9 +1708,9 @@ export function registerTools(server, wsManager, caps = 'all') {
     'http_auth',
     'Set/clear credentials for HTTP Basic/Digest auth dialogs (browser-wide, in-memory only).',
     {
-      action: z.enum(['set', 'clear']),
-      username: z.string().optional(),
-      password: z.string().optional(),
+      action: z.enum(['set', 'clear']).describe('set installs credentials for HTTP auth prompts; clear removes them'),
+      username: z.string().optional().describe('Required for action=set'),
+      password: z.string().optional().describe('Required for action=set; kept in memory, never written to disk'),
     },
     async ({ action, username, password }) => {
       if (action === 'set' && !username) throw new Error('username is required for action=set');
@@ -1703,7 +1724,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'security_headers',
     'Audit security headers (CSP, HSTS, XCTO, clickjacking, Referrer/Permissions-Policy, version leaks). Captured from real navigations — reload if unavailable.',
     {
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ tab_id }) => {
       const data = await send(MessageType.GET_RESPONSE_HEADERS, { tab_id });
@@ -1721,9 +1742,9 @@ export function registerTools(server, wsManager, caps = 'all') {
     'session_fixture',
     'Save/restore localStorage+sessionStorage+cookies as a named fixture (e.g. a logged-in state). Restore requires the tab to be on the origin recorded at save.',
     {
-      action: z.enum(['save', 'restore', 'list']),
+      action: z.enum(['save', 'restore', 'list']).describe('save snapshots the current origin; restore writes it back'),
       name: z.string().optional().describe('Required for save/restore'),
-      tab_id: z.number().optional(),
+      tab_id: tabId,
     },
     async ({ action, name, tab_id }) => {
       if (action === 'list') {
@@ -1793,11 +1814,12 @@ export function registerTools(server, wsManager, caps = 'all') {
     'List actionable elements (buttons, links, inputs, [role], [onclick]) with ready-to-use CSS selector, label, position, flags. Prefer this over dumping HTML to discover selectors.',
     {
       scope: z.string().optional().describe('Limit search (CSS selector)'),
-      limit: z.number().optional().default(100),
-      visible_only: z.boolean().optional().default(true),
-      format: z.enum(['lines', 'json']).optional().default('lines'),
-      frame_id: z.number().optional(),
-      tab_id: z.number().optional(),
+      limit: z.number().optional().default(100).describe('Max elements returned; raise it on a dense page'),
+      visible_only: z.boolean().optional().default(true)
+        .describe('false also lists elements hidden or scrolled out of view'),
+      format: z.enum(['lines', 'json']).optional().default('lines').describe('lines is compact; json adds full attributes per element'),
+      frame_id: frameId,
+      tab_id: tabId,
     },
     async ({ scope, limit, visible_only, format, frame_id, tab_id }) => {
       const data = await send(MessageType.GET_INTERACTIVES, { scope, limit, visible_only, frame_id, tab_id });
@@ -1823,16 +1845,18 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- extract ---
   server.tool(
     'extract',
-    'Extract repeated structured data (rows, cards, lists) in one call: item_selector matches the items, fields map names to relative selectors. Deterministic, parses the main-document HTML server-side.',
+    'Read repeated non-tabular structures — product cards, list items, search results — as one record per item: '
+      + 'item_selector matches the repeating block, fields map output names to selectors relative to it. '
+      + 'Read-only, deterministic, parsed server-side from the main-document HTML.',
     {
       item_selector: z.string().describe('CSS selector matching each item'),
       fields: z.record(z.string(), z.object({
         selector: z.string().optional().describe('Relative to the item (default: the item itself)'),
         attr: z.string().optional().describe('Attribute to read (default: text content)'),
       })).describe('field name → {selector, attr}'),
-      max_items: z.number().optional().default(50),
-      format: z.enum(['lines', 'json']).optional().default('lines'),
-      tab_id: z.number().optional(),
+      max_items: z.number().optional().default(50).describe('Cap on records returned, in document order'),
+      format: z.enum(['lines', 'json']).optional().default('lines').describe('lines is compact; json keeps one object per record'),
+      tab_id: tabId,
       max_length: z.number().optional().default(20000).describe('Max output chars'),
     },
     async ({ item_selector, fields, max_items, format, tab_id, max_length }) => {
@@ -1866,14 +1890,14 @@ export function registerTools(server, wsManager, caps = 'all') {
     'assert',
     'Assert a page condition, polling until timeout: element exists/visible (optionally with count or containing text), text on page, tab url/title. Patterns: substring, or "/…/" for regex. Recorded flows replay it as a test.',
     {
-      selector: z.string().optional(),
-      state: z.enum(['attached', 'visible']).optional().default('attached'),
+      selector: z.string().optional().describe('Element the assertion is about; ">>>" pierces shadow DOM'),
+      state: z.enum(['attached', 'visible']).optional().default('attached').describe('attached means present in the DOM, visible also requires a rendered box'),
       text: z.string().optional().describe('In the element (with selector) or anywhere on the page'),
       count: z.number().optional().describe('Exact match count for selector'),
       url: z.string().optional().describe('Tab url pattern'),
       title: z.string().optional().describe('Tab title pattern'),
-      timeout: z.number().optional().default(5000),
-      tab_id: z.number().optional(),
+      timeout: z.number().optional().default(5000).describe('Max ms to wait for the condition before failing'),
+      tab_id: tabId,
     },
     async ({ selector, state, text, count, url, title, timeout, tab_id }) => {
       const params = { selector, state, text, count, url, title, timeout, tab_id: tab_id ?? sessionTabId ?? undefined };
@@ -1896,7 +1920,7 @@ export function registerTools(server, wsManager, caps = 'all') {
     'session_record',
     'Record the commands of this session as a replayable jsonl file (replay with the CLI: chrome-bridge replay --file <path>). tab_id is stripped — replays target the tab they navigate.',
     {
-      action: z.enum(['start', 'stop', 'status', 'list']),
+      action: z.enum(['start', 'stop', 'status', 'list']).describe('start begins recording, stop writes the file and returns its path'),
       name: z.string().optional().describe('Required for start'),
     },
     async ({ action, name }) => {