Skip to main content
Glama

evaluate_script

Run a JavaScript function in the Firefox page and return its result for targeted reads, such as values, text, computed styles, or element existence, without taking a full snapshot.

Instructions

Run a JS function in the page and return its result. Prefer this for targeted reads (a value, text, computed style, whether an element exists) instead of a full take_snapshot. Use the UID interaction tools for clicking, typing, and filling.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "function": "<function>"
    },
    "name": "evaluate_script"
  }
}

Input Schema

NameRequiredDescriptionDefault
argsNoUIDs to pass as function arguments, all from the same frame. With UIDs from an iframe, the function runs in that iframe.
saveToNoSave the result to a file as JSON instead of returning it inline. Pass a file path, an existing directory (generated file inside), or true (generated file under ~/.firefox-mcp/output/). Relative paths resolve against the current working directory.
previewNoNumber of characters of the saved result to return inline as a preview when saveTo is used. Omit for no preview.
sandboxNoEvaluate in an isolated sandbox realm with this name instead of the page realm. The sandbox shares the page DOM and keeps the native built-ins even where the page overrode them. Page-defined globals and expandos are invisible from the sandbox, and vice-versa. The same name reuses the same sandbox across calls; omit to evaluate in the page realm.
timeoutNoTimeout in ms (default: 5000)
functionYesJS function string, e.g. () => document.title

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.11.0
    • changedInput schema / properties / args / description
      Previous value: -"UIDs to pass as function arguments"New value: +"UIDs to pass as function arguments, all from the same frame. With UIDs from an iframe, the function runs in that iframe."
    • changedInput schema / properties / saveTo / description
      Previous value: -"Save the result to a file as JSON instead of returning it inline. Pass a file path, an existing directory (generated file inside), or true (generated file under ~/.firefox-devtools-mcp/output/). Relative paths resolve against the current working directory."New value: +"Save the result to a file as JSON instead of returning it inline. Pass a file path, an existing directory (generated file inside), or true (generated file under ~/.firefox-mcp/output/). Relative paths resolve against the current working directory."
  2. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / sandbox
      Added value: +{
      +  "description": "Evaluate in an isolated sandbox realm with this name instead of the page realm. The sandbox shares the page DOM and keeps the native built-ins even where the page overrode them. Page-defined globals and expandos are invisible from the sandbox, and vice-versa. The same name reuses the same sandbox across calls; omit to evaluate in the page realm.",
      +  "type": "string"
      +}
  3. Addedv0.9.15

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations supply only readOnlyHint=false, so the description carries most of the burden. 'Run a JS function in the page' conveys that arbitrary code executes in page context, but the description never warns about side effects on page state, nor mentions that functions can write files (saveTo) or run in an isolated realm (sandbox) — those live only in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each load-bearing: capability, preferred use case with the excluded alternative, and the routing rule for interaction tools. Nothing is repeated or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-power evaluation tool the routing guidance is excellent and the rich schema covers arguments, sandboxing, file output, and timeout. What is missing is a note that executed code can mutate page state and that saveTo/preview change the return shape — minor but relevant given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters (args, saveTo, preview, sandbox, timeout, function) are already documented in structured data. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Run a JS function in the page and return its result.' It also carves out scope against siblings by naming take_snapshot and the UID interaction tools, so an agent can pick it without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes when to use it ('targeted reads: a value, text, computed style, whether an element exists') and when not to ('instead of a full take_snapshot'), and redirects clicking/typing/filling to the UID tools. That is the full when/when-not/alternative triad.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.