Skip to main content
Glama

OmniBrowser v2

A small attach-only Chrome/Chromium helper: independent CLI and persistent STDIO MCP, seven commands, no agent loop/broker/recipes or arbitrary eval tool. Python 3.10+; existing runtime dependencies only (Playwright, httpx, markdownify, MCP).

Install and entries

git clone https://github.com/huutrungle2001/OmniBrowser-v2.git OmniBrowser
cd OmniBrowser
python3 -m venv .venv
.venv/bin/python -m pip install -e .
export PATH="$PWD/.venv/bin:$PATH"
export OMNI_CDP_URL=http://127.0.0.1:17082

Chrome must already expose loopback CDP; Omni never launches a browser/profile. Default is port 17082; CLI accepts --cdp-url, MCP reads OMNI_CDP_URL. Playwright 1.64+ attach uses no_defaults=True, leaving download policy, focus and media defaults unchanged. Do not expose CDP to a network.

Root python /absolute/path/OmniBrowser/omni.py, installed omni, and omni-mcp work independently of cwd. --help/--version do not contact Chrome. For Python package imports from the checkout, use PYTHONPATH=src with safe-path mode or run outside the root: the development entry omni.py otherwise shadows the installed package in ordinary python -c/stdin imports.

Related MCP server: Chrome MCP Bridge

Commands

omni --list-tabs
omni --goto https://example.com --new-tab
omni --goto https://example.com --tab TAB_ID
omni --observe --tab TAB_ID
omni --observe --tab TAB_ID --cursor CURSOR_FROM_PREVIOUS_RESULT
omni --act --tab TAB_ID --ref REF --action click
omni --act --tab TAB_ID --ref REF --action fill --value 'text'
omni --act --tab TAB_ID --ref REF --action press --key Enter
omni --act --tab TAB_ID --ref REF --action select --value blue
omni --act --tab TAB_ID --ref REF --action select --label Blue
omni --scroll --tab TAB_ID --direction down --amount 600
omni --screenshot --tab TAB_ID --output /absolute/capture.png
omni --screenshot --tab TAB_ID --output /absolute/full.png --full-page
omni --download --tab TAB_ID --url https://example.com/notes.pdf --output ./notes.pdf

Use real returned tab IDs/refs, not indexes, text matches or guessed selectors. Only explicit goto --new-tab creates a tab; no implicit focus/tab selection. Irrelevant/ambiguous action arguments are rejected before browser interaction. Press is native element input; select is exact value OR label on native HTML select only (custom dropdowns return UNSUPPORTED_ACTION). No force/JS click, JS value assignment, action replay, hidden observe or post-action screenshot.

CLI stdout is one JSON object, optionally --pretty. Errors retain {"ok":false,"error":{"code":"STALE_REF","message":"..."}}. Exit codes: 0 success; 2 invalid/unsupported/limit; 3 connection/missing tab; 4 stale/unavailable target; 5 timeout; 6 file/download/auth; 1 internal. --timeout is milliseconds, default 10000 (download 120000); it is a phase bound, not a hard wall-clock interruption of CDP capture/local parsing. Filled/selected values and native call logs are omitted from errors/results; shell history/arguments can still expose CLI values.

Complete paged observation

Observe joins batch DOM/AX/DOMSnapshot captures using vendored browser-use snapshot/visibility/clickable/paint-order logic, then clean HTML -> markdown. It returns content, absolute links, named controls, coverage, truncated, has_more, and next_cursor. Follow the cursor to continue all three streams until has_more=false/next_cursor=null.

Each full Omni JSON page + newline is bounded to 15360 UTF-8 bytes by default (--max-bytes 2048..65536). Streams are interleaved fairly; positions in coverage.positions are [start,end) offsets for content characters/items. Only the returned page binds refs, at most 96 combined links/controls; candidate discovery is not globally capped at 96. An item that cannot fit by itself raises OUTPUT_BUDGET; names, URLs and refs are not clipped to fit.

