Skip to main content
Glama

browser

Control a Chromium-family instance over CDP to navigate pages, read rendered text, inspect tabs, and evaluate JavaScript without keystrokes or OCR.

Instructions

Talk to the instance's Chromium-family browser over the Chrome DevTools Protocol — exact navigation and page text without keystrokes or OCR.

action='info' → {"ok", "url", "title", "pages": [{url, title}, …], "viewport"} of the active tab + all tabs. viewport = {dpr, left, top, css_width, css_height} maps the page's CSS pixels (getBoundingClientRect) to the pixels click()/screenshot() use: x = left + css_xdpr, y = top + css_ydpr (dpr is not 1 on a zoomed page; top is the toolbar height) action='navigate' → loads url in the active tab (waits for the load event, max 30 s); returns {"ok", "url", "title", "loaded": bool} action='text' → {"ok", "url", "title", "text", "length", "truncated"}: the rendered page text (document.body.innerText), capped at max_chars (default 20000, max 200000) action='eval' → {"ok", "result"}: the JSON value of the JavaScript expression js (e.g. "document.querySelector('h1').innerText"); a Promise is awaited. A result whose JSON is longer than max_chars (default 100000, max 1000000) comes back as {"ok", "truncated": true, "length", "result_json": the first max_chars characters} — raise max_chars or return less (slice/map in the script). Errors in the page script come back as a failure with the message timeout_s (1–600, default 30) bounds an eval or text call. On a timeout the call fails (isError, "timed_out": true) and the connection stays usable, but the script KEEPS RUNNING in the page — for long work store the outcome on window (js="fetchAll().then(r => { window.__r = r }); 'started'") and poll with short evals. page_url_contains picks a tab by URL fragment (default: the most recently active page). Works only for browsers started by launch_app/start-display.sh (CDP port 9222+N); fails (isError) with the fix otherwise, or when the tab, URL or script is bad. The page state you see in screenshots is this same tab.

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": "browser"
  }
}

Input Schema

NameRequiredDescriptionDefault
jsNo
urlNo
actionNoinfo
instanceNo
max_charsNo
timeout_sNo
page_url_containsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.2
    • changedInput schema / properties / max_chars / default
      Previous value: -20000New value: +0
    • addedInput schema / properties / timeout_s
      Added value: +{
      +  "default": 30,
      +  "title": "Timeout S",
      +  "type": "number"
      +}
  2. Addedv0.6.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 timeout semantics (call fails with isError/'timed_out', connection stays usable, script keeps running in the page), truncation behavior per action with concrete caps, load-wait of 30s on navigate, and the hard prerequisite that the browser must have been started by launch_app/start-display.sh on CDP port 9222+N. It also explains the viewport coordinate mapping needed to reconcile CSS pixels with click()/screenshot().

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 purpose, then organized as an action-keyed reference block where each entry pairs an action with its return shape and constraints, which makes it easy to scan. It is long, and some return-shape detail duplicates the existing output schema, but nearly every line carries operational information rather than filler.

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 seven-parameter, multi-mode browser control tool with zero schema descriptions, the definition covers prerequisites, per-action limits, error modes, and long-running-work patterns, which is close to what an agent needs to call it safely. The unaddressed 'instance' parameter and the absence of any note that eval executes arbitrary page JavaScript (and can mutate page state) are the remaining gaps.

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 description coverage is 0%, so the description must define all seven parameters, and it defines six well: js, url, action (all four values explained), max_chars (distinct defaults and ceilings for text vs eval), timeout_s (range 1–600, default 30, which actions it bounds), and page_url_contains (fragment matching with the most-recently-active default). The 'instance' parameter is never mentioned anywhere, leaving one gap in an otherwise strong compensation for the empty schema.

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 concrete verb+resource ('Talk to the instance's Chromium-family browser over the Chrome DevTools Protocol') and immediately qualifies the value proposition ('exact navigation and page text without keystrokes or OCR'), which separates it from click/type_text siblings. The four action names (info, navigate, text, eval) are enumerated with their return shapes, so an agent can pick the right mode 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?

Usage context is clear: use this for exact navigation and text extraction instead of keystroke/OCR approaches, and the closing line clarifies the relationship to screenshot ('the page state you see in screenshots is this same tab'). It also gives a concrete pattern for long-running work (store on window, poll with short evals). It stops short of explicit when-not-to-use exclusions or naming siblings like find_elements/parse_screen as alternatives.

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