browser_evaluate
Execute JavaScript expressions on web pages or specific elements using structured accessibility snapshots, enabling precise interactions without screenshots or visual models.
Instructions
Evaluate JavaScript expression on page or element
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| element | No | Human-readable element description used to obtain permission to interact with the element | |
| function | Yes | () => { /* code */ } or (element) => { /* code */ } when element is provided | |
| ref | No | Exact target element reference from the page snapshot |
Implementation Reference
- src/tools/evaluate.ts:41-57 (handler)The main handler function for the browser_evaluate tool. It handles JavaScript evaluation on the page or a specific element, generates corresponding code snippets, waits for execution completion, and adds the result to the response.handle: async (tab, params, response) => { response.setIncludeSnapshot(); let locator: playwright.Locator | undefined; if (params.ref && params.element) { locator = await tab.refLocator({ ref: params.ref, element: params.element }); response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`); } else { response.addCode(`await page.evaluate(${javascript.quote(params.function)});`); } await tab.waitForCompletion(async () => { const receiver = locator ?? tab.page as any; const result = await receiver._evaluateFunction(params.function); response.addResult(JSON.stringify(result, null, 2) || 'undefined'); }); },
- src/tools/evaluate.ts:25-29 (schema)Zod schema defining the input parameters for the browser_evaluate tool: function (string, required), element (string, optional), ref (string, optional).const evaluateSchema = z.object({ function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'), element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'), ref: z.string().optional().describe('Exact target element reference from the page snapshot'), });
- src/tools/evaluate.ts:31-58 (registration)Registration of the browser_evaluate tool using defineTabTool, specifying capability, schema (including name 'browser_evaluate'), and the handler function. The tool is then exported for use.const evaluate = defineTabTool({ capability: 'core', schema: { name: 'browser_evaluate', title: 'Evaluate JavaScript', description: 'Evaluate JavaScript expression on page or element', inputSchema: evaluateSchema, type: 'destructive', }, handle: async (tab, params, response) => { response.setIncludeSnapshot(); let locator: playwright.Locator | undefined; if (params.ref && params.element) { locator = await tab.refLocator({ ref: params.ref, element: params.element }); response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`); } else { response.addCode(`await page.evaluate(${javascript.quote(params.function)});`); } await tab.waitForCompletion(async () => { const receiver = locator ?? tab.page as any; const result = await receiver._evaluateFunction(params.function); response.addResult(JSON.stringify(result, null, 2) || 'undefined'); }); }, });