Skip to main content
Glama

Open a browser

open_browser
Destructive

Opens a real Chromium browser on SpecStream's server and returns its session id. Drive it with the browser_ tools (browser_navigate, browser_snapshot, browser_click, browser_type, browser_take_screenshot, browser_read and the others) with that session_id, or hand its connect_url to Playwright, Puppeteer, browser-use or Stagehand. Use it for pages that need a real browser: forms, clicks, pages drawn by scripts. For the text of known pages read_pages is faster and cheaper. A page whose site opted out, whose robots.txt disallows SpecStream or that is outside allowed_domains answers blocked. The session ends at close_browser, after idle_timeout_s with no step or connection, or at timeout_s (default 300 seconds, at most 3,600). Charged $0.10 an hour by the second while it runs (at most 10¢ a session), plus $1 per 1,000 steps (0.1¢ a step). A session that fails to start is not charged.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "open_browser"
  }
}

Input Schema

NameRequiredDescriptionDefault
headlessNofalse runs the browser with a screen, for sites that act differently without one. It uses more memory.
metadataNoYour own labels for the session, returned as sent.
viewportNoThe browser window's size in pixels.
timeout_sNoThe most seconds the session runs. It ends then, connected or not.
keep_aliveNotrue keeps the session when the client disconnects, so a new client can connect, until idle_timeout_s passes. false ends it at the disconnect.
block_mediaNotrue skips images, video, audio and fonts: pages load faster and the session reads fewer bytes.
idle_timeout_sNoThe session ends after this many seconds with no client connected and no action. With keep_alive false, a disconnect ends it at once.
allowed_domainsNoHosts the browser may open, such as example.com or *.example.com. Empty allows every public host. A page outside them is refused with blocked.

Output Schema

NameRequiredDescriptionDefault
idNo
bytesNo
priceNo
limitsNo
statusNo
actionsNo
secondsNo
ended_atNo
headlessNo
live_urlNo
metadataNo
viewportNo
timeout_sNo
created_atNo
expires_atNo
keep_aliveNo
started_atNo
actions_urlNo
block_mediaNo
charged_usdNo
connect_urlNo
ended_reasonNo
idle_timeout_sNo
allowed_domainsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "actions": {
      +      "type": "integer"
      +    },
      +    "actions_url": {
      +      "type": "string"
      +    },
      +    "allowed_domains": {
      +      "items": {},
      +      "type": "array"
      +    },
      +    "block_media": {
      +      "type": "boolean"
      +    },
      +    "bytes": {
      +      "type": "integer"
      +    },
      +    "charged_usd": {
      +      "type": "number"
      +    },
      +    "connect_url": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "created_at": {
      +      "type": "string"
      +    },
      +    "ended_at": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "ended_reason": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "expires_at": {
      +      "type": "string"
      +    },
      +    "headless": {
      +      "type": "boolean"
      +    },
      +    "id": {
      +      "type": "string"
      +    },
      +    "idle_timeout_s": {
      +      "type": "integer"
      +    },
      +    "keep_alive": {
      +      "type": "boolean"
      +    },
      +    "limits": {
      +      "type": "object"
      +    },
      +    "live_url": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "metadata": {
      +      "type": "object"
      +    },
      +    "price": {
      +      "type": "object"
      +    },
      +    "seconds": {
      +      "type": "integer"
      +    },
      +    "started_at": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "status": {
      +      "type": "string"
      +    },
      +    "timeout_s": {
      +      "type": "integer"
      +    },
      +    "viewport": {
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed3 schema fields changed
    • addedInput schema / $defs / Viewport / properties / height / description
      Added value: +"The window's height in pixels."
    • addedInput schema / $defs / Viewport / properties / width / description
      Added value: +"The window's width in pixels."
    • addedInput schema / properties / viewport / description
      Added value: +"The browser window's size in pixels."
  3. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing session lifecycle (close_browser, idle timeout, hard timeout), billing ($0.10/hr capped at 10¢ plus $1 per 1,000 steps), and that failed starts are not charged. It also explains what 'blocked' means (opt-out, robots.txt, allowed_domains).

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

Conciseness4/5

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

Front-loaded with action, resource, and return value, then usage, then lifecycle and cost — a sensible order. It is dense and nearly every sentence carries information, though the pricing granularity ('charged $0.10 an hour by the second... 0.1¢ a step') is the one passage that could be tightened.

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 stateful, billable, open-world resource-creating tool, the description covers creation, driving, termination, failure modes, and cost — everything an agent needs before calling. An output schema exists, so return-shape explanation is correctly omitted.

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 the schema already documents all eight parameters including defaults and ranges. The description adds some consequence-level meaning for allowed_domains and timeouts (session ends at timeout_s even if connected; blocked on out-of-domain pages), but most parameter detail is restatement. Baseline 3 is appropriate.

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 — 'Opens a real Chromium browser on SpecStream's server' — plus the return value (session id). It immediately differentiates itself from the browser_* family (which drive the session) and from read_pages (cheaper for text of known pages).

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?

Gives explicit when-to-use ('pages that need a real browser: forms, clicks, pages drawn by scripts') and when-not ('For the text of known pages read_pages is faster and cheaper'). It also names the follow-on tools and external alternatives (Playwright, Puppeteer, browser-use, Stagehand) via connect_url, and explains the blocked outcome conditions.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.