docs: update generate-docs.ts tools output order (#1991)

Closes: #1932

Author: nroscino

README.md

@@ -477,7 +477,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
-- **Input automation** (9 tools)
+- **Input automation** (10 tools)
   - [`click`](docs/tool-reference.md#click)
   - [`drag`](docs/tool-reference.md#drag)
   - [`fill`](docs/tool-reference.md#fill)
@@ -487,6 +487,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`press_key`](docs/tool-reference.md#press_key)
   - [`type_text`](docs/tool-reference.md#type_text)
   - [`upload_file`](docs/tool-reference.md#upload_file)
+  - [`click_at`](docs/tool-reference.md#click_at)
 - **Navigation automation** (6 tools)
   - [`close_page`](docs/tool-reference.md#close_page)
   - [`list_pages`](docs/tool-reference.md#list_pages)
@@ -504,21 +505,28 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 - **Network** (2 tools)
   - [`get_network_request`](docs/tool-reference.md#get_network_request)
   - [`list_network_requests`](docs/tool-reference.md#list_network_requests)
-- **Debugging** (6 tools)
+- **Debugging** (10 tools)
   - [`evaluate_script`](docs/tool-reference.md#evaluate_script)
   - [`get_console_message`](docs/tool-reference.md#get_console_message)
   - [`lighthouse_audit`](docs/tool-reference.md#lighthouse_audit)
   - [`list_console_messages`](docs/tool-reference.md#list_console_messages)
   - [`take_screenshot`](docs/tool-reference.md#take_screenshot)
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
+  - [`execute_webmcp_tool`](docs/tool-reference.md#execute_webmcp_tool)
+  - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools)
+  - [`screencast_start`](docs/tool-reference.md#screencast_start)
+  - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
+- **Memory** (4 tools)
+  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
+  - [`get_memory_snapshot_details`](docs/tool-reference.md#get_memory_snapshot_details)
+  - [`get_nodes_by_class`](docs/tool-reference.md#get_nodes_by_class)
+  - [`load_memory_snapshot`](docs/tool-reference.md#load_memory_snapshot)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)
   - [`reload_extension`](docs/tool-reference.md#reload_extension)
   - [`trigger_extension_action`](docs/tool-reference.md#trigger_extension_action)
   - [`uninstall_extension`](docs/tool-reference.md#uninstall_extension)
-- **Memory** (1 tools)
-  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
 
 <!-- END AUTO GENERATED TOOLS -->
 

docs/tool-reference.md

@@ -2,7 +2,7 @@
 
 # Chrome DevTools MCP Tool Reference (~7010 cl100k_base tokens)
 
-- **[Input automation](#input-automation)** (9 tools)
+- **[Input automation](#input-automation)** (10 tools)
   - [`click`](#click)
   - [`drag`](#drag)
   - [`fill`](#fill)
@@ -12,6 +12,7 @@
   - [`press_key`](#press_key)
   - [`type_text`](#type_text)
   - [`upload_file`](#upload_file)
+  - [`click_at`](#click_at)
 - **[Navigation automation](#navigation-automation)** (6 tools)
   - [`close_page`](#close_page)
   - [`list_pages`](#list_pages)
@@ -29,21 +30,28 @@
 - **[Network](#network)** (2 tools)
   - [`get_network_request`](#get_network_request)
   - [`list_network_requests`](#list_network_requests)
-- **[Debugging](#debugging)** (6 tools)
+- **[Debugging](#debugging)** (10 tools)
   - [`evaluate_script`](#evaluate_script)
   - [`get_console_message`](#get_console_message)
   - [`lighthouse_audit`](#lighthouse_audit)
   - [`list_console_messages`](#list_console_messages)
   - [`take_screenshot`](#take_screenshot)
   - [`take_snapshot`](#take_snapshot)
+  - [`execute_webmcp_tool`](#execute_webmcp_tool)
+  - [`list_webmcp_tools`](#list_webmcp_tools)
+  - [`screencast_start`](#screencast_start)
+  - [`screencast_stop`](#screencast_stop)
+- **[Memory](#memory)** (4 tools)
+  - [`take_memory_snapshot`](#take_memory_snapshot)
+  - [`get_memory_snapshot_details`](#get_memory_snapshot_details)
+  - [`get_nodes_by_class`](#get_nodes_by_class)
+  - [`load_memory_snapshot`](#load_memory_snapshot)
 - **[Extensions](#extensions)** (5 tools)
   - [`install_extension`](#install_extension)
   - [`list_extensions`](#list_extensions)
   - [`reload_extension`](#reload_extension)
   - [`trigger_extension_action`](#trigger_extension_action)
   - [`uninstall_extension`](#uninstall_extension)
-- **[Memory](#memory)** (1 tools)
-  - [`take_memory_snapshot`](#take_memory_snapshot)
 
 ## Input automation
 
@@ -150,6 +158,19 @@
 
 ---
 
+### `click_at`
+
+**Description:** Clicks at the provided coordinates (requires flag: --experimentalVision=true)
+
+**Parameters:**
+
+- **x** (number) **(required)**: The x coordinate
+- **y** (number) **(required)**: The y coordinate
+- **dblClick** (boolean) _(optional)_: Set to true for double clicks. Default is false.
+- **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
+
+---
+
 ## Navigation automation
 
 ### `close_page`
@@ -396,13 +417,97 @@ in the DevTools Elements panel (if any).
 
 ---
 
+### `execute_webmcp_tool`
+
+**Description:** Executes a WebMCP tool exposed by the page. (requires flag: --experimentalWebmcp=true)
+
+**Parameters:**
+
+- **toolName** (string) **(required)**: The name of the WebMCP tool to execute
+- **input** (string) _(optional)_: The JSON-stringified parameters to pass to the WebMCP tool
+
+---
+
+### `list_webmcp_tools`
+
+**Description:** Lists all WebMCP tools the page exposes. (requires flag: --experimentalWebmcp=true)
+
+**Parameters:** None
+
+---
+
+### `screencast_start`
+
+**Description:** Starts recording a screencast (video) of the selected page in specified format. (requires flag: --experimentalScreencast=true)
+
+**Parameters:**
+
+- **filePath** (string) _(optional)_: Output file path (.webm,.mp4 are supported). Uses mkdtemp to generate a unique path if not provided.
+
+---
+
+### `screencast_stop`
+
+**Description:** Stops the active screencast recording on the selected page. (requires flag: --experimentalScreencast=true)
+
+**Parameters:** None
+
+---
+
+## Memory
+
+### `take_memory_snapshot`
+
+**Description:** Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to save the heapsnapshot to.
+
+---
+
+### `get_memory_snapshot_details`
+
+**Description:** Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+- **pageIdx** (number) _(optional)_: The page index for pagination of aggregates.
+- **pageSize** (number) _(optional)_: The page size for pagination of aggregates.
+
+---
+
+### `get_nodes_by_class`
+
+**Description:** Loads a memory heapsnapshot and returns instances of a specific class with their stable IDs. (requires flag: --experimentalMemory=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+- **uid** (number) **(required)**: The unique UID for the class, obtained from aggregates listing.
+- **pageIdx** (number) _(optional)_: The page index for pagination.
+- **pageSize** (number) _(optional)_: The page size for pagination.
+
+---
+
+### `load_memory_snapshot`
+
+**Description:** Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+
+---
+
 ## Extensions
 
 > NOTE: Extensions are not active by default. Use the '--categoryExtensions' flag
 
 ### `install_extension`
 
-**Description:** Installs a Chrome extension from the given path.
+**Description:** Installs a Chrome extension from the given path. (requires flag: --categoryExtensions=true)
 
 **Parameters:**
 
@@ -412,15 +517,15 @@ in the DevTools Elements panel (if any).
 
 ### `list_extensions`
 
-**Description:** Lists all the Chrome extensions installed in the browser. This includes their name, ID, version, and enabled status.
+**Description:** Lists all the Chrome extensions installed in the browser. This includes their name, ID, version, and enabled status. (requires flag: --categoryExtensions=true)
 
 **Parameters:** None
 
 ---
 
 ### `reload_extension`
 
-**Description:** Reloads an unpacked Chrome extension by its ID.
+**Description:** Reloads an unpacked Chrome extension by its ID. (requires flag: --categoryExtensions=true)
 
 **Parameters:**
 
@@ -430,7 +535,7 @@ in the DevTools Elements panel (if any).
 
 ### `trigger_extension_action`
 
-**Description:** Triggers the default action of an extension by its ID.
+**Description:** Triggers the default action of an extension by its ID. (requires flag: --categoryExtensions=true)
 
 **Parameters:**
 
@@ -440,22 +545,10 @@ in the DevTools Elements panel (if any).
 
 ### `uninstall_extension`
 
-**Description:** Uninstalls a Chrome extension by its ID.
+**Description:** Uninstalls a Chrome extension by its ID. (requires flag: --categoryExtensions=true)
 
 **Parameters:**
 
 - **id** (string) **(required)**: ID of the extension to uninstall.
 
 ---
-
-## Memory
-
-### `take_memory_snapshot`
-
-**Description:** Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.
-
-**Parameters:**
-
-- **filePath** (string) **(required)**: A path to a .heapsnapshot file to save the heapsnapshot to.
-
----

scripts/generate-docs.ts

@@ -131,6 +131,20 @@ function addCrossLinks(text: string, tools: ToolWithAnnotations[]): string {
   return result;
 }
 
+function sortTools(a: ToolWithAnnotations, b: ToolWithAnnotations): number {
+  const aHasConditions = Boolean(a.annotations?.conditions?.length > 0);
+  const bHasConditions = Boolean(b.annotations?.conditions?.length > 0);
+
+  if (aHasConditions && !bHasConditions) {
+    return 1;
+  }
+  if (!aHasConditions && bHasConditions) {
+    return -1;
+  }
+
+  return a.name.localeCompare(b.name);
+}
+
 function generateToolsTOC(
   categories: Record<string, ToolWithAnnotations[]>,
   sortedCategories: string[],
@@ -143,7 +157,7 @@ function generateToolsTOC(
     toc += `- **${categoryName}** (${categoryTools.length} tools)\n`;
 
     // Sort tools within category for TOC
-    categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));
+    categoryTools.sort(sortTools);
     for (const tool of categoryTools) {
       const anchorLink = tool.name.toLowerCase();
       toc += `  - [\`${tool.name}\`](docs/tool-reference.md#${anchorLink})\n`;
@@ -341,7 +355,7 @@ async function generateReference(
     markdown += `- **[${categoryName}](#${anchorName})** (${categoryTools.length} tools)\n`;
 
     // Sort tools within category for TOC
-    categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));
+    categoryTools.sort(sortTools);
     for (const tool of categoryTools) {
       // Generate proper markdown anchor link: backticks are removed, keep underscores, lowercase
       const anchorLink = tool.name.toLowerCase();
@@ -363,7 +377,7 @@ async function generateReference(
     }
 
     // Sort tools within category
-    categoryTools.sort((a: Tool, b: Tool) => a.name.localeCompare(b.name));
+    categoryTools.sort(sortTools);
 
     for (const tool of categoryTools) {
       markdown += `### \`${tool.name}\`\n\n`;
@@ -372,6 +386,23 @@ async function generateReference(
         // Escape HTML tags but preserve JS function syntax
         let escapedDescription = escapeHtmlTags(tool.description);
 
+        const requiredFlags: string[] = [];
+
+        const isOffByDefault = OFF_BY_DEFAULT_CATEGORIES.includes(category);
+        if (isOffByDefault) {
+          const categoryFlag = buildFlag(category);
+          requiredFlags.push(`--${categoryFlag}=true`);
+        }
+
+        const conditions = tool.annotations?.conditions || [];
+        for (const condition of conditions) {
+          requiredFlags.push(`--${condition}=true`);
+        }
+
+        if (requiredFlags.length > 0) {
+          escapedDescription += ` (requires flag: ${requiredFlags.join(', ')})`;
+        }
+
         // Add cross-links to mentioned tools
         escapedDescription = addCrossLinks(
           escapedDescription,
@@ -448,16 +479,17 @@ function getToolsAndCategories(tools: any) {
   const toolsWithAnnotations: ToolWithAnnotations[] = tools
     .filter(tool => {
       // Skipping in_page tools as they are not launched yet
-      if (tool.annotations.category.includes('experimental')) {
+      if (tool.annotations.category === ToolCategory.IN_PAGE) {
         return false;
       }
 
-      if (!tool.annotations.conditions) {
-        return true;
+      // Skipping internal interop tools not meant for public documentation
+      const skipTools = ['get_tab_id'];
+      if (skipTools.includes(tool.name)) {
+        return false;
       }
 
-      // Only include unconditional tools.
-      return tool.annotations.conditions.length === 0;
+      return true;
     })
     .map(tool => {
       const properties: Record<string, TypeInfo> = {};
@@ -497,8 +529,16 @@ function getToolsAndCategories(tools: any) {
   // Sort categories using the enum order
   const categoryOrder = Object.values(ToolCategory);
   const sortedCategories = Object.keys(categories).sort((a, b) => {
-    const aIndex = categoryOrder.indexOf(a);
-    const bIndex = categoryOrder.indexOf(b);
+    const aOff = OFF_BY_DEFAULT_CATEGORIES.includes(a as ToolCategory);
+    const bOff = OFF_BY_DEFAULT_CATEGORIES.includes(b as ToolCategory);
+
+    if (aOff !== bOff) {
+      return aOff ? 1 : -1;
+    }
+
+    const aIndex = categoryOrder.indexOf(a as ToolCategory);
+    const bIndex = categoryOrder.indexOf(b as ToolCategory);
+
     // Put known categories first, unknown categories last
     if (aIndex === -1 && bIndex === -1) {
       return a.localeCompare(b);