fix: improve tool descriptions (#965)

madhaviai · dependabot[bot] · OrKoN · web-flow · commit bdbbc84c125b · 2026-03-05T06:47:15.000Z
Addresses cases where DevTools MCP tools were not consistently picked up from natural language prompts by improving tool descriptions and metadata. Validation: Tested locally across multiple prompts related to LCP and page performance. MCP tools were selected more consistently after the description updates. Refs #940 --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com> Co-authored-by: Nikolay Vitkov <34244704+Lightning00Blade@users.noreply.github.com> Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
 
-# Chrome DevTools MCP Tool Reference (~6915 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~6927 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)
@@ -165,7 +165,7 @@
 
 ### `navigate_page`
 
-**Description:** Navigates the currently selected page to a URL.
+**Description:** Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.
 
 **Parameters:**
 
@@ -180,7 +180,7 @@
 
 ### `new_page`
 
-**Description:** Creates a new page
+**Description:** Open a new tab and load a URL. Use project URL if not specified otherwise.
 
 **Parameters:**
 
@@ -256,7 +256,7 @@
 
 ### `performance_start_trace`
 
-**Description:** Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.
+**Description:** Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.
 
 **Parameters:**
 
@@ -268,7 +268,7 @@
 
 ### `performance_stop_trace`
 
-**Description:** Stops the active performance trace recording on the selected page.
+**Description:** Stop the active performance trace recording on the selected webpage.
 
 **Parameters:**
 
diff --git a/scripts/eval_scenarios/fix_webpage_issues_test.ts b/scripts/eval_scenarios/fix_webpage_issues_test.ts
@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Eval scenario: user asks to fix issues with their webpage (no URL given).
+ * When no URL is provided, the model should pick the current frontend and run
+ * and inspect it. Verifies the MCP server is invoked and the model opens the
+ * frontend and inspects it (snapshot, console, or network).
+ *
+ * Note: Tools like performance_start_trace, take_snapshot, list_console_messages,
+ * and list_network_requests do not require a URL in the prompt—they operate on
+ * the currently selected page. Only navigate_page/new_page need a URL to open
+ * a page; the eval runner injects the test URL when htmlRoute is set.
+ */
+
+import assert from 'node:assert';
+
+import type {TestScenario} from '../eval_gemini.ts';
+
+const INSPECTION_TOOLS = [
+  'take_snapshot',
+  'list_console_messages',
+  'list_network_requests',
+];
+
+export const scenario: TestScenario = {
+  prompt: 'Can you fix issues with my webpage?',
+  maxTurns: 4,
+  htmlRoute: {
+    path: '/fix_issues_test.html',
+    htmlContent: `
+      <h1>Test Page</h1>
+      <p>Some content</p>
+      <script>
+        console.error('Intentional error for testing');
+      </script>
+    `,
+  },
+  expectations: calls => {
+    const NAVIGATION_TOOLS = ['navigate_page', 'new_page'];
+    assert.ok(
+      calls.length >= 2,
+      'Expected at least navigation and one inspection',
+    );
+    const navigationIndex = calls.findIndex(c =>
+      NAVIGATION_TOOLS.includes(c.name),
+    );
+    assert.ok(
+      navigationIndex !== -1,
+      `Expected a navigation call (${NAVIGATION_TOOLS.join(' or ')}), got: ${calls.map(c => c.name).join(', ')}`,
+    );
+    const afterNavigation = calls.slice(navigationIndex + 1);
+    const inspectionCalls = afterNavigation.filter(c =>
+      INSPECTION_TOOLS.includes(c.name),
+    );
+    assert.ok(
+      inspectionCalls.length >= 1,
+      `Expected at least one inspection tool (${INSPECTION_TOOLS.join(', ')}) after navigation, got: ${calls.map(c => c.name).join(', ')}`,
+    );
+  },
+};
diff --git a/scripts/eval_scenarios/frontend_snapshot_test.ts b/scripts/eval_scenarios/frontend_snapshot_test.ts
@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Eval scenario using "website"/"webpage" wording to verify the model invokes
+ * the right tools when users ask to open a site and read its content.
+ */
+
+import assert from 'node:assert';
+
+import type {TestScenario} from '../eval_gemini.ts';
+
+export const scenario: TestScenario = {
+  prompt:
+    'Open the website at <TEST_URL> and tell me what content is on the page.',
+  maxTurns: 3,
+  htmlRoute: {
+    path: '/frontend_snapshot.html',
+    htmlContent: '<h1>Frontend Test</h1><p>This is a test webpage.</p>',
+  },
+  expectations: calls => {
+    assert.strictEqual(calls.length, 2);
+    assert.ok(
+      calls[0].name === 'navigate_page' || calls[0].name === 'new_page',
+      'First call should be navigation',
+    );
+    assert.strictEqual(
+      calls[1].name,
+      'take_snapshot',
+      'Second call should be take_snapshot to read page content',
+    );
+  },
+};
diff --git a/src/tools/pages.ts b/src/tools/pages.ts
@@ -87,7 +87,7 @@ export const closePage = defineTool({
 
 export const newPage = defineTool({
   name: 'new_page',
-  description: `Creates a new page`,
+  description: `Open a new tab and load a URL. Use project URL if not specified otherwise.`,
   annotations: {
     category: ToolCategory.NAVIGATION,
     readOnlyHint: false,
@@ -131,7 +131,7 @@ export const newPage = defineTool({
 
 export const navigatePage = definePageTool({
   name: 'navigate_page',
-  description: `Navigates the currently selected page to a URL.`,
+  description: `Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.`,
   annotations: {
     category: ToolCategory.NAVIGATION,
     readOnlyHint: false,
diff --git a/src/tools/performance.ts b/src/tools/performance.ts
@@ -28,7 +28,7 @@ const filePathSchema = zod
 
 export const startTrace = definePageTool({
   name: 'performance_start_trace',
-  description: `Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.`,
+  description: `Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.`,
   annotations: {
     category: ToolCategory.PERFORMANCE,
     readOnlyHint: false,
@@ -117,7 +117,7 @@ export const startTrace = definePageTool({
 export const stopTrace = definePageTool({
   name: 'performance_stop_trace',
   description:
-    'Stops the active performance trace recording on the selected page.',
+    'Stop the active performance trace recording on the selected webpage.',
   annotations: {
     category: ToolCategory.PERFORMANCE,
     readOnlyHint: false,
