evaluate_script
Execute JavaScript functions in a live Chrome browser page to retrieve JSON-serializable data for automation, debugging, or content extraction.
Instructions
Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON so returned values have to JSON-serializable.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| function | Yes | A JavaScript function to run in the currently selected page. Example without arguments: `() => { return document.title }` or `async () => { return await fetch("example.com") }`. Example with arguments: `(el) => { return el.innerText; }` | |
| args | No | An optional list of arguments to pass to the function. |
Implementation Reference
- src/tools/script.ts:46-72 (handler)The main handler function for the 'evaluate_script' tool. It evaluates the provided JavaScript function on the currently selected page using Puppeteer, passes optional element arguments by UID, serializes the result to JSON, and appends the output to the response.handler: async (request, response, context) => { const page = context.getSelectedPage(); const fn = await page.evaluateHandle(`(${request.params.function})`); const args: Array<JSHandle<unknown>> = [fn]; try { for (const el of request.params.args ?? []) { args.push(await context.getElementByUid(el.uid)); } await context.waitForEventsAfterAction(async () => { const result = await page.evaluate( async (fn, ...args) => { // @ts-expect-error no types. return JSON.stringify(await fn(...args)); }, ...args, ); response.appendResponseLine('Script ran on page and returned:'); response.appendResponseLine('```json'); response.appendResponseLine(`${result}`); response.appendResponseLine('```'); }); } finally { Promise.allSettled(args.map(arg => arg.dispose())).catch(() => { // Ignore errors }); } },
- src/tools/script.ts:20-45 (schema)Zod schema defining the input parameters for the tool: 'function' (string describing the JS function to evaluate) and optional 'args' (array of {uid: string} for page elements).schema: { function: z.string().describe( `A JavaScript function to run in the currently selected page. Example without arguments: \`() => { return document.title }\` or \`async () => { return await fetch("example.com") }\`. Example with arguments: \`(el) => { return el.innerText; }\` `, ), args: z .array( z.object({ uid: z .string() .describe( 'The uid of an element on the page from the page content snapshot', ), }), ) .optional() .describe(`An optional list of arguments to pass to the function.`), },
- src/tools/script.ts:12-73 (registration)The tool registration using defineTool, including name 'evaluate_script', description, annotations, schema, and handler.export const evaluateScript = defineTool({ name: 'evaluate_script', description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON so returned values have to JSON-serializable.`, annotations: { category: ToolCategories.DEBUGGING, readOnlyHint: false, }, schema: { function: z.string().describe( `A JavaScript function to run in the currently selected page. Example without arguments: \`() => { return document.title }\` or \`async () => { return await fetch("example.com") }\`. Example with arguments: \`(el) => { return el.innerText; }\` `, ), args: z .array( z.object({ uid: z .string() .describe( 'The uid of an element on the page from the page content snapshot', ), }), ) .optional() .describe(`An optional list of arguments to pass to the function.`), }, handler: async (request, response, context) => { const page = context.getSelectedPage(); const fn = await page.evaluateHandle(`(${request.params.function})`); const args: Array<JSHandle<unknown>> = [fn]; try { for (const el of request.params.args ?? []) { args.push(await context.getElementByUid(el.uid)); } await context.waitForEventsAfterAction(async () => { const result = await page.evaluate( async (fn, ...args) => { // @ts-expect-error no types. return JSON.stringify(await fn(...args)); }, ...args, ); response.appendResponseLine('Script ran on page and returned:'); response.appendResponseLine('```json'); response.appendResponseLine(`${result}`); response.appendResponseLine('```'); }); } finally { Promise.allSettled(args.map(arg => arg.dispose())).catch(() => { // Ignore errors }); } }, });