Cursors are signed with a document-local key and a keyed fingerprint of cleaned extraction and exact node identities. They expose offsets, not raw content, credentials or editable values. Each call captures afresh; no disk registry or observation daemon. Cursors work between CLI processes and MCP. Malformed, wrong-tab/document, navigation or changed extracted state returns STALE_CURSOR and requires a fresh observe without cursor. Title-only/irrelevant chrome text outside the extracted main content is not itself a reason to invalidate.

truncated and *_omitted describe the CURRENT response, so they may remain true/nonzero on the final page because earlier pages held other items. has_more=false only ends recoverable pagination, not all site coverage. Unrecoverable limits remain explicit: 50000 processed DOM nodes, 3000 paint-filter nodes, 1000000 HTML characters before markdown, overlong name fallbacks omitted, and unsupported iframe/closed-shadow content. Check processing_limited, paint_filter_limited, extraction_content_truncated, omission counts and unsupported counts.

Refs resolve from exact backend node objects into a document-local Map; no Nth element rebinding. They work across CLI/MCP, with at most 512 retained refs. Navigation/BFCache, detachment/reattachment, identity changes (e.g. href), another tab or eviction rejects a ref. On stale refs, observe/select again. Main document/open Shadow DOM only; no raw DOM/AX, editable values, hidden fields, cookies or browser credentials are serialized. Visible page text/URLs are not a general secret-redaction service.

Screenshot, scroll and downloads

Screenshot is viewport PNG by default. Full-page uses bounded CDP capture beyond the viewport, without tab activation, viewport resize or hidden scrolling. Output is CSS-resolution PNG, limited to 6000000 pixels, 8192px per side and 4 MiB encoded-image bytes. Oversized capture returns SCREENSHOT_LIMIT. CLI requires output; MCP returns actual standard ImageContent plus JSON metadata, with optional explicit output file. Existing files/missing parents require --overwrite/--mkdir; publication is atomic and failures leave no partial PNG. Screenshots can reveal visible secrets; use only authorized pages.

Scroll sends one native wheel input to a hit-tested main-document location with no inner scroller in its ancestry. Direction is up/down; amount is 1..10000 CSS pixels, default 75% viewport height capped at 800 (minimum 100). It returns before/after positions, movement, document/viewport sizes and at_current_bottom. This is not a claim that lazy loading is finished or an infinite list is complete. No inner-pane/iframe scrolling, focus switching, implicit observe or repeated auto-scroll.

HTTP downloads preserve the existing scoped in-memory cookie jar, redirects, streaming/byte cap (512 MiB default), HTML/PDF checks and atomic no-clobber output. No browser Save dialog or download-policy changes. POST/blob, partitioned-cookie auth, browser-only tokens, client certificates and challenges have no fallback.

MCP, skill and source layout

Exactly seven tools: list_tabs, goto, observe, act, download, screenshot, scroll. MCP uses snake_case arguments (tab_id, full_page, max_bytes, cursor, etc.). For example: act(tab_id, ref, action="press", key="Enter"); observe(tab_id, cursor=next_cursor); screenshot(tab_id). Results/errors share CLI objects in text + structuredContent; screenshot adds a real PNG ImageContent. Observe's byte budget excludes MCP protocol/duplicate representation overhead.

Add an MCP registration to ~/.codex/config.toml, replacing the example paths with your checkout's absolute paths:

[mcp_servers.omni]
command = "/absolute/path/OmniBrowser/.venv/bin/python"
args = ["/absolute/path/OmniBrowser/omni_mcp.py"]
tool_timeout_sec = 180
[mcp_servers.omni.env]
OMNI_CDP_URL = "http://127.0.0.1:17082"

