browser_evaluate
Destructive
Execute JavaScript code on web pages or specific elements to extract data, manipulate content, or automate interactions during browser automation sessions.
Instructions
Evaluate JavaScript expression on page or element
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| function | Yes | () => { /* code */ } or (element) => { /* code */ } when element is provided | |
| element | No | Human-readable element description used to obtain permission to interact with the element | |
| ref | No | Exact target element reference from the page snapshot |
Implementation Reference
- src/tools/evaluate.ts:41-57 (handler)Handler function for the browser_evaluate tool that evaluates the provided JavaScript function on the page or a specific element locator.
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 browser_evaluate: function (JS code), element (optional description), ref (optional element reference).
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)Tool definition and export using defineTabTool, specifying name 'browser_evaluate', schema, capability 'core', and the handle function.
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'); }); }, }); - src/tools.ts:36-52 (registration)Imports evaluate.ts (line 20) and spreads its tools (line 40) into the central allTools array used for tool registration.
export const allTools: Tool<any>[] = [ ...common, ...console, ...dialogs, ...evaluate, ...files, ...install, ...keyboard, ...navigate, ...network, ...mouse, ...pdf, ...screenshot, ...snapshot, ...tabs, ...wait, ];