chrome-bridge-mcp 1.8.0 → 1.9.0

package/README.md

@@ -1,10 +1,10 @@
 # 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-109%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-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)
 
 **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.**
 
-By using a local WebSocket bridge and a specialized Chrome extension, Chrome Bridge provides 59 web-development tools (navigation, DOM inspection, visual regression, audits, network mocking) and a dedicated headless instance for CI. It is self-hosted, local-only, and requires no paid plan.
+By using a local WebSocket bridge and a specialized Chrome extension, Chrome Bridge provides 60 web-development tools (navigation, DOM inspection, visual regression, audits, network mocking) and a dedicated headless instance for CI. It is self-hosted, local-only, and requires no paid plan.
 
 ## Why Chrome Bridge?
 
@@ -31,12 +31,12 @@ unfavourable ones) and the harness limits are in
 - **Honest caveat:** per *turn*, Chrome Bridge costs slightly more than Claude in Chrome (41,985 vs 36,613 cache-read tokens; $0.0373 vs $0.0337). The win is in the number of turns.
 
 ### 2. Feature Comparison
-Chrome Bridge ships 59 specialized tools (30 core by default) compared to ~20 in Claude in Chrome. It is also the only automation that drives the real host Chrome on ChromeOS/Crostini.
+Chrome Bridge ships 60 specialized tools (31 core by default) compared to ~20 in Claude in Chrome. It is also the only automation that drives the real host Chrome on ChromeOS/Crostini.
 
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **59** (30 core) | ~20 | ~50 | 23 core (71 total) |
+| **Tools** | **60** (31 core) | ~20 | ~50 | 23 core (71 total) |
 | **Requires Paid Plan** | **No** | Yes (Pro+) | No | No |
 | **Network Mocking** | **Yes** (stub/headers) | No | No | Yes |
 | **Visual Regression** | **Yes** (`screenshot_diff`) | No | No | No |
