Back to docs

Tool Evaluate Script

Category: Browser Automation · Tier: Free

Run JavaScript in the page context and return the result. It compiles a script the same way as the CLI's cbrowser evaluate, so a declaration, a return or a function works without wrapping.

evaluate_script is red zone. A script can click, submit or delete without passing the element-level gate that click, press_key, type_text and drag apply, so the tool refuses and runs nothing unless force is true. For reading the page, extract, analyze_page and get_console_messages need no force.

Parameters

Parameter Type Required Description
script string Yes JavaScript to run: an expression, statements, a body with return, or a function literal
args array No Arguments for a function-literal script, and in scope as args for the other forms. JSON values only. Default []
force boolean To run Must be true. Without it the call is refused and nothing runs
_browserToken string No Browser session token

What you can pass

  • An expression returns its value: document.title
  • Statements return the value of the last one: function t() { return document.title }; t()
  • A body with a top-level return runs as a function body
  • A function literal such as (sel) => ... is called with args

Examples

On https://example.com:

{
  "script": "document.title",
  "force": true
}
→ { "result": "Example Domain",
    "zone": "red" }

{
  "script":
    "(t) => document.title === t",
  "args": ["Example Domain"],
  "force": true
}
→ { "result": true, "zone": "red" }

{
  "script":
    "return document.links.length;",
  "force": true
}
→ { "result": 1, "zone": "red" }

Without force

The call is refused before a browser is touched. The response is a tool error (isError: true) with the fields every red-zone refusal carries:

Field Value
success false
tool "evaluate_script"
zone "red"
result null
message The gate's reason, then "Re-run with force: true (the MCP tool parameter; --force is the CLI flag)."
howToRun "Re-run with force: true (the MCP tool parameter; --force is the CLI flag)."

On the hosted server a refused call is refunded, because nothing ran.

From the Blog