One dedicated thread owns sync Playwright, attaches lazily and serializes MCP calls. CLI is independent with per-call connections. Broken transport is dropped for a later call; no replay. Shutdown disconnects, not Chrome/user tabs. Other clients need agent coordination. Already-running clients may need MCP reconnect/new session for changed schemas; no other agent/session was restarted. Install the bundled skill by linking skills/omnibrowser into ~/.codex/skills/omnibrowser. See skills/omnibrowser/SKILL.md. The product name is OmniBrowser; CLI omni and MCP registration omni remain unchanged.

Each top-level operation is implemented once in src/omni/commands/*.py. Entries stay tiny; CLI/MCP share validation and dispatch. reader.py, pagination.py, refs.js, tabs.py and cdp.py are bounded shared helpers. Tiny old-module compatibility imports remain. Vendor MIT/provenance is in src/omni/_vendor/browser_use_dom/UPSTREAM.md.

Verification

This revision was exercised directly through actual CLI/MCP on a harmless temporary local demo in a newly-created tab of existing Chrome. No pytest, automated suite, mocks, benchmark or new fixture project was added/run; existing tests remain unchanged. No Moodle/account/agent-fetch tab was used. Existing fixture-based checks are included under tests/; local handoff notes and screenshots are not published.

Available Tools

7 tools
actB

Native click/fill/press/select on an exact observed ref. No replay or hidden observe. select is native HTML only.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyNo
refYes
labelNo
valueNo
actionYes
tab_idYesExact stable tab_id; no implicit tab selection.
timeoutNoPhase timeout in milliseconds (10000; download 120000).

TDQS

B3.1/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It discloses several useful traits: native interaction, no replay or hidden observe, and that select is native HTML only. It still omits side effects, navigation/submission behavior, and failure modes, so significant gaps remain for a mutation tool.

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?

The description is short, front-loaded, and every sentence contributes: purpose first, then a negative behavioral constraint, then a select-specific rule. It is appropriately terse, though it is arguably under-specified for a tool with a complex oneOf schema.

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

Completeness2/5

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

Given the tool's complexity (7 parameters, a nested oneOf, required fields, no annotations, and no output schema), the description is too thin. It does not explain how to form valid parameter combinations, what the tool returns, what side effects to expect, or when to prefer alternative tools.

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

Parameters2/5

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

Schema description coverage is only 29%, so the description must compensate but mostly does not. It names the action values and constrains ref to an observed ref, yet it never explains the required value/key/label combinations for fill, press, and select, nor the role of tab_id and timeout beyond what little the schema itself provides.

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

Purpose4/5

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

The description states a specific set of actions (click/fill/press/select) on a specific target (an exact observed ref), which is much clearer than a generic verb. It does not name sibling tools or explicitly route the agent away from observe, so it falls short of full sibling differentiation.

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

Usage Guidelines3/5

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

The description implies usage context by requiring an 'exact observed ref' and stating 'No replay or hidden observe,' which tells the agent this tool does not perform observation. However, it does not explicitly say when to use this versus siblings like observe or goto, nor does it list exclusions or prerequisites in a routing-friendly way.

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

downloadB

Cookie-scoped HTTP GET streaming; atomic output, no Save dialog. No POST/blob/challenge fallback.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesAbsolute HTTP(S) URL without embedded credentials.
mkdirNo
outputYesPrefer an absolute output path.
tab_idYesExact stable tab_id; no implicit tab selection.
timeoutNoPhase timeout in milliseconds (10000; download 120000).
max_bytesNo
overwriteNo

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose real behavior: requests are scoped to a tab's cookie jar, output is streamed and written atomically, and no Save dialog appears. It is silent on failure/partial-write behavior, permission or auth requirements, and concurrency, which matters for a mutating filesystem operation.

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?

Two tight clauses with zero filler and the key constraints front-loaded. The telegraphic, semi-sentence style trades some readability for density, but every phrase carries load.

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

Completeness3/5

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

For a 7-parameter write-to-disk tool with no annotations and no output schema, the description covers the core semantics and the hard limitations but omits error behavior, overwrite/directory-creation consequences, and size-limit behavior. Adequate but with visible gaps.

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 57%, with mkdir, max_bytes, and overwrite carrying no description anywhere. The description's "cookie-scoped" and "no implicit tab selection" framing adds meaning to tab_id and url beyond the schema, but it says nothing about the undocumented three parameters, so it only partially compensates for the gap.

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

Purpose4/5

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

The description names a concrete mechanism (cookie-scoped HTTP GET streaming to an atomic file write), which is clearly distinct from browser-rendering siblings like goto or screenshot. It never explicitly contrasts itself with those siblings, so an agent has to infer that this is the file-retrieval path rather than rendering, but the purpose itself is specific and non-tautological.

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

Usage Guidelines3/5

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

"No POST/blob/challenge fallback" gives explicit negative conditions (don't use for POST endpoints, blob URLs, or challenge-protected resources), which is genuinely useful routing information. However, it names no positive trigger and no alternative tool to use for the excluded cases, so the when-to-use guidance is only half complete.

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

gotoA

Navigate an explicit tab or create one only with new_tab=true. No hidden observe.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesAbsolute HTTP(S) URL without embedded credentials.
tab_idNoExact stable tab_id; no implicit tab selection.
new_tabNo
timeoutNoPhase timeout in milliseconds (10000; download 120000).

TDQS

A3.5/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. 'No hidden observe' is a genuine behavioral disclosure (navigation does not implicitly observe), but it omits what navigation actually does, whether it waits for load, and what state results. Partial disclosure only.

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?

Two short sentences, zero filler, and the core constraint is front-loaded. Every clause carries weight.

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

Completeness3/5

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

For a navigation/mutation tool with no annotations and no output schema, the description leaves gaps: no mention of what happens to the current tab state, waiting/timeout behavior, or whether content is returned. Adequate but thin given the tool's complexity.

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 coverage is 75%, with url, tab_id, and timeout already documented. The description reinforces the new_tab semantics ('create one only with new_tab=true'), which the schema encodes only structurally via oneOf, but adds little beyond the schema's own constraint language.

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

Purpose4/5

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

States a specific verb (navigate) and resource (a tab), plus the create path conditioned on new_tab=true. It partially differentiates from the observe sibling via 'No hidden observe', though the phrasing is terse and assumes familiarity with the observe/act/goto trio.

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

Usage Guidelines3/5

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

The clause 'create one only with new_tab=true' implies when the create path applies, and 'No hidden observe' hints at a contrast with observe. However, no explicit when-to-use vs alternatives (observe, act, list_tabs) is given, leaving selection to inference.

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

list_tabsB

List stable page-target IDs, titles and URLs without selecting/focusing a tab.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNoPhase timeout in milliseconds (10000; download 120000).

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose one meaningful trait: listing does not select or focus a tab, i.e. it is side-effect free. However, it says nothing about ordering, scope (current window vs all windows), or whether the list can change between calls, leaving behavioral gaps for a no-annotation tool.

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?

A single front-loaded sentence that states the action, the returned data, and the key non-side-effect guarantee with zero filler. Every clause earns its place.

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 simple enumeration tool with no output schema, the description covers the essentials: what is returned and that focus is unchanged. It is slightly short on return ordering and scope (which tabs are included), which an agent might want before relying on the IDs.

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?

Only one optional parameter exists and schema description coverage is 100%, so the timeout semantics (phase timeout, download 120000) are already fully documented in the schema. The description adds no parameter meaning beyond that, making the baseline 3 appropriate.

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

Purpose4/5

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

The description gives a specific verb ('List') and resource ('tabs') and names the returned fields (stable page-target IDs, titles, URLs), so the agent knows exactly what it produces. It implicitly separates itself from a focus/select action, but never names a sibling such as observe or goto, so differentiation is contextual rather than explicit.

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

Usage Guidelines2/5

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

There is no statement of when to use this tool versus observe, goto, or act, and no prerequisites or exclusions are given. The only hint is the behavioral contrast ('without selecting/focusing a tab'), which implies the use case but never instructs the agent.

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

observeC

Clean content, links and controls with exact refs; continue all streams using next_cursor. No field values.

ParametersJSON Schema
NameRequiredDescriptionDefault
cursorNo
tab_idYesExact stable tab_id; no implicit tab selection.
timeoutNoPhase timeout in milliseconds (10000; download 120000).
max_bytesNo

TDQS

C2.4/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It discloses one genuinely useful trait, 'No field values' (i.e. form values are excluded from output), plus cursor continuation, but says nothing about read-only semantics, side effects, error behavior, or output shape. Two facts do not cover a full behavioral profile.

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?

It is short and front-loads the return contents before the pagination hint, with no filler sentences. However, the compressed semicolon phrasing is ambiguous rather than efficient, and brevity here comes at the cost of specification.

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

Completeness2/5

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

With no output schema and no annotations, the description must explain what comes back; it only partially does so ('content, links and controls with exact refs', 'No field values') and omits pagination mechanics, cursor semantics, and the meaning of timeout/max_bytes. Inadequate for a 4-parameter browser tool.

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

Parameters2/5

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

Schema description coverage is only 50% (cursor and max_bytes are undocumented). Worse, the description refers to 'next_cursor' while the actual parameter is named 'cursor', which could mislead an agent, and it explains nothing about max_bytes or cursor format/size limits.

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

Purpose3/5

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

The description names the resources returned (content, links, controls) and the ref mechanism, so an agent can infer this reads page structure. But it opens with a noun phrase rather than a verb+resource statement, and it never distinguishes itself from siblings like screenshot or act. Purpose is inferable but vague.

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

Usage Guidelines2/5

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

There is no explicit when-to-use guidance and no named alternative among list_tabs, goto, act, download, screenshot, or scroll. The only usage hint is 'continue all streams using next_cursor', which implies pagination continuation but leaves the primary selection condition unstated.

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

screenshotB

Return actual PNG ImageContent and metadata; optional safe output file. No focus/resize/scroll. Max 6M pixels, 8192px/side, 4 MiB.

ParametersJSON Schema
NameRequiredDescriptionDefault
mkdirNo
outputNoPrefer an absolute output path.
tab_idYesExact stable tab_id; no implicit tab selection.
timeoutNoPhase timeout in milliseconds (10000; download 120000).
full_pageNo
overwriteNo

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden and does disclose output type (PNG ImageContent + metadata), the optional output file, and hard limits (6M pixels, 8192px/side, 4 MiB). It omits permission/auth requirements, whether the write of an output file is reversible, and pagination/streaming behavior, so disclosure is partial.

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?

Two dense sentences, front-loaded with the output artifact before the scope exclusion and limits. Every clause carries information, though the telegraphic phrasing is borderline cryptic rather than genuinely concise-and-clear.

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

Completeness3/5

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

For a 6-param, no-annotation, no-output-schema tool, the description covers the return artifact and size limits but leaves the three undocumented boolean params and permission/behavioral context unexplained. It is adequate but has clear gaps for correct invocation.

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 coverage is 50% and three params (mkdir, full_page, overwrite) have no schema descriptions. "Optional safe output file" loosely gestures at output/mkdir/overwrite, but full_page and overwrite behavior are never explained, so the description only marginally compensates.

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

Purpose4/5

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

The description states a concrete verb+resource ("Return actual PNG ImageContent and metadata") and scopes itself with "No focus/resize/scroll," which implicitly separates it from act/scroll siblings. It is clear what the tool produces, though it never names a sibling tool explicitly.

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

Usage Guidelines3/5

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

"No focus/resize/scroll" gives a when-not-to-use boundary, implying those interactions live in other tools. However, it does not say when to prefer screenshot over observe or how it relates to goto/list_tabs, leaving usage mostly implied.

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

scrollC

One main-document native wheel input. CSS pixels; reports before/after movement, not lazy-load completeness. Inner panes unsupported.

ParametersJSON Schema
NameRequiredDescriptionDefault
amountNo
tab_idYesExact stable tab_id; no implicit tab selection.
timeoutNoPhase timeout in milliseconds (10000; download 120000).
directionYes

TDQS

C2.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does add real behavioral context: units are CSS pixels, it reports before/after movement, it does not guarantee lazy-load completeness, and it only works on the main document. However, it omits whether the call blocks, how the movement report is shaped, and any timeout/permission implications.

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?

Three terse clauses with no filler, and the primary scope constraint (main-document) leads. The telegraphic style is efficient but borders on under-specified fragments.

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

Completeness3/5

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

For a 4-param tool with no annotations and no output schema, the description covers scope, units, and rough return semantics, which is decent. It still leaves the shape of the 'before/after movement' report and timeout behavior unaddressed, so it is adequate but not complete.

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 coverage is 50%, with tab_id and timeout documented in-schema while amount and direction are bare. The description's 'CSS pixels' clause usefully clarifies the unit for the amount parameter, but it adds nothing for direction and leaves amount's range/semantics largely to the schema.

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

Purpose3/5

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

The description conveys that this performs a wheel/scroll input on the main document, but the phrasing 'One main-document native wheel input' is cryptic and never states a clean verb+resource like 'scroll the page'. It does implicitly separate itself from inner-pane scrolling, giving partial sibling differentiation against act/observe/screenshot.

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

Usage Guidelines2/5

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

There is no explicit when-to-use guidance and no mention of alternatives such as act or observe for interacting with the page. The 'Inner panes unsupported' clause implies a scope exclusion but is not framed as usage guidance.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv2.0.0
    • First observedact
    • First observeddownload
    • First observedgoto
    • First observedlist_tabs
    • First observedobserve
    • First observedscreenshot
    • First observedscroll

TDQS

B3.4/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct browser primitive: list_tabs (enumerate), goto (navigate), observe (read state), act (mutate state), download (fetch file), screenshot (capture image), scroll (viewport movement). The descriptions explicitly delimit boundaries (e.g. observe returns refs but no field values, act works only on observed refs), leaving no real overlap. observe vs screenshot are the closest pair but are clearly separated as DOM-content vs PNG image.

Naming Consistency4/5

Six of seven names are clean single-verb actions (goto, observe, act, download, screenshot, scroll), giving a predictable action-oriented convention. list_tabs is the lone verb_noun outlier, a minor deviation rather than a different style. Overall readable and consistent.

Tool Count5/5

Seven tools is well-scoped for a browser automation server, covering the essential perceive/act/navigate/capture primitives. Each tool earns its place with no redundant or filler entries. Falls squarely in the ideal 3-15 range.

Completeness4/5

Core browser lifecycle is covered: tab enumeration, navigation, observation, interaction, scrolling, screenshots, and downloads. Minor gaps exist, such as no explicit tab-close or history back/forward operation and no dedicated wait-for-load primitive, but agents can work around these via goto and repeated observe. The surface is solid for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to control the Google Chrome browser through a Node.js WebSocket bridge and a dedicated browser extension. It provides tools for capturing screenshots, executing JavaScript, managing tabs, and extracting page content via the MCP protocol.
    2
    -
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to control and interact with a Chrome browser via MCP, providing tools for navigation, screenshots, clicking, form filling, content extraction, and tab management.
    -
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables local opencode agents to control a live Chrome browser via MCP tools, including tab management, JavaScript execution, clicking, form filling, page reading, screenshots, and console log retrieval.
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to control, read, and verify a live Chrome browser through 46 schema-validated MCP tools, including DOM pruning, coordinate-aware interaction, and trusted CDP input events.
    77 npm
    36
    AGPL 3.0