Merge pull request #18 from tontoko/refactor/simplify-tool-descriptions

Refine tool and schema descriptions for clarity and guidance

Author: tontoko

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tontoko/fast-playwright-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },

src/schemas/expectation.ts

@@ -4,9 +4,15 @@ import { z } from 'zod';
  */
 export const diffOptionsSchema = z
   .object({
-    enabled: z.boolean().default(false),
+    enabled: z
+      .boolean()
+      .default(false)
+      .describe('Show only changes (saves ~80% tokens)'),
     threshold: z.number().min(0).max(1).default(0.1),
-    format: z.enum(['unified', 'split', 'minimal']).default('unified'),
+    format: z
+      .enum(['unified', 'split', 'minimal'])
+      .default('unified')
+      .describe('Diff format ("minimal" for smallest output)'),
     maxDiffLines: z.number().positive().default(50),
     ignoreWhitespace: z.boolean().default(true),
     context: z.number().min(0).default(3),
@@ -17,7 +23,11 @@ export const diffOptionsSchema = z
  */
 export const expectationSchema = z
   .object({
-    includeSnapshot: z.boolean().optional().default(false),
+    includeSnapshot: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe('Include accessibility tree (false for chained actions)'),
     includeConsole: z.boolean().optional().default(false),
     includeDownloads: z.boolean().optional().default(false),
     includeTabs: z.boolean().optional().default(false),
@@ -27,11 +37,8 @@ export const expectationSchema = z
         selector: z
           .string()
           .optional()
-          .describe('CSS selector to limit snapshot scope'),
-        maxLength: z
-          .number()
-          .optional()
-          .describe('Maximum characters for snapshot'),
+          .describe('CSS selector to limit scope (e.g., ".result", "form")'),
+        maxLength: z.number().optional().describe('Max snapshot characters'),
         format: z.enum(['aria', 'text', 'html']).optional().default('aria'),
       })
       .optional(),

src/tools/batch-execute.ts

@@ -13,7 +13,8 @@ export const batchExecuteTool = defineTool({
   schema: {
     name: 'browser_batch_execute',
     title: 'Batch Execute Browser Actions',
-    description: `Execute multiple browser actions in sequence with optimized response handling.RECOMMENDED:Use this tool instead of individual actions when performing multiple operations to significantly reduce token usage and improve performance.BY DEFAULT use for:form filling(multiple type→click),multi-step navigation,any workflow with 2+ known steps.Saves 90% tokens vs individual calls.globalExpectation:{includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}.Per-step override:steps[].expectation.Example:[{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{element:"username",ref:"#user",text:"john"}},{tool:"browser_click",arguments:{element:"submit",ref:"#btn"}}].Tool names must match exactly(e.g.browser_navigate,browser_click,browser_type).`,
+    description:
+      'Execute multiple browser actions in sequence. PREFER over individual tools for 2+ operations.',
     inputSchema: batchExecuteSchema,
     type: 'destructive',
   },

src/tools/dialogs.ts

@@ -7,14 +7,13 @@ const handleDialog = defineTabTool({
   schema: {
     name: 'browser_handle_dialog',
     title: 'Handle a dialog',
-    description: `Handle a dialog(alert,confirm,prompt).accept:true to accept,false to dismiss.promptText:"answer" for prompt dialogs.expectation:{includeSnapshot:true} to see page after dialog handling.USE batch_execute if dialog appears during workflow.`,
+    description: 'Handle a dialog (alert, confirm, prompt)',
     inputSchema: z.object({
-      accept: z.boolean().describe('Whether to accept the dialog.'),
-      promptText: z
-        .string()
-        .optional()
-        .describe('The text of the prompt in case of a prompt dialog.'),
-      expectation: expectationSchema,
+      accept: z.boolean().describe('Accept (true) or dismiss (false)'),
+      promptText: z.string().optional().describe('Text for prompt dialogs'),
+      expectation: expectationSchema.describe(
+        'Page state after dialog. Use batch_execute for workflows'
+      ),
     }),
     type: 'destructive',
   },

src/tools/evaluate.ts

@@ -8,9 +8,7 @@ import { generateLocator } from './utils.js';
 const evaluateSchema = z.object({
   function: z
     .string()
-    .describe(
-      '() => { /* code */ } or (element) => { /* code */ } when element is provided'
-    ),
+    .describe('JS function: () => {...} or (element) => {...}'),
   element: z
     .string()
     .optional()
@@ -23,15 +21,17 @@ const evaluateSchema = z.object({
     .describe(
       'System-generated element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values.'
     ),
-  expectation: expectationSchema,
+  expectation: expectationSchema.describe(
+    'Page state config. false for data extraction, true for DOM changes'
+  ),
 });
 const evaluate = defineTabTool({
   capability: 'core',
   schema: {
     name: 'browser_evaluate',
     title: 'Evaluate JavaScript',
     description:
-      'Evaluate JavaScript expression on page or element.Returns evaluation result.USE CASES:extract data,modify DOM,trigger events.expectation:{includeSnapshot:false} for data extraction,true if modifying page.element+ref to run on specific element.CONSIDER batch_execute for multiple evaluations.',
+      'Evaluate JavaScript expression on page or element and return result',
     inputSchema: evaluateSchema,
     type: 'destructive',
   },

src/tools/files.ts

@@ -7,14 +7,12 @@ const uploadFile = defineTabTool({
   schema: {
     name: 'browser_file_upload',
     title: 'Upload files',
-    description: `Upload one or multiple files to file input.paths:["/path/file1.jpg","/path/file2.pdf"] for multiple files.expectation:{includeSnapshot:true,snapshotOptions:{selector:"form"}} to verify upload.Must be triggered after file input interaction.USE batch_execute for click→upload workflows.`,
+    description: 'Upload one or multiple files to file input',
     inputSchema: z.object({
-      paths: z
-        .array(z.string())
-        .describe(
-          'The absolute paths to the files to upload. Can be a single file or multiple files.'
-        ),
-      expectation: expectationSchema,
+      paths: z.array(z.string()).describe('Absolute paths to upload (array)'),
+      expectation: expectationSchema.describe(
+        'Page state config. Use batch_execute for click→upload'
+      ),
     }),
     type: 'destructive',
   },

src/tools/keyboard.ts

@@ -11,15 +11,12 @@ const pressKey = defineTabTool({
   schema: {
     name: 'browser_press_key',
     title: 'Press a key',
-    description:
-      'Press a key on the keyboard.Common keys:Enter,Escape,ArrowUp/Down/Left/Right,Tab,Backspace.expectation:{includeSnapshot:false} for navigation keys,true for content changes.CONSIDER batch_execute for multiple key presses.',
+    description: 'Press a key on the keyboard',
     inputSchema: z.object({
-      key: z
-        .string()
-        .describe(
-          'Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'
-        ),
-      expectation: expectationSchema,
+      key: z.string().describe('Key to press'),
+      expectation: expectationSchema.describe(
+        'Page state config. Use batch_execute for multiple keys'
+      ),
     }),
     type: 'destructive',
   },
@@ -45,27 +42,24 @@ const typeSchema = elementSchema.extend({
   ref: z
     .string()
     .describe(
-      'System-generated element ID from previous tool results (e.g., "rNODE-45-1"). Never use custom values.'
+      'System-generated element ID from previous tool results. Never use custom values.'
     ),
-  text: z.string().describe('Text to type into the element'),
-  submit: z
-    .boolean()
-    .optional()
-    .describe('Whether to submit entered text (press Enter after)'),
+  text: z.string(),
+  submit: z.boolean().optional().describe('Press Enter after typing if true'),
   slowly: z
     .boolean()
     .optional()
-    .describe(
-      'Whether type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.'
-    ),
-  expectation: expectationSchema,
+    .describe('Type slowly for auto-complete if true'),
+  expectation: expectationSchema.describe(
+    'Page state config. Use batch_execute for forms'
+  ),
 });
 const type = defineTabTool({
   capability: 'core',
   schema: {
     name: 'browser_type',
     title: 'Type text',
-    description: `Type text into editable element.FOR FORMS:Use batch_execute to fill multiple fields efficiently.slowly:true for auto-complete fields,submit:true to press Enter after.expectation:{includeSnapshot:false} when filling multiple fields(use batch),true for final verification.snapshotOptions:{selector:"form"} to focus on form only.diffOptions:{enabled:true} shows only what changed in form.`,
+    description: 'Type text into editable element',
     inputSchema: typeSchema,
     type: 'destructive',
   },

src/tools/mouse.ts

@@ -39,12 +39,13 @@ const mouseClick = defineTabTool({
   schema: {
     name: 'browser_mouse_click_xy',
     title: 'Click',
-    description:
-      'Click at specific coordinates.Requires --caps=vision.x,y:click position.expectation:{includeSnapshot:true} to verify result.PREFER browser_click with element ref over coordinates.USE batch_execute for coordinate-based workflows.',
+    description: 'Click at specific coordinates',
     inputSchema: elementSchema.extend({
-      x: z.number().describe('X coordinate'),
-      y: z.number().describe('Y coordinate'),
-      expectation: expectationSchema,
+      x: z.number().describe('X coordinate (requires --caps=vision)'),
+      y: z.number().describe('Y coordinate (requires --caps=vision)'),
+      expectation: expectationSchema.describe(
+        'Page state after click. Prefer element ref over coords'
+      ),
     }),
     type: 'destructive',
   },
@@ -69,13 +70,15 @@ const mouseDrag = defineTabTool({
   schema: {
     name: 'browser_mouse_drag_xy',
     title: 'Drag mouse',
-    description: `Drag from one coordinate to another.Requires --caps=vision.startX,startY→endX,endY.expectation:{includeSnapshot:true,snapshotOptions:{selector:".drop-zone"}} to verify.PREFER browser_drag with element refs over coordinates.`,
+    description: 'Drag from one coordinate to another',
     inputSchema: elementSchema.extend({
-      startX: z.number().describe('Start X coordinate'),
-      startY: z.number().describe('Start Y coordinate'),
-      endX: z.number().describe('End X coordinate'),
-      endY: z.number().describe('End Y coordinate'),
-      expectation: expectationSchema,
+      startX: z.number().describe('Start X (requires --caps=vision)'),
+      startY: z.number().describe('Start Y (requires --caps=vision)'),
+      endX: z.number().describe('End X'),
+      endY: z.number().describe('End Y'),
+      expectation: expectationSchema.describe(
+        'Page state after drag. Prefer element refs over coords'
+      ),
     }),
     type: 'destructive',
   },

src/tools/navigate.ts

@@ -12,10 +12,10 @@ const navigate = defineTool({
   schema: {
     name: 'browser_navigate',
     title: 'Navigate to a URL',
-    description: `Navigate to a URL.expectation:{includeSnapshot:true} to see what loaded,false if you know what to do next.snapshotOptions:{selector:"#content"} to focus on main content(saves 50% tokens).diffOptions:{enabled:true} when revisiting pages to see only changes.CONSIDER batch_execute for navigate→interact workflows.`,
+    description: 'Navigate to a URL',
     inputSchema: z.object({
       url: z.string().describe('The URL to navigate to'),
-      expectation: expectationSchema,
+      expectation: expectationSchema.describe('Page state after navigation'),
     }),
     type: 'destructive',
   },
@@ -29,11 +29,10 @@ const goBack = defineTabTool({
   capability: 'core',
   schema: {
     name: 'browser_navigate_back',
-    title: 'Go back',
-    description:
-      'Go back to previous page.expectation:{includeSnapshot:true} to see previous page,false if continuing workflow.diffOptions:{enabled:true} shows only what changed from forward page.USE batch_execute for back→interact sequences.',
+    title: 'Go back to previous page',
+    description: 'Go back to previous page',
     inputSchema: z.object({
-      expectation: expectationSchema,
+      expectation: expectationSchema.describe('Page state after going back'),
     }),
     type: 'readOnly',
   },
@@ -46,11 +45,10 @@ const goForward = defineTabTool({
   capability: 'core',
   schema: {
     name: 'browser_navigate_forward',
-    title: 'Go forward',
-    description:
-      'Go forward to next page.expectation:{includeSnapshot:true} to see next page,false if continuing workflow.diffOptions:{enabled:true} shows only what changed from previous page.USE batch_execute for forward→interact sequences.',
+    title: 'Go forward to next page',
+    description: 'Go forward to next page',
     inputSchema: z.object({
-      expectation: expectationSchema,
+      expectation: expectationSchema.describe('Page state after going forward'),
     }),
     type: 'readOnly',
   },

src/tools/network.ts

@@ -8,19 +8,32 @@ import {
 import { defineTabTool } from './tool.js';
 
 const networkFilterSchema = z.object({
-  urlPatterns: z.array(z.string()).optional(),
-  excludeUrlPatterns: z.array(z.string()).optional(),
+  urlPatterns: z
+    .array(z.string())
+    .optional()
+    .describe('URL patterns to filter (supports regex)'),
+  excludeUrlPatterns: z
+    .array(z.string())
+    .optional()
+    .describe('URL patterns to exclude (takes precedence)'),
   statusRanges: z
     .array(
       z.object({
-        min: z.number(),
-        max: z.number(),
+        min: z.number().describe('Minimum status code'),
+        max: z.number().describe('Maximum status code'),
       })
     )
-    .optional(),
-  methods: z.array(z.string()).optional(),
-  maxRequests: z.number().default(20),
-  newestFirst: z.boolean().default(true),
+    .optional()
+    .describe('Status code ranges (e.g., [{min:200,max:299}])'),
+  methods: z.array(z.string()).optional().describe('HTTP methods to filter'),
+  maxRequests: z
+    .number()
+    .default(20)
+    .describe('Max requests to return (default: 20)'),
+  newestFirst: z
+    .boolean()
+    .default(true)
+    .describe('Order by timestamp (default: newest first)'),
 });
 
 const requests = defineTabTool({
@@ -29,7 +42,7 @@ const requests = defineTabTool({
     name: 'browser_network_requests',
     title: 'List network requests',
     description:
-      'Returns network requests since loading the page with optional filtering. urlPatterns:["api/users"] to filter by URL patterns. excludeUrlPatterns:["analytics"] to exclude specific patterns. statusRanges:[{min:200,max:299}] for success codes only. methods:["GET","POST"] to filter by HTTP method. maxRequests:10 to limit results. newestFirst:false for chronological order. Supports regex patterns for advanced filtering.',
+      'Returns network requests since loading the page with optional filtering',
     inputSchema: networkFilterSchema.partial(),
     type: 'readOnly',
   },