feat: support third-party developer tools (#1982)

Enables "third-party developer tools" feature. This allows the inspected
web page to expose tools which provide debugging information to Chrome
DevTools for Agents.

Third-party developer tools enable web applications to expose internal
state, component hierarchies, or specific debug data that cannot be
deduced through static analysis. This allows Chrome DevTools for Agents
to provide richer, more actionable context to AI agents during debugging
sessions.

2 additional tools are enabled in Chrome DevTools for Agents for
interacting with third-party developer tools:
`list_3p_developer_tools()` and `execute_3p_developer_tool`.

Code changes in this PR:
- Rename "in-page tools" to "third-party developer tools"
- Unhide
- Make available in CLI
- Add documentation

Author: wolfib

README.md

@@ -525,6 +525,9 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`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)
+- **Third-party** (2 tools)
+  - [`execute_3p_developer_tool`](docs/tool-reference.md#execute_3p_developer_tool)
+  - [`list_3p_developer_tools`](docs/tool-reference.md#list_3p_developer_tools)
 - **WebMCP** (2 tools)
   - [`execute_webmcp_tool`](docs/tool-reference.md#execute_webmcp_tool)
   - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools)
@@ -636,6 +639,11 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `false`
 
+- **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`**
+  Set to true to enable third-party developer tools exposed by the inspected page itself
+  - **Type:** boolean
+  - **Default:** `false`
+
 - **`--performanceCrux`/ `--performance-crux`**
   Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.
   - **Type:** boolean

docs/third-party-developer-tools.md

@@ -0,0 +1,87 @@
+# Developer Guide: Building third-party developer tools
+
+This documentation outlines how to expose custom runtime data and tools from your web application to Chrome DevTools for Agents.
+
+## Overview
+
+Third-party developer tools enable your web application to expose internal state, component hierarchies, or specific debug data that cannot be deduced through static analysis. This allows Chrome DevTools for Agents to provide richer, more actionable context to AI agents during debugging sessions.
+
+## How It Works: Tool Discovery
+
+Chrome DevTools for Agents uses an event-based mechanism to discover tools exposed by the page. The process follows these steps:
+
+1.  **Event Dispatch:** Chrome DevTools for Agents dispatches a `devtoolstooldiscovery` event on the global `window` object.
+2.  **Listener:** Your application listens for this event and provides the tool definitions.
+3.  **Response:** Your application must call `event.respondWith()` to register a `ToolGroup` object.
+
+_Note: Chrome DevTools for Agents requests this list automatically after page navigations (e.g., `new_page`, `navigate_page`) or when explicitly requested via the `list_3p_developer_tools()` MCP tool._
+
+## Implementation
+
+To expose tools, implement a listener for the `devtoolstooldiscovery` event and provide a `ToolGroup` containing your tool definitions.
+
+### Type Definitions
+
+Your tools must follow the `ToolDefinition` and `ToolGroup` interfaces:
+
+```typescript
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: JSONSchema7;
+  execute: (args: Record<string, unknown>) => unknown;
+}
+
+export interface ToolGroup {
+  name: string;
+  description: string;
+  tools: ToolDefinition[];
+}
+```
+
+### Example Implementation
+
+```typescript
+window.addEventListener(
+  'devtoolstooldiscovery',
+  (event: DevtoolsToolDiscoveryEvent) => {
+    event.respondWith({
+      name: 'Page-specific DevTools',
+      description: "Provide runtime info directly from the page's JavaScript",
+      tools: [
+        {
+          name: 'add',
+          description: 'Calculates the sum of two numbers.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              a: {type: 'number'},
+              b: {type: 'number'},
+            },
+            required: ['a', 'b'],
+          },
+          execute: async (input: {a: number; b: number}) => {
+            return input.a + input.b;
+          },
+        },
+      ],
+    });
+  },
+);
+```
+
+## Tool Invocation
+
+Once discovered, MCP clients can execute your tools through Chrome DevTools for Agents using:
+
+- **`execute_3p_developer_tool`**: The standard way to invoke a specific registered tool by name with validated parameters.
+- **`evaluate_script`**: Allows for more complex interactions by running a custom script that calls `window.__dtmcp.executeTool()` directly, enabling you to compose functionality.
+
+## Important Considerations
+
+- **Experimental Status:** This feature is currently experimental. APIs may change, and there are no guarantees regarding stability.
+- **Security & Scope:**
+  - **Context:** Third-party developer tools execute only within the context of the page that defines them. They do not persist across origins.
+  - **Capabilities:** These tools do not grant expanded privileges; they can only execute code that an attacker would already be able to run on that page.
+- **DOM Elements:** If your tools require DOM elements as inputs or outputs, they are handled via special UIDs referenced in the accessibility tree.
+- **Flags:** The implementation is gated behind the `--categoryExperimentalThirdParty=true` command-line flag.

docs/tool-reference.md

@@ -50,6 +50,9 @@
   - [`reload_extension`](#reload_extension)
   - [`trigger_extension_action`](#trigger_extension_action)
   - [`uninstall_extension`](#uninstall_extension)
+- **[Third-party](#third-party)** (2 tools)
+  - [`execute_3p_developer_tool`](#execute_3p_developer_tool)
+  - [`list_3p_developer_tools`](#list_3p_developer_tools)
 - **[WebMCP](#webmcp)** (2 tools)
   - [`execute_webmcp_tool`](#execute_webmcp_tool)
   - [`list_webmcp_tools`](#list_webmcp_tools)
@@ -535,6 +538,35 @@ in the DevTools Elements panel (if any).
 
 ---
 
+## Third-party
+
+> NOTE: The Third-party category is not active by default. Use the '--categoryExperimentalThirdParty' flag.
+
+### `execute_3p_developer_tool`
+
+**Description:** Executes a tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)
+
+**Parameters:**
+
+- **toolName** (string) **(required)**: The name of the tool to execute
+- **params** (string) _(optional)_: The JSON-stringified parameters to pass to the tool
+
+---
+
+### `list_3p_developer_tools`
+
+**Description:** Lists all third-party developer tools the page exposes for providing runtime information.
+Third-party developer tools can be called via the '[`execute_3p_developer_tool`](#execute_3p_developer_tool)()' MCP tool.
+Alternatively, third-party developer tools can be executed by calling '[`evaluate_script`](#evaluate_script)' and adding the
+following command to the script:
+'window.\_\_dtmcp.executeTool(toolName, params)'
+This might be helpful when the third-party developer tools return non-serializable values or when composing
+third-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)
+
+**Parameters:** None
+
+---
+
 ## WebMCP
 
 > NOTE: The WebMCP category is not active by default. Use the '--categoryExperimentalWebmcp' flag.

src/McpPage.ts

@@ -13,8 +13,8 @@ import type {
   Viewport,
   WebMCPTool,
 } from './third_party/index.js';
-import type {ToolGroup, ToolDefinition} from './tools/inPage.js';
 import {takeSnapshot} from './tools/snapshot.js';
+import type {ToolGroup, ToolDefinition} from './tools/thirdPartyDeveloper.js';
 import type {
   ContextPage,
   DevToolsData,
@@ -58,7 +58,7 @@ export class McpPage implements ContextPage {
   #dialog?: Dialog;
   #dialogHandler: (dialog: Dialog) => void;
 
-  inPageTools: ToolGroup<ToolDefinition> | undefined;
+  thirdPartyDeveloperTools: ToolGroup<ToolDefinition> | undefined;
 
   constructor(page: Page, id: number) {
     this.pptrPage = page;
@@ -89,8 +89,8 @@ export class McpPage implements ContextPage {
     }
   }
 
-  getInPageTools(): ToolGroup<ToolDefinition> | undefined {
-    return this.inPageTools;
+  getThirdPartyDeveloperTools(): ToolGroup<ToolDefinition> | undefined {
+    return this.thirdPartyDeveloperTools;
   }
 
   getWebMcpTools(): WebMCPTool[] {
@@ -144,7 +144,7 @@ export class McpPage implements ContextPage {
     this.pptrPage.off('dialog', this.#dialogHandler);
   }
 
-  async executeInPageTool(
+  async executeThirdPartyDeveloperTool(
     toolName: string,
     params: Record<string, unknown>,
     response: Response,

src/McpResponse.ts

@@ -27,8 +27,8 @@ import type {
   JSONSchema7Definition,
   Extension,
 } from './third_party/index.js';
-import type {ToolGroup, ToolDefinition} from './tools/inPage.js';
 import {handleDialog} from './tools/pages.js';
+import type {ToolGroup, ToolDefinition} from './tools/thirdPartyDeveloper.js';
 import type {
   DevToolsData,
   ImageContentData,
@@ -196,7 +196,7 @@ export class McpResponse implements Response {
     includePreservedMessages?: boolean;
   };
   #listExtensions?: boolean;
-  #listInPageTools?: boolean;
+  #listThirdPartyDeveloperTools?: boolean;
   #listWebMcpTools?: boolean;
   #devToolsData?: DevToolsData;
   #tabId?: string;
@@ -244,9 +244,9 @@ export class McpResponse implements Response {
     this.#listExtensions = true;
   }
 
-  setListInPageTools(): void {
-    if (this.#args.categoryExperimentalInPage) {
-      this.#listInPageTools = true;
+  setListThirdPartyDeveloperTools(): void {
+    if (this.#args.categoryExperimentalThirdParty) {
+      this.#listThirdPartyDeveloperTools = true;
     }
   }
 
@@ -552,11 +552,11 @@ export class McpResponse implements Response {
       extensions = await context.listExtensions();
     }
 
-    let inPageTools: ToolGroup<ToolDefinition> | undefined;
-    if (this.#listInPageTools) {
+    let thirdPartyDeveloperTools: ToolGroup<ToolDefinition> | undefined;
+    if (this.#listThirdPartyDeveloperTools) {
       const page = this.#page ?? context.getSelectedMcpPage();
-      inPageTools = await getToolGroup(page);
-      page.inPageTools = inPageTools;
+      thirdPartyDeveloperTools = await getToolGroup(page);
+      page.thirdPartyDeveloperTools = thirdPartyDeveloperTools;
     }
 
     let webmcpTools: WebMCPTool[] | undefined;
@@ -669,7 +669,7 @@ export class McpResponse implements Response {
       traceSummary: this.#attachedTraceSummary,
       extensions,
       lighthouseResult: this.#attachedLighthouseResult,
-      inPageTools,
+      thirdPartyDeveloperTools,
       webmcpTools,
       errorMessage: this.#error?.message,
     });
@@ -688,7 +688,7 @@ export class McpResponse implements Response {
       traceInsight?: TraceInsightData;
       extensions?: Map<string, Extension>;
       lighthouseResult?: LighthouseData;
-      inPageTools?: ToolGroup<ToolDefinition>;
+      thirdPartyDeveloperTools?: ToolGroup<ToolDefinition>;
       webmcpTools?: WebMCPTool[];
       errorMessage?: string;
     },
@@ -705,7 +705,7 @@ export class McpResponse implements Response {
       traceInsights?: Array<{insightName: string; insightKey: string}>;
       lighthouseResult?: object;
       extensions?: object[];
-      inPageTools?: object;
+      thirdPartyDeveloperTools?: object;
       webmcpTools?: object[];
       message?: string;
       networkConditions?: string;
@@ -1004,13 +1004,17 @@ Call ${handleDialog.name} to handle it before continuing.`);
       }
     }
 
-    if (this.#listInPageTools) {
-      structuredContent.inPageTools = data.inPageTools ?? undefined;
-      response.push('## In-page tools');
-      if (!data.inPageTools || !data.inPageTools.tools) {
-        response.push('No in-page tools available.');
+    if (this.#listThirdPartyDeveloperTools) {
+      structuredContent.thirdPartyDeveloperTools =
+        data.thirdPartyDeveloperTools ?? undefined;
+      response.push('## Third-party developer tools');
+      if (
+        !data.thirdPartyDeveloperTools ||
+        !data.thirdPartyDeveloperTools.tools
+      ) {
+        response.push('No third-party developer tools available.');
       } else {
-        const toolGroup = data.inPageTools;
+        const toolGroup = data.thirdPartyDeveloperTools;
         response.push(`${toolGroup.name}: ${toolGroup.description}`);
         response.push('Available tools:');
         const toolDefinitionsMessage = toolGroup.tools

src/TextSnapshot.ts

@@ -149,8 +149,8 @@ export class TextSnapshot {
   }
 
   // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
-  // returned by in-page tools. We insert them into the tree by finding the closest ancestor in the
-  // tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
+  // returned by third-party developer tools. We insert them into the tree by finding the closest ancestor
+  // in the tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
   private static async insertExtraNodes(
     page: McpPage,
     idToNode: Map<string, TextSnapshotNode>,

src/bin/chrome-devtools-cli-options.ts

@@ -196,6 +196,25 @@ export const commands: Commands = {
       },
     },
   },
+  execute_3p_developer_tool: {
+    description:
+      'Executes a tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)',
+    category: 'Third-party',
+    args: {
+      toolName: {
+        name: 'toolName',
+        type: 'string',
+        description: 'The name of the tool to execute',
+        required: true,
+      },
+      params: {
+        name: 'params',
+        type: 'string',
+        description: 'The JSON-stringified parameters to pass to the tool',
+        required: false,
+      },
+    },
+  },
   execute_webmcp_tool: {
     description:
       'Executes a WebMCP tool exposed by the page. (requires flag: --categoryExperimentalWebmcp=true)',
@@ -425,6 +444,12 @@ export const commands: Commands = {
       },
     },
   },
+  list_3p_developer_tools: {
+    description:
+      "Lists all third-party developer tools the page exposes for providing runtime information.\n  Third-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.\n  Alternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the\n  following command to the script:\n  'window.__dtmcp.executeTool(toolName, params)'\n  This might be helpful when the third-party developer tools return non-serializable values or when composing\n  third-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)",
+    category: 'Third-party',
+    args: {},
+  },
   list_console_messages: {
     description:
       'List all console messages for the currently selected page since the last navigation.',

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -237,12 +237,11 @@ export const cliOptions = {
     describe:
       'Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.',
   },
-  categoryExperimentalInPage: {
+  categoryExperimentalThirdParty: {
     type: 'boolean',
-    hidden: true,
     default: false,
     describe:
-      'Set to true to enable tools exposed by the inspected page itself',
+      'Set to true to enable third-party developer tools exposed by the inspected page itself',
   },
   performanceCrux: {
     type: 'boolean',

src/telemetry/flag_usage_metrics.json

@@ -272,10 +272,20 @@
   },
   {
     "name": "category_experimental_in_page_present",
-    "flagType": "boolean"
+    "flagType": "boolean",
+    "isDeprecated": true
   },
   {
     "name": "category_experimental_in_page",
+    "flagType": "boolean",
+    "isDeprecated": true
+  },
+  {
+    "name": "category_experimental_third_party_present",
+    "flagType": "boolean"
+  },
+  {
+    "name": "category_experimental_third_party",
     "flagType": "boolean"
   },
   {

src/telemetry/tool_call_metrics.json

@@ -115,7 +115,7 @@
     ]
   },
   {
-    "name": "execute_in_page_tool",
+    "name": "execute_3p_developer_tool",
     "args": [
       {
         "name": "tool_name_length",
@@ -253,7 +253,7 @@
     "args": []
   },
   {
-    "name": "list_in_page_tools",
+    "name": "list_3p_developer_tools",
     "args": []
   },
   {