fix(extension): arm inactivity timers for all pending tabs (#1443)

Closes #1457

.github/workflows/ci.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [ main ]
 
+env:
+  PWMCP_DEBUG: '1'
+  PWDEBUGIMPL: '1'
+
 jobs:
   lint:
     runs-on: ubuntu-latest

README.md

@@ -72,6 +72,26 @@ amp mcp add playwright -- npx @playwright/mcp@latest
 
 </details>
 
+<details>
+<summary>Antigravity</summary>
+
+Add via the Antigravity settings or by updating your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
+```
+
+</details>
+
 <details>
 <summary>Claude Code</summary>
 
@@ -344,8 +364,6 @@ Playwright MCP server supports following arguments. They can be provided in the
 | --cdp-endpoint <endpoint> | CDP endpoint to connect to.<br>*env* `PLAYWRIGHT_MCP_CDP_ENDPOINT` |
 | --cdp-header <headers...> | CDP headers to send with the connect request, multiple can be specified.<br>*env* `PLAYWRIGHT_MCP_CDP_HEADER` |
 | --cdp-timeout <timeout> | timeout in milliseconds for connecting to CDP endpoint, defaults to 30000ms<br>*env* `PLAYWRIGHT_MCP_CDP_TIMEOUT` |
-| --chromium-sandbox | enable the chromium sandbox. disable with --no-chromium-sandbox.<br>*env* `PLAYWRIGHT_MCP_CHROMIUM_SANDBOX` |
-| --no-chromium-sandbox | disable the chromium sandbox.<br>*env* `PLAYWRIGHT_MCP_NO_CHROMIUM_SANDBOX` |
 | --codegen <lang> | specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript".<br>*env* `PLAYWRIGHT_MCP_CODEGEN` |
 | --config <path> | path to the configuration file.<br>*env* `PLAYWRIGHT_MCP_CONFIG` |
 | --console-level <level> | level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.<br>*env* `PLAYWRIGHT_MCP_CONSOLE_LEVEL` |
@@ -360,11 +378,13 @@ Playwright MCP server supports following arguments. They can be provided in the
 | --init-script <path...> | path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page's scripts. Can be specified multiple times.<br>*env* `PLAYWRIGHT_MCP_INIT_SCRIPT` |
 | --isolated | keep the browser profile in memory, do not save it to disk.<br>*env* `PLAYWRIGHT_MCP_ISOLATED` |
 | --image-responses <mode> | whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".<br>*env* `PLAYWRIGHT_MCP_IMAGE_RESPONSES` |
+| --no-sandbox | disable the sandbox for all process types that are normally sandboxed.<br>*env* `PLAYWRIGHT_MCP_NO_SANDBOX` |
 | --output-dir <path> | path to the directory for output files.<br>*env* `PLAYWRIGHT_MCP_OUTPUT_DIR` |
 | --output-mode <mode> | whether to save snapshots, console messages, network logs to a file or to the standard output. Can be "file" or "stdout". Default is "stdout".<br>*env* `PLAYWRIGHT_MCP_OUTPUT_MODE` |
 | --port <port> | port to listen on for SSE transport.<br>*env* `PLAYWRIGHT_MCP_PORT` |
 | --proxy-bypass <bypass> | comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"<br>*env* `PLAYWRIGHT_MCP_PROXY_BYPASS` |
 | --proxy-server <proxy> | specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"<br>*env* `PLAYWRIGHT_MCP_PROXY_SERVER` |
+| --sandbox | enable the sandbox for all process types that are normally not sandboxed.<br>*env* `PLAYWRIGHT_MCP_SANDBOX` |
 | --save-session | Whether to save the Playwright MCP session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_SESSION` |
 | --save-trace | Whether to save the Playwright Trace of the session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_TRACE` |
 | --save-video <size> | Whether to save the video of the session into the output directory. For example "--save-video=800x600"<br>*env* `PLAYWRIGHT_MCP_SAVE_VIDEO` |
@@ -707,6 +727,10 @@ And then in MCP client config, set the `url` to the HTTP endpoint:
 }
 ```
 
+## Security
+
+Playwright MCP is **not** a security boundary. See [MCP Security Best Practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) for guidance on securing your deployment.
+
 <details>
 <summary><b>Docker</b></summary>
 
@@ -731,7 +755,7 @@ docker run -d -i --rm --init --pull=always \
   --name playwright \
   -p 8931:8931 \
   mcr.microsoft.com/playwright/mcp \
-  cli.js --headless --browser chromium --no-sandbox --port 8931
+  cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0
 ```
 
 The server will listen on host port **8931** and can be reached by any MCP client.  
@@ -1006,6 +1030,257 @@ http.createServer(async (req, res) => {
 
 </details>
 
+<details>
+<summary><b>Configuration (opt-in via --caps=config)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_get_config**
+  - Title: Get config
+  - Description: Get the final resolved config after merging CLI options, environment variables and config file.
+  - Parameters: None
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>Network (opt-in via --caps=network)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_route**
+  - Title: Mock network requests
+  - Description: Set up a route to mock network requests matching a URL pattern
+  - Parameters:
+    - `pattern` (string): URL pattern to match (e.g., "**/api/users", "**/*.{png,jpg}")
+    - `status` (number, optional): HTTP status code to return (default: 200)
+    - `body` (string, optional): Response body (text or JSON string)
+    - `contentType` (string, optional): Content-Type header (e.g., "application/json", "text/html")
+    - `headers` (array, optional): Headers to add in "Name: Value" format
+    - `removeHeaders` (string, optional): Comma-separated list of header names to remove from request
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_route_list**
+  - Title: List network routes
+  - Description: List all active network routes
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_unroute**
+  - Title: Remove network routes
+  - Description: Remove network routes matching a pattern (or all routes if no pattern specified)
+  - Parameters:
+    - `pattern` (string, optional): URL pattern to unroute (omit to remove all routes)
+  - Read-only: **false**
+
+</details>
+
+<details>
+<summary><b>Storage (opt-in via --caps=storage)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_clear**
+  - Title: Clear cookies
+  - Description: Clear all cookies
+  - Parameters: None
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_delete**
+  - Title: Delete cookie
+  - Description: Delete a specific cookie
+  - Parameters:
+    - `name` (string): Cookie name to delete
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_get**
+  - Title: Get cookie
+  - Description: Get a specific cookie by name
+  - Parameters:
+    - `name` (string): Cookie name to get
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_list**
+  - Title: List cookies
+  - Description: List all cookies (optionally filtered by domain/path)
+  - Parameters:
+    - `domain` (string, optional): Filter cookies by domain
+    - `path` (string, optional): Filter cookies by path
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_cookie_set**
+  - Title: Set cookie
+  - Description: Set a cookie with optional flags (domain, path, expires, httpOnly, secure, sameSite)
+  - Parameters:
+    - `name` (string): Cookie name
+    - `value` (string): Cookie value
+    - `domain` (string, optional): Cookie domain
+    - `path` (string, optional): Cookie path
+    - `expires` (number, optional): Cookie expiration as Unix timestamp
+    - `httpOnly` (boolean, optional): Whether the cookie is HTTP only
+    - `secure` (boolean, optional): Whether the cookie is secure
+    - `sameSite` (string, optional): Cookie SameSite attribute
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_clear**
+  - Title: Clear localStorage
+  - Description: Clear all localStorage
+  - Parameters: None
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_delete**
+  - Title: Delete localStorage item
+  - Description: Delete a localStorage item
+  - Parameters:
+    - `key` (string): Key to delete
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_get**
+  - Title: Get localStorage item
+  - Description: Get a localStorage item by key
+  - Parameters:
+    - `key` (string): Key to get
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_list**
+  - Title: List localStorage
+  - Description: List all localStorage key-value pairs
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_localstorage_set**
+  - Title: Set localStorage item
+  - Description: Set a localStorage item
+  - Parameters:
+    - `key` (string): Key to set
+    - `value` (string): Value to set
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_clear**
+  - Title: Clear sessionStorage
+  - Description: Clear all sessionStorage
+  - Parameters: None
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_delete**
+  - Title: Delete sessionStorage item
+  - Description: Delete a sessionStorage item
+  - Parameters:
+    - `key` (string): Key to delete
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_get**
+  - Title: Get sessionStorage item
+  - Description: Get a sessionStorage item by key
+  - Parameters:
+    - `key` (string): Key to get
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_list**
+  - Title: List sessionStorage
+  - Description: List all sessionStorage key-value pairs
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_sessionstorage_set**
+  - Title: Set sessionStorage item
+  - Description: Set a sessionStorage item
+  - Parameters:
+    - `key` (string): Key to set
+    - `value` (string): Value to set
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_set_storage_state**
+  - Title: Restore storage state
+  - Description: Restore storage state (cookies, local storage) from a file. This clears existing cookies and local storage before restoring.
+  - Parameters:
+    - `filename` (string): Path to the storage state file to restore from
+  - Read-only: **false**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_storage_state**
+  - Title: Save storage state
+  - Description: Save storage state (cookies, local storage) to a file for later reuse
+  - Parameters:
+    - `filename` (string, optional): File name to save the storage state to. Defaults to `storage-state-{timestamp}.json` if not specified.
+  - Read-only: **true**
+
+</details>
+
+<details>
+<summary><b>DevTools (opt-in via --caps=devtools)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_start_tracing**
+  - Title: Start tracing
+  - Description: Start trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_start_video**
+  - Title: Start video
+  - Description: Start video recording
+  - Parameters:
+    - `size` (object, optional): Video size
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_stop_tracing**
+  - Title: Stop tracing
+  - Description: Stop trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_stop_video**
+  - Title: Stop video
+  - Description: Stop video recording
+  - Parameters:
+    - `filename` (string, optional): Filename to save the video
+  - Read-only: **true**
+
+</details>
+
 <details>
 <summary><b>Coordinate-based (opt-in via --caps=vision)</b></summary>
 
@@ -1142,10 +1417,5 @@ http.createServer(async (req, res) => {
 
 </details>
 
-<details>
-<summary><b>Tracing (opt-in via --caps=tracing)</b></summary>
-
-</details>
-
 
 <!--- End of tools generated section -->

package-lock.json

@@ -1,19 +1,19 @@
 {
   "name": "playwright-mcp-internal",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "playwright-mcp-internal",
-      "version": "0.0.67",
+      "version": "0.0.68",
       "license": "Apache-2.0",
       "workspaces": [
         "packages/*"
       ],
       "devDependencies": {
         "@modelcontextprotocol/sdk": "^1.25.2",
-        "@playwright/test": "1.59.0-alpha-1771028105000",
+        "@playwright/test": "1.59.0-alpha-1771104257000",
         "@types/node": "^24.3.0"
       }
     },
@@ -742,9 +742,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.9",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.9.tgz",
-      "integrity": "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==",
+      "version": "1.19.10",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.10.tgz",
+      "integrity": "sha512-hZ7nOssGqRgyV3FVVQdfi+U4q02uB23bpnYpdvNXkYTRRyWx84b7yf1ans+dnJ/7h41sGL3CeQTfO+ZGxuO+Iw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -854,13 +854,13 @@
       "link": true
     },
     "node_modules/@playwright/test": {
-      "version": "1.59.0-alpha-1771028105000",
-      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.59.0-alpha-1771028105000.tgz",
-      "integrity": "sha512-chMidCR7qg6ExeTrYP3isJ5fzIgD0bXldX4aQo1vVWPb0su5xJL0UcA5hD1qsmuP1dkUlkI4Qf2wfuxuCfxdyg==",
+      "version": "1.59.0-alpha-1771104257000",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.59.0-alpha-1771104257000.tgz",
+      "integrity": "sha512-0zUPgLuSbyO2xtA+FdEWejFpA5tYU1dINMj2D6KGbB7dgxW8V/4bOrpYS38hizSrzpdSiuRcIK7UgiNFxEeK3A==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.59.0-alpha-1771028105000"
+        "playwright": "1.59.0-alpha-1771104257000"
       },
       "bin": {
         "playwright": "cli.js"
@@ -2168,9 +2168,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.11.8",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.11.8.tgz",
-      "integrity": "sha512-eVkB/CYCCei7K2WElZW9yYQFWssG0DhaDhVvr7wy5jJ22K+ck8fWW0EsLpB0sITUTvPnc97+rrbQqIr5iqiy9Q==",
+      "version": "4.12.7",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.7.tgz",
+      "integrity": "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -2626,12 +2626,12 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.59.0-alpha-1771028105000",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.59.0-alpha-1771028105000.tgz",
-      "integrity": "sha512-tSRYmBZlJt32Q0CKNlVyavvobXt+P7kFUJN+ak9wkcUo+hRSHqyAUcp6G9pRG/vilraanrS6gmAIs3cjUwwxhA==",
+      "version": "1.59.0-alpha-1771104257000",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.59.0-alpha-1771104257000.tgz",
+      "integrity": "sha512-6SCMMMJaDRsSqiKVLmb2nhtLES7iTYawTWWrQK6UdIGNzXi8lka4sLKRec3L4DnTWwddAvCuRn8035dhNiHzbg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.59.0-alpha-1771028105000"
+        "playwright-core": "1.59.0-alpha-1771104257000"
       },
       "bin": {
         "playwright": "cli.js"
@@ -2648,9 +2648,9 @@
       "link": true
     },
     "node_modules/playwright-core": {
-      "version": "1.59.0-alpha-1771028105000",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.59.0-alpha-1771028105000.tgz",
-      "integrity": "sha512-yEIjYyIGSWw8cuaw1hSkAQ+1EBQSdYW2RaHOgHLVAKW8iw7gs8tpY9Wr/75oGazhohRyZNNDom41SO7ktuTUcA==",
+      "version": "1.59.0-alpha-1771104257000",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.59.0-alpha-1771104257000.tgz",
+      "integrity": "sha512-YiXup3pnpQUCBMSIW5zx8CErwRx4K6O5Kojkw2BzJui8MazoMUDU6E3xGsb1kzFviEAE09LFQ+y1a0RhIJQ5SA==",
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"
@@ -3420,7 +3420,7 @@
     },
     "packages/extension": {
       "name": "@playwright/mcp-extension",
-      "version": "0.0.67",
+      "version": "0.0.68",
       "license": "Apache-2.0",
       "devDependencies": {
         "@types/chrome": "^0.0.315",
@@ -3445,11 +3445,11 @@
     },
     "packages/playwright-mcp": {
       "name": "@playwright/mcp",
-      "version": "0.0.67",
+      "version": "0.0.68",
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.59.0-alpha-1771028105000",
-        "playwright-core": "1.59.0-alpha-1771028105000"
+        "playwright": "1.59.0-alpha-1771104257000",
+        "playwright-core": "1.59.0-alpha-1771104257000"
       },
       "bin": {
         "playwright-mcp": "cli.js"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-mcp-internal",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "private": true,
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   ],
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@playwright/test": "1.59.0-alpha-1771028105000",
+    "@playwright/test": "1.59.0-alpha-1771104257000",
     "@types/node": "^24.3.0"
   }
 }

packages/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Playwright MCP Bridge",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "description": "Share browser tabs with Playwright MCP server",
   "permissions": [
     "debugger",

packages/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp-extension",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "description": "Playwright MCP Browser Extension",
   "private": true,
   "repository": {

packages/extension/src/background.ts

@@ -190,7 +190,6 @@ class TabShareExtension {
             chrome.tabs.sendMessage(tabId, { type: 'connectionTimeout' });
           }
         }, 5000);
-        return;
       }
     }
   }

packages/playwright-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "description": "Playwright Tools for MCP",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
     "name": "Microsoft Corporation"
   },
   "license": "Apache-2.0",
+  "mcpName": "io.github.microsoft/playwright-mcp",
   "scripts": {
     "lint": "node update-readme.js",
     "test": "playwright test",
@@ -32,8 +33,8 @@
     }
   },
   "dependencies": {
-    "playwright": "1.59.0-alpha-1771028105000",
-    "playwright-core": "1.59.0-alpha-1771028105000"
+    "playwright": "1.59.0-alpha-1771104257000",
+    "playwright-core": "1.59.0-alpha-1771104257000"
   },
   "bin": {
     "playwright-mcp": "cli.js"

packages/playwright-mcp/update-readme.js

@@ -22,21 +22,30 @@ const { execSync } = require('child_process');
 
 const { browserTools } = require('playwright/lib/mcp/browser/tools');
 
-const capabilities = {
+const capabilities = /** @type {Record<string, string>} */ ({
   'core-navigation': 'Core automation',
   'core': 'Core automation',
   'core-tabs': 'Tab management',
   'core-input': 'Core automation',
   'core-install': 'Browser installation',
-  'vision': 'Coordinate-based (opt-in via --caps=vision)',
-  'pdf': 'PDF generation (opt-in via --caps=pdf)',
-  'testing': 'Test assertions (opt-in via --caps=testing)',
-  'tracing': 'Tracing (opt-in via --caps=tracing)',
-};
+  'config': 'Configuration',
+  'network': 'Network',
+  'storage': 'Storage',
+  'devtools': 'DevTools',
+  'vision': 'Coordinate-based',
+  'pdf': 'PDF generation',
+  'testing': 'Test assertions',
+});
+
+const knownCapabilities = new Set(Object.keys(capabilities));
+const unknownCapabilities = [...new Set(browserTools.map(tool => tool.capability))].filter(cap => !knownCapabilities.has(cap));
+if (unknownCapabilities.length)
+  throw new Error(`Unknown tool capabilities: ${unknownCapabilities.join(', ')}. Please update the capabilities map in ${path.basename(__filename)}.`);
 
 /** @type {Record<string, any[]>} */
 const toolsByCapability = {};
-for (const [capability, title] of Object.entries(capabilities)) {
+for (const capability of Object.keys(capabilities)) {
+  const title = capabilityTitle(capability);
   let tools = browserTools.filter(tool => tool.capability === capability && !tool.skillOnly);
   tools = (toolsByCapability[title] || []).concat(tools);
   toolsByCapability[title] = tools;
@@ -44,6 +53,15 @@ for (const [capability, title] of Object.entries(capabilities)) {
 for (const [, tools] of Object.entries(toolsByCapability))
   tools.sort((a, b) => a.schema.name.localeCompare(b.schema.name));
 
+/**
+ * @param {string} capability
+ * @returns {string}
+ */
+function capabilityTitle(capability) {
+  const title = capabilities[capability];
+  return capability.startsWith('core') ? title : `${title} (opt-in via --caps=${capability})`;
+}
+
 /**
  * @param {any} tool
  * @returns {string[]}