Skip to main content
Glama

evaluate_js

Run JavaScript in the browser page to return its value, await promises, and preview complex or thrown results.

Instructions

Evaluates JavaScript in the page and returns its value (promises awaited; top-level await works in code up to 64 KB that parses, the last statement giving the value; other code runs as written): {value, type, subtype?, description?, preview?}. value is the JSON form; a Map, Set, typed array, Error, cycle or throwing getter gets a bounded preview (preview: true; a Map as [key, value] pairs, a Set or typed array as items, an Error as {name, message, stack}, '[Circular]', '[Thrown: message]') that description names (Map(2), TypeError: bad); functions, nodes and symbols give null, described (a function's source). Cut over 100000 characters (truncated: true). An exception fails with its message, and its 1-based line and column when they are in the expression. user_gesture: true lets the expression call APIs that need a user action (requestFullscreen, clipboard writes, window.open past the popup blocker); off by default, as the page then gets that power. In a paused frame use evaluate_on_call_frame (--tool-groups debug). Chrome stops a script after 8 s; Firefox cannot (close a frozen tab with close_tab).

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": {
      "expression": "<expression>"
    },
    "name": "evaluate_js"
  }
}

Input Schema

NameRequiredDescriptionDefault
tab_idNoDefault: the active tab.
expressionYesA JavaScript expression or IIFE.
instance_idNoDefault: 'default'.
user_gestureNoRun it as if the user had just interacted, for APIs that need it (fullscreen, clipboard, popups). Default: false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0-rc.1

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so thoroughly: it discloses awaiting behavior, the 64 KB / 100000-character limits, truncation and preview flags, how Maps/Sets/Errors/cycles/functions/symbols are represented, and that exceptions fail with message plus line and column. It also discloses the security implication of user_gesture (the page gains that power) and the divergent timeouts (Chrome 8 s, Firefox cannot stop), which is exactly the kind of non-obvious behavior an agent needs.

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

Conciseness3/5

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

The essential purpose is front-loaded, but the rest is a single dense block riddled with nested parentheticals (the preview list inside a parenthetical inside a sentence) that is hard to scan. Almost every clause carries information, but it would read far better as short bulleted sentences.

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

Completeness5/5

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

For a four-parameter tool with no output schema and no annotations, the description supplies the return shape, edge-case representations, limits, error format, and cross-browser timeout caveats. Nothing an agent needs to invoke it correctly appears missing.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the 64 KB size ceiling on expression code, what top-level await does to the returned value, and the concrete consequence of user_gesture being enabled. tab_id and instance_id are left to the schema, which already documents their defaults.

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?

The opening sentence gives a specific verb and resource ("Evaluates JavaScript in the page and returns its value") and immediately scopes behavior with "promises awaited; top-level await works." It also names the sibling appropriate for a different situation (evaluate_on_call_frame for paused frames), so an agent can distinguish this tool without opening the schema.

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

Usage Guidelines4/5

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

It explicitly routes paused-frame work to evaluate_on_call_frame and states the condition under which user_gesture should be turned on (fullscreen, clipboard, popups). It does not discuss when a structured alternative like inspect_dom or snapshot should be preferred over raw JS, leaving one meaningful choice implicit.

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