@@ -63,7 +63,7 @@ Claude Code calls `navigate` (returning clickable element refs), `accessibility_
 
 ## Token-Efficient Design
 
-- **Compact Schemas**: 30 core tools use ≈3.9k tokens of schemas (vs Playwright MCP's ~4.6k). Specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`.
+- **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`.
 - **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.
@@ -84,7 +84,7 @@ Claude Code  <--stdio-->  MCP Server  <--WebSocket :8765-->  Chrome Extension
 
 The **MCP Server** (Node.js) handles the protocol and tool logic. The **Chrome Extension** (MV3) executes commands via Chrome APIs. User scripts (`execute_js`) run via `chrome.userScripts.execute()`, requiring the "Allow user scripts" toggle in extension settings.
 
-## Tools (59 total)
+## Tools (60 total)
 
 ### Core & Navigation (7)
 `get_status`, `get_tabs`, `create_tab`, `navigate`, `tab_action`, `get_frames`, `screenshot`.
@@ -95,8 +95,8 @@ The **MCP Server** (Node.js) handles the protocol and tool logic. The **Chrome E
 ### DOM & Inspection (11)
 `read_page`, `extract`, `get_page_info`, `query_dom`, `modify_dom`, `find_text`, `get_interactives`, `inject_css`, `highlight_elements`, `watch_dom`, `measure_spacing`.
 
-### Debugging & Network (8)
-`execute_js`, `read_console`, `monitor_network`, `monitor_websocket`, `network_rules` (block/redirect/stub/headers), `get_performance`, `web_vitals`, `list_event_listeners`.
+### Debugging & Network (9)
+`execute_js`, `read_console`, `monitor_network`, `monitor_websocket`, `network_rules` (block/redirect/stub/headers), `http_request` (sent with the user's session cookies), `get_performance`, `web_vitals`, `list_event_listeners`.
 
 ### Visual & Responsive (7)
 `element_screenshot`, `full_page_screenshot`, `screenshot_diff`, `viewport_resize`, `set_zoom`, `emulate_media`, `set_geolocation`.
@@ -132,7 +132,7 @@ Configure the server via environment variables (or the matching CLI flags):
 - `CHROME_BRIDGE_PORT`: Default `8765`.
 - `CHROME_BRIDGE_HOST` / `--host`: Bind address, default `127.0.0.1`. Set to `0.0.0.0` **only** where the browser lives outside the container (ChromeOS/Crostini port-forward) — and pair it with a token.
 - `CHROME_BRIDGE_TOKEN`: Shared secret required on both `ext_init` and `relay_init`. Strongly recommended whenever the bind is not loopback.
-- `CHROME_BRIDGE_CAPS` / `--caps`: Tool groups to load (`core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, or `all`). `install.sh` registers with `all`; the bare server defaults to `core` (30 tools). `get_status` reports `caps_active` and `caps_available`.
+- `CHROME_BRIDGE_CAPS` / `--caps`: Tool groups to load (`core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, or `all`). `install.sh` registers with `all`; the bare server defaults to `core` (31 tools). `get_status` reports `caps_active` and `caps_available`.
 
 Run `node tools/measure-schema.mjs` to see the exact schema cost of the active set.
 

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.8.0",
-  "description": "Bridge your browser to Claude Code: 59 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
+  "version": "1.9.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",
   "permissions": [

package/extension/service-worker.js

@@ -423,6 +423,8 @@ async function executeCommand(msg) {
       return await cmdManageDownloads(params);
     case 'save_page':
       return await cmdSavePage(params);
+    case 'http_request':
+      return await cmdHttpRequest(params);
     case 'set_zoom':
       return await cmdSetZoom(params);
     case 'http_auth':
@@ -2177,12 +2179,12 @@ async function cmdWatchDom({ selector = 'body', attributes = true, childList = t
 
 // --- emulate_media ---
 
-async function cmdEmulateMedia({ colorScheme, reducedMotion, printMode = false, reset = false, tab_id }) {
+async function cmdEmulateMedia({ colorScheme, reducedMotion, printMode = false, user_agent = null, reset = false, tab_id }) {
   const tabId = await resolveTabId(tab_id);
 
   const results = await chrome.scripting.executeScript({
     target: { tabId },
-    func: (cs, rm, print, doReset) => {
+    func: (cs, rm, print, ua, doReset) => {
       const STYLE_ID = '__chromeBridge_media';
       const META_ID = '__chromeBridge_colorScheme';
 
@@ -2196,6 +2198,15 @@ async function cmdEmulateMedia({ colorScheme, reducedMotion, printMode = false,
           window.matchMedia = window.__chromeBridge_origMatchMedia;
           delete window.__chromeBridge_origMatchMedia;
         }
+        // navigator.userAgent è stato ridefinito con un getter: per tornare
+        // all'originale va rimossa la proprietà own, così riemerge quella del
+        // prototipo.
+        if (window.__chromeBridge_uaPatched) {
+          for (const prop of ['userAgent', 'appVersion', 'platform']) {
+            try { delete navigator[prop]; } catch { /* proprietà non configurabile: si prosegue */ }
+          }
+          delete window.__chromeBridge_uaPatched;
+        }
         return { reset: true };
       }
 
@@ -2261,9 +2272,26 @@ async function cmdEmulateMedia({ colorScheme, reducedMotion, printMode = false,
         meta.remove();
       }
 
+      // navigator.userAgent non è scrivibile: va ridefinita come getter sull'
+      // istanza, che precede quella del prototipo. Vale per il JS della pagina,
+      // non per l'header della richiesta (quello è network_rules).
+      if (ua) {
+        for (const [prop, value] of [
+          ['userAgent', ua],
+          ['appVersion', ua.replace(/^Mozilla\//, '')],
+          ['platform', /iPhone|iPad|Android/i.test(ua) ? 'iPhone' : navigator.platform],
+        ]) {
+          try {
+            Object.defineProperty(navigator, prop, { get: () => value, configurable: true });
+          } catch { /* alcune pagine congelano navigator: si prosegue */ }
+        }
+        window.__chromeBridge_uaPatched = true;
+        overrides.userAgent = ua;
+      }
+
       return { emulated: overrides };
     },
-    args: [colorScheme || null, reducedMotion || null, printMode, reset],
+    args: [colorScheme || null, reducedMotion || null, printMode, user_agent, reset],
     world: 'MAIN',
   });
   return results?.[0]?.result ?? {};
@@ -3440,6 +3468,46 @@ async function cmdManageDownloads({ action, timeout = 30000, limit = 10 }) {
 
 // --- save_page (MHTML via pageCapture) ---
 
+// --- http_request ---
+
+/**
+ * La fetch parte dal service worker, non dal server Node: con host permission
+ * `<all_urls>` e `credentials: 'include'` Chrome allega i cookie di sessione
+ * dell'utente. È l'unica differenza che conta — la stessa URL richiesta da Node
+ * restituisce la pagina di login.
+ */
+async function cmdHttpRequest({ url, method = 'GET', headers, body, binary = false }) {
+  if (!/^https?:\/\//i.test(String(url || ''))) {
+    throw new Error(`http_request needs an absolute http(s) URL, got "${url}"`);
+  }
+  const res = await fetch(url, {
+    method,
+    headers: headers && Object.keys(headers).length ? headers : undefined,
+    body: body ?? undefined,
+    credentials: 'include',
+    redirect: 'follow',
+  });
+
+  const outHeaders = {};
+  for (const [k, v] of res.headers.entries()) outHeaders[k] = v;
+  const common = {
+    status: res.status,
+    ok: res.ok,
+    // res.url riflette i redirect seguiti: senza, un 302 verso il login
+    // sembrerebbe una risposta della URL chiesta.
+    url: res.url,
+    content_type: res.headers.get('content-type') || '',
+    headers: outHeaders,
+  };
+
+  if (binary) {
+    const blob = await res.blob();
+    return { ...common, body_b64: await blobToBase64(blob), size: blob.size };
+  }
+  const text = await res.text();
+  return { ...common, body: text, size: text.length };
+}
+
 async function cmdSavePage({ tab_id }) {
   const tabId = await resolveTabId(tab_id);
   const blob = await new Promise((resolve, reject) => {

package/package.json

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

package/server/protocol.js

@@ -58,6 +58,7 @@ export const MessageType = Object.freeze({
   SET_GEOLOCATION:       'set_geolocation',
   MANAGE_DOWNLOADS:      'manage_downloads',
   SAVE_PAGE:             'save_page',
+  HTTP_REQUEST:          'http_request',
   SET_ZOOM:              'set_zoom',
   HTTP_AUTH:             'http_auth',
   GET_RESPONSE_HEADERS:  'get_response_headers',
@@ -80,7 +81,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.8.0';
+export const VERSION               = '1.9.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;
@@ -129,6 +130,7 @@ export function getTimeout(type) {
     || type === MessageType.UPLOAD_FILE
     || type === MessageType.MANAGE_DOWNLOADS
     || type === MessageType.SAVE_PAGE
+    || type === MessageType.HTTP_REQUEST
     || type === MessageType.WAIT_FOR_FUNCTION
     || type === MessageType.SCROLL_UNTIL) return 60000;
   return COMMAND_TIMEOUT_MS;

package/server/tools.js

@@ -190,6 +190,106 @@ for (const [group, names] of Object.entries(TOOL_CAPS)) {
   for (const n of names) TOOL_TO_CAP.set(n, group);
 }
 
+/**
+ * Annotations MCP, una voce per tool.
+ *
+ * Sono l'unico modo che l'agente ha di sapere cosa fa un tool al mondo PRIMA di
+ * chiamarlo: la descrizione in prosa la legge, ma non la può confrontare. Senza
+ * `readOnlyHint`, `click` e `read_page` si equivalgono al momento della scelta.
+ *
+ * Stanno qui e non sui singoli `server.tool(...)` perché il wrapper in
+ * registerTools le applica tutte da un punto solo, e
+ * `test/unit/tool-annotations.test.js` fallisce se un tool nuovo non ha la sua
+ * voce — impossibile aggiungere un tool e dimenticarle.
+ *
+ * openWorldHint = il tool può raggiungere o farsi raggiungere da server remoti
+ * (navigazione, fetch, mock di rete), non solo leggere lo stato già caricato.
+ */
+const ro = (open = false) => ({
+  readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: open,
+});
+const rw = ({ destructive = false, idempotent = false, open = false } = {}) => ({
+  readOnlyHint: false, destructiveHint: destructive, idempotentHint: idempotent, openWorldHint: open,
+});
+
+export const TOOL_ANNOTATIONS = {
+  // --- osservazione pura ---
+  accessibility_audit: ro(),
+  assert: ro(),
+  check_links: ro(true),
+  element_screenshot: ro(),
+  extract: ro(),
+  extract_table: ro(),
+  find_text: ro(),
+  full_page_screenshot: ro(),
+  get_frames: ro(),
+  get_interactives: ro(),
+  get_page_info: ro(),
+  get_performance: ro(),
+  get_status: ro(),
+  get_storage: ro(),
+  get_tabs: ro(),
+  list_event_listeners: ro(),
+  manage_downloads: ro(),
+  measure_spacing: ro(),
+  monitor_network: ro(true),
+  monitor_websocket: ro(true),
+  query_dom: ro(),
+  read_page: ro(),
+  screenshot: ro(),
+  security_headers: ro(true),
+  seo_audit: ro(),
+  unused_css: ro(),
+  wait_for: ro(),
+  watch_dom: ro(),
+  web_vitals: ro(),
+
+  // --- interazione con la pagina ---
+  click: rw({ open: true }),          // un click può navigare
+  drag_and_drop: rw(),
+  fill_form: rw({ idempotent: true }),
+  hover: rw({ idempotent: true }),
+  press_key: rw(),
+  scroll: rw(),
+  type_text: rw({ idempotent: true }),
+  upload_file: rw(),
+
+  // --- modifica di pagina, tab o resa ---
+  dismiss_overlays: rw({ idempotent: true }),
+  emulate_media: rw({ idempotent: true }),
+  handle_dialogs: rw({ idempotent: true }),
+  highlight_elements: rw({ idempotent: true }),
+  inject_css: rw({ idempotent: true }),
+  modify_dom: rw({ idempotent: true }),
+  screenshot_diff: rw({ idempotent: true }),
+  set_zoom: rw({ idempotent: true }),
+  viewport_resize: rw({ idempotent: true }),
+  create_tab: rw({ open: true }),
+  navigate: rw({ idempotent: true, open: true }),
+  tab_action: rw({ destructive: true, open: true }),  // close chiude una tab dell'utente
+
+  // --- rete, identità, posizione ---
+  http_auth: rw({ idempotent: true, open: true }),
+  network_rules: rw({ idempotent: true, open: true }),
+  set_geolocation: rw({ idempotent: true }),
+
+  // --- codice arbitrario ---
+  execute_js: rw({ destructive: true, open: true }),
+
+  // http_request non è read-only: un POST cambia lo stato del server remoto, e
+  // con save_to scrive un file. destructive perché sovrascrive save_to senza
+  // chiedere.
+  http_request: rw({ destructive: true, open: true }),
+
+  // --- stato che può essere distrutto o sovrascritto ---
+  clipboard: rw({ idempotent: true }),
+  read_console: rw({ destructive: true }),                        // clear:true cancella il buffer
+  save_page: rw({ destructive: true, idempotent: true }),         // sovrascrive output_path
+  session_fixture: rw({ destructive: true, idempotent: true }),   // restore sovrascrive cookie e storage
+  session_record: rw(),
+  set_storage: rw({ destructive: true, idempotent: true }),
+};
+
 /**
  * Registra tutti i tool MCP.
  *
@@ -203,15 +303,26 @@ export function registerTools(server, wsManager, caps = 'all') {
     ? ['core', ...Object.keys(TOOL_CAPS)]
     : ['core', ...String(caps).split(',').map((s) => s.trim()).filter((s) => s && s !== 'core')];
 
-  // Filtro capability: i tool opt-in fuori dai gruppi attivi non vengono registrati
-  if (caps !== 'all') {
-    const enabled = new Set(String(caps).split(',').map((s) => s.trim()).filter(Boolean));
+  // Ogni registrazione passa da qui: il filtro capability scarta i tool opt-in
+  // fuori dai gruppi attivi, e le annotations vengono applicate da TOOL_ANNOTATIONS.
+  // Un solo wrapper per entrambe le cose, altrimenti con caps != 'all' le
+  // annotations sparivano insieme al filtro.
+  {
     const target = server;
+    const enabled = caps !== 'all'
+      ? new Set(String(caps).split(',').map((s) => s.trim()).filter(Boolean))
+      : null;
     server = {
       tool(name, desc, schema, handler) {
-        const group = TOOL_TO_CAP.get(name);
-        if (group && !enabled.has(group) && !enabled.has('all')) return;
-        target.tool(name, desc, schema, handler);
+        if (enabled) {
+          const group = TOOL_TO_CAP.get(name);
+          if (group && !enabled.has(group) && !enabled.has('all')) return;
+        }
+        const annotations = TOOL_ANNOTATIONS[name];
+        // Un tool senza voce resta registrato (meglio di un crash all'avvio):
+        // è il test tool-annotations a segnalarlo.
+        if (annotations) target.tool(name, desc, schema, annotations, handler);
+        else target.tool(name, desc, schema, handler);
       },
     };
   }
@@ -342,7 +453,8 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- get_tabs ---
   server.tool(
     'get_tabs',
-    'List all open Chrome tabs',
+    'List every open tab with id, url, title and active flag. Read-only. Use it to find a tab_id when the '
+      + 'implicit target (last navigated tab, else the active one) is not the tab you mean.',
     {},
     async () => {
       const data = await send(MessageType.GET_TABS);
@@ -429,7 +541,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- click ---
   server.tool(
     'click',
-    'Click an element by CSS selector or by ref from get_interactives.',
+    'Click an element, by CSS selector or by a ref (n1, n2…) from get_interactives or navigate. Fires a real '
+      + '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(),
       ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
@@ -485,7 +599,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- read_page ---
   server.tool(
     'read_page',
-    'Read the content of a Chrome tab page',
+    'Read the page as text (default), raw HTML, or accessibility tree. Read-only. Expensive on large pages: '
+      + '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(),
@@ -525,7 +641,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- get_storage ---
   server.tool(
     'get_storage',
-    'Get page storage: localStorage, sessionStorage, and cookies',
+    'Read localStorage, sessionStorage or cookies of the current origin (type=all for every one). Read-only. '
+      + '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(),
@@ -544,7 +662,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- get_performance ---
   server.tool(
     'get_performance',
-    'Get page performance metrics: navigation timing, paint metrics, memory, and resource loading',
+    '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.',
     {
       tab_id: z.number().optional(),
     },
@@ -584,7 +704,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- modify_dom ---
   server.tool(
     'modify_dom',
-    'Modify DOM elements: setAttribute, removeAttribute, addClass, removeClass, setStyle, setTextContent',
+    'Change an element in the live DOM: setAttribute, removeAttribute, addClass, removeClass, setStyle, '
+      + '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']),
@@ -608,7 +730,8 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- inject_css ---
   server.tool(
     'inject_css',
-    'Inject CSS rules into a Chrome tab page',
+    '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(),
@@ -700,7 +823,8 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- create_tab ---
   server.tool(
     'create_tab',
-    'Create a new Chrome tab, optionally navigating to a URL',
+    'Open a new tab, optionally at a URL, and make it the implicit target of later commands in this session. '
+      + '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),
@@ -785,7 +909,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- set_storage ---
   server.tool(
     'set_storage',
-    'Write, delete, or clear localStorage, sessionStorage, or cookies',
+    'Write, delete or clear a localStorage/sessionStorage key, or a cookie with its path, domain and expiry. '
+      + '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']),
@@ -880,7 +1006,10 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- full_page_screenshot ---
   server.tool(
     'full_page_screenshot',
-    'Full-page capture by scrolling: stitched segments of ~2 viewports (≤1568px, top→bottom), or one image per viewport with stitch=false.',
+    'Full-page capture by scrolling: stitched segments of ~2 viewports (≤1568px, top→bottom), or one image per '
+      + 'viewport with stitch=false. Read-only, but expensive: each segment costs ~2.7k image tokens, so only the first '
+      + '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),
       delay: z.number().optional().default(500).describe('ms between captures (min 500, Chrome quota)'),
@@ -1003,7 +1132,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- measure_spacing ---
   server.tool(
     'measure_spacing',
-    'Measure pixel distance, gap, overlap, and margin/padding between two elements',
+    'Measure the gap, overlap and distance in CSS pixels between two elements, with their margins and paddings. '
+      + '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(),
@@ -1049,16 +1180,20 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- emulate_media ---
   server.tool(
     'emulate_media',
-    'Emulate prefers-color-scheme, prefers-reduced-motion, print mode (matchMedia override + CSS).',
+    'Make the page believe it runs in a different environment, until reset or reload: prefers-color-scheme, '
+      + 'prefers-reduced-motion, print mode (matchMedia override + CSS) and navigator.userAgent/platform. '
+      + '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),
+      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(),
     },
-    async ({ colorScheme, reducedMotion, printMode, reset, tab_id }) => {
-      const data = await send(MessageType.EMULATE_MEDIA, { colorScheme, reducedMotion, printMode, reset, tab_id });
+    async ({ colorScheme, reducedMotion, printMode, user_agent, reset, tab_id }) => {
+      const data = await send(MessageType.EMULATE_MEDIA, { colorScheme, reducedMotion, printMode, user_agent, reset, tab_id });
       return {
         content: [{
           type: 'text',
@@ -1092,7 +1227,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- press_key ---
   server.tool(
     'press_key',
-    'Press a keyboard key with optional modifiers (keydown/keypress/keyup).',
+    'Send a key to the focused element (or to selector, focusing it first) as a real keydown/keypress/keyup '
+      + 'sequence, so framework handlers fire. For typing a value use type_text; this is for Enter, Tab, Escape, '
+      + 'arrows and shortcuts. Not idempotent: two calls send the key twice.',
     {
       key: z.string().describe('e.g. "Enter", "Escape", "Tab", "ArrowDown"'),
       selector: z.string().optional().describe('Target (default: activeElement)'),
@@ -1130,7 +1267,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- tab_action ---
   server.tool(
     'tab_action',
-    'Tab lifecycle actions: close, activate (focus), reload (optional cache bypass), back, forward',
+    'Tab lifecycle: close, activate (focus), reload (optional cache bypass), back, forward. close discards the '
+      + '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']),
       bypass_cache: z.boolean().optional().default(false).describe('reload only'),
@@ -1302,7 +1441,9 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- web_vitals ---
   server.tool(
     'web_vitals',
-    'Core Web Vitals since page load: CLS, LCP, FCP, TTFB, long tasks, INP approximation.',
+    '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.',
     {
       tab_id: z.number().optional(),
     },
@@ -1468,6 +1609,64 @@ export function registerTools(server, wsManager, caps = 'all') {
     }
   );
 
+  // --- http_request ---
+  server.tool(
+    'http_request',
+    'HTTP request sent from the browser, so it carries the session cookies of the logged-in user: '
+      + 'fetches URLs a plain server-side request would get a login page for (invoices, authenticated JSON, CSV exports). '
+      + 'Text bodies are returned inline (capped by max_length); with save_to the bytes are written to that path instead, '
+      + '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'),
+      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)'),
+      max_length: z.number().optional().default(DEFAULT_MAX_OUTPUT).describe('Max chars of body returned inline'),
+    },
+    async ({ url, method, headers, body, save_to, max_length }) => {
+      const data = await send(MessageType.HTTP_REQUEST, { url, method, headers, body, binary: Boolean(save_to) });
+
+      if (save_to) {
+        // Il base64 non deve mai raggiungere il modello: un PDF di 300 kB sono
+        // ~100k token di rumore per un contenuto che va letto da file.
+        await writeFile(save_to, Buffer.from(data.body_b64 ?? '', 'base64'));
+        return {
+          content: [{
+            type: 'text',
+            text: jsonText({
+              saved: save_to,
+              status: data.status,
+              ok: data.ok,
+              content_type: data.content_type,
+              size: data.size,
+              url: data.url,
+            }),
+          }],
+        };
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(
+            jsonText({
+              status: data.status,
+              ok: data.ok,
+              content_type: data.content_type,
+              size: data.size,
+              url: data.url,
+              headers: data.headers,
+              body: data.body,
+            }, max_length ?? DEFAULT_MAX_OUTPUT, 'max_length'),
+            max_length ?? DEFAULT_MAX_OUTPUT,
+            'max_length',
+          ),
+        }],
+      };
+    }
+  );
+
   // --- set_zoom ---
   server.tool(
     'set_zoom',