Skip to main content
Glama
pm990320

ultimate-playwright-mcp

by pm990320

Ultimate Playwright MCP

npm version npm downloads license CI

Multi-agent Playwright MCP server with tab isolation via targetId. Allows multiple Claude instances (or other MCP clients) to share a single Chrome browser while maintaining isolated tab groups.

Why Ultimate Playwright?

The official @playwright/mcp gives you browser control for a single agent. But what if you have multiple agents sharing one browser?

Ultimate Playwright MCP solves this with tab group isolation:

  • šŸ”€ Multi-agent tab groups — Each agent creates a groupId and only sees its own tabs

  • šŸŖ Shared cookies & sessions — All agents share the same BrowserContext (log in once, everyone's authenticated)

  • šŸŽØ Visual Chrome tab groups — Companion extension organizes tabs into color-coded Chrome tab groups

  • šŸ’¾ Persistent registry — Tab groups survive MCP server restarts (~/.ultimate-playwright-mcp/tab-groups.json)

  • šŸ”Œ Connect to existing Chrome — Uses CDP to attach to your running Chrome (keeps your profile, extensions, bookmarks)

Comparison

Feature

ultimate-playwright-mcp

@playwright/mcp

browser-use-mcp

Multi-agent tab isolation

āœ… Tab groups with groupId

āŒ Single session

āŒ Single session

Shared cookies across agents

āœ… Same BrowserContext

N/A

N/A

Connect to existing Chrome

āœ… CDP

āŒ Launches new browser

āŒ Launches new browser

Visual tab groups in Chrome

āœ… Extension

āŒ

āŒ

Persistent tab registry

āœ… Survives restarts

āŒ

āŒ

Accessibility tree snapshots

āœ… Element refs (e1, e2…)

āœ…

āŒ Screenshot-based

Open source

āœ… MIT

āœ… Apache-2.0

āœ… MIT

Related MCP server: playwright-mcp-orchestrator

Features

  • āœ… Tab Isolation - Each agent gets its own tabs via unique targetId

  • āœ… Shared Cookies - All agents share the same BrowserContext (cookies, sessions, localStorage)

  • āœ… Parallel Execution - Multiple agents can operate simultaneously without interference

  • āœ… CDP Connection - Connects to existing Chrome via Chrome DevTools Protocol

  • āœ… Native Page Checkpoints - Capture structured artifacts and generate reports per targetId

  • āœ… Battle-Tested - Extracted from OpenClaw (MIT licensed)

Installation

npm install -g ultimate-playwright-mcp

Or run directly with npx:

npx ultimate-playwright-mcp --cdp-endpoint http://localhost:9222

Quick Start

1. Launch Chrome with Remote Debugging

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir=C:\\temp\\chrome-debug

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ultimate-playwright": {
      "command": "npx",
      "args": [
        "ultimate-playwright-mcp",
        "--cdp-endpoint",
        "http://localhost:9222"
      ]
    }
  }
}

3. Restart Claude Desktop

Claude will now have access to browser control tools with tab isolation.

Usage Example

User: Open two tabs and navigate them independently

Claude: I'll create two tabs with separate targetIds:

1. browser_tabs({ action: "new" })
   → **targetId: ABC123...**

2. browser_tabs({ action: "new" })
   → **targetId: XYZ789...**

3. browser_navigate({ targetId: "ABC123...", url: "https://github.com" })
4. browser_navigate({ targetId: "XYZ789...", url: "https://google.com" })

Both tabs are now navigated independently!

Available Tools

Tool

Description

Key Parameters

browser_tab_group

Create/list/delete tab groups for isolation

action, name, color, groupId

browser_tabs

List, create, close, or select tabs

action, groupId, targetId, index

browser_navigate

Navigate to a URL

url, targetId

browser_snapshot

Capture accessibility tree with refs

targetId

browser_click

Click an element

ref, targetId

browser_type

Type text into an element

ref, text, targetId

browser_hover

Hover over an element

ref, targetId

browser_press_key

Press a keyboard key

key, targetId

browser_fill_form

Fill multiple form fields

fields, targetId

browser_wait_for

Wait for conditions

text, selector, url, loadState, targetId

browser_checkpoint

Capture a structured checkpoint for a tab

name, targetId, collectors

browser_checkpoint_report

Generate reports from stored checkpoints

format, resultsDir

Checkpoints

Use browser_checkpoint when you want a persisted capture of the current page for later review or report generation.

  • Checkpoints are scoped to the resolved targetId, so they work with this server's tab isolation model.

  • Artifacts and manifests are written under ~/.ultimate-playwright-mcp/checkpoints by default.

  • Generated reports are written under ~/.ultimate-playwright-mcp/checkpoints/report.

Example:

1. browser_checkpoint({ targetId: "ABC123", name: "after-login" })
2. browser_checkpoint_report({ format: "html" })

Tab Groups (Multi-User Isolation)

When multiple users or agents share one browser instance, tab groups keep everyone's tabs isolated. Each session creates its own group, and all tab operations are scoped to that group.

User: Research product pricing

Claude: I'll create a tab group first, then open tabs within it.

1. browser_tab_group({ action: "create", name: "pricing-research", color: "blue" })
   → **groupId: g_a1b2c3d4e5f6**

2. browser_tabs({ action: "new", groupId: "g_a1b2c3d4e5f6", url: "https://example.com/pricing" })
   → **targetId: ABC123...**

3. browser_tabs({ action: "list", groupId: "g_a1b2c3d4e5f6" })
   → Only shows tabs in this group (not other users' tabs)

Meanwhile, another user on the same server:

1. browser_tab_group({ action: "create", name: "docs-review", color: "green" })
   → **groupId: g_x9y8z7w6v5u4**

2. browser_tabs({ action: "new", groupId: "g_x9y8z7w6v5u4", url: "https://docs.example.com" })
   → **targetId: XYZ789...**

Both users share the same cookies/sessions but only see their own tabs!

Tab Group Lifecycle

  1. Create a group at the start of your session

  2. Open tabs within the group using groupId

  3. Work with tabs using targetId as before

  4. Delete the group when done (optionally closes all tabs)

Group state is persisted to ~/.ultimate-playwright-mcp/tab-groups.json so it survives MCP server restarts.

Architecture

ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│        Single Chrome Process                │
│    (--remote-debugging-port=9222)           │
│  ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”   │
│  │     Single BrowserContext            │   │
│  │  (shared cookies, storage)           │   │
│  │                                      │   │
│  │  Group: alice (blue)                 │   │
│  │  ā”Œā”€ā”€ā”€ā”€ā”€ā” ā”Œā”€ā”€ā”€ā”€ā”€ā”                    │   │
│  │  │ Tab │ │ Tab │                    │   │
│  │  │  A  │ │  B  │                    │   │
│  │  ā””ā”€ā”€ā”€ā”€ā”€ā”˜ ā””ā”€ā”€ā”€ā”€ā”€ā”˜                    │   │
│  │                                      │   │
│  │  Group: bob (green)                  │   │
│  │  ā”Œā”€ā”€ā”€ā”€ā”€ā” ā”Œā”€ā”€ā”€ā”€ā”€ā” ā”Œā”€ā”€ā”€ā”€ā”€ā”            │   │
│  │  │ Tab │ │ Tab │ │ Tab │            │   │
│  │  │  C  │ │  D  │ │  E  │            │   │
│  │  ā””ā”€ā”€ā”€ā”€ā”€ā”˜ ā””ā”€ā”€ā”€ā”€ā”€ā”˜ ā””ā”€ā”€ā”€ā”€ā”€ā”˜            │   │
│  ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜   │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
                   ↑
           CDP Connection
                   ↓
ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│    ultimate-playwright-mcp (MCP Server)     │
│    - Tab routing via targetId               │
│    - Tab groups via groupId                 │
│    - Shared ownership registry (JSON file)  │
│    - Stdio transport                        │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
         ↓           ↓           ↓
   ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā” ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā” ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
   │ Alice   │ │  Bob    │ │ Charlie │
   │ (Claude)│ │ (Claude)│ │ (Cursor)│
   ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜ ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜ ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜

MCP Configuration

Cursor / Windsurf / Generic MCP Client

{
  "mcpServers": {
    "ultimate-playwright": {
      "command": "npx",
      "args": ["ultimate-playwright-mcp", "--cdp-endpoint", "http://localhost:9222"]
    }
  }
}

With Environment Variable

{
  "mcpServers": {
    "ultimate-playwright": {
      "command": "npx",
      "args": ["ultimate-playwright-mcp"],
      "env": {
        "CDP_ENDPOINT": "http://localhost:9222"
      }
    }
  }
}

CLI Options

ultimate-playwright-mcp [options]

Options:
  --cdp-endpoint <url>  CDP endpoint URL (e.g., http://localhost:9222)
                        Can also use CDP_ENDPOINT env var.
                        If omitted, daemon-managed Chrome is started lazily on first tool call.
  --agent-id <id>       Optional agent ID for logging/debugging
                        Can also use AGENT_ID env var
  --keep-alive          Auto-restart daemon-managed Chrome if it exits
                        Use --no-keep-alive for testing workflows where you want Chrome to stay down after kill
                        Default: disabled (no auto-restart)
                        Can also use KEEP_ALIVE env var (set to "false" to disable)
  --checkpoint-output-dir <path>
                        Root directory for checkpoint manifests, artifacts, and reports
                        Can also use CHECKPOINT_OUTPUT_DIR env var
  -V, --version         Output version number
  -h, --help            Display help

Multi-Agent Setup

Running Multiple Claude Code Instances

Each instance connects to the same MCP server and gets isolated tabs:

Terminal 1:

claude-code --mcp-config ./mcp-config.json
# Agent A creates tabs with targetIds starting from ABC...

Terminal 2:

claude-code --mcp-config ./mcp-config.json
# Agent B creates tabs with targetIds starting from XYZ...

Both agents share cookies and sessions but operate on different tabs!

Persistent Chrome Setup (macOS)

For a Chrome instance that auto-starts with debug port:

Create ~/Library/LaunchAgents/com.user.chrome-debug.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.chrome-debug</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</string>
        <string>--remote-debugging-port=9222</string>
        <string>--user-data-dir=/Users/YOUR_USERNAME/chrome-debug-profile</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load with:

launchctl load ~/Library/LaunchAgents/com.user.chrome-debug.plist

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run type-check

# Lint
npm run lint

# Watch mode
npm run watch

License

MIT

Attribution

This project extracts browser control code from OpenClaw (MIT licensed), which provides battle-tested tab isolation and Playwright integration.

Key extracted components:

  • CDP session management (pw-session.ts)

  • Browser operations (pw-tools-*.ts)

  • Role-based element refs (pw-role-snapshot.ts)

Available Tools

14 tools
browser_checkpointC

Capture a structured checkpoint for the current page or a specific tab. Stores checkpoint artifacts and a manifest under the server-managed checkpoint directory.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesUnique checkpoint name for this capture.
targetIdNoTarget ID of the tab. If omitted, uses the first available tab.
descriptionNoLong-form description of what the checkpoint captures.
highlightSelectorNoCSS selector to highlight in the screenshot artifact.
fullPageNoCapture a full-page screenshot when the screenshot collector runs.
collectorsNoPer-collector overrides. Set a collector to false to disable it or provide an options object.

TDQS

C2.9/5.0
Behavior2/5

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

Without annotations, the description should disclose behavioral traits like side effects, authorization needs, or whether page state is modified. It only mentions that artifacts are stored under a server-managed directory, leaving important behaviors (e.g., does it pause the page? Is it safe?) unspecified.

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 concise with two sentences, front-loaded with the main action. It avoids unnecessary words, though it could benefit from additional context without compromising conciseness.

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 6 parameters including nested objects and no output schema, the description lacks completeness. It does not explain what artifacts a checkpoint includes, how collectors work, or how this tool differs from similar tools like browser_snapshot.

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 baseline is 3. The description adds minimal parameter meaning beyond the schema; it does not elaborate on the parameters like 'collectors' or 'fullPage'.

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 clearly states the tool captures a structured checkpoint for a page or tab and stores artifacts. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like browser_snapshot or browser_checkpoint_report, though the name and context help.

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?

The description provides no guidance on when to use this tool versus alternatives such as browser_snapshot or browser_checkpoint_report. No context about prerequisites, use cases, or when not to use it.

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

browser_checkpoint_reportA

Generate an HTML, Markdown, or MDX report from stored MCP checkpoint manifests.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoSingle report format to generate. Defaults to html.
resultsDirNoOptional directory containing checkpoint manifests. Defaults to the server-managed checkpoint results directory.

TDQS

A3.5/5.0
Behavior2/5

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

No annotations exist, so the description must carry behavioral transparency. It only says 'generate a report' with no details on whether the operation is read-only, what it modifies, or any side effects. This leaves the agent underinformed.

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?

The description is a single, well-structured sentence that front-loads the core action (generate report) and lists supported formats. No wasted words.

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?

Given low complexity (2 optional params, no output schema), the description is minimally viable but incomplete. It fails to describe what the report contains, leaving agents guessing about output structure and content.

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 baseline is 3. The description adds no extra meaning beyond the schema; it doesn't explain the implications of each format or the purpose of resultsDir.

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 description clearly states it generates a report (HTML, Markdown, or MDX) from checkpoint manifests, with a specific verb and resource. It distinguishes from sibling tools, which are all about browser interactions, not report generation.

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 use when a report from checkpoint manifests is needed, but provides no explicit guidance on when to use this tool vs alternatives, nor any exclusions or prerequisites.

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

browser_clickB

Click an element by its ref (e1, e2, etc. from snapshot)

ParametersJSON Schema
NameRequiredDescriptionDefault
refYesElement reference from snapshot (e.g., 'e1', 'e2')
targetIdNoTarget ID of the tab
buttonNoMouse button to click (default: left)
doubleClickNoPerform a double-click

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral transparency, but it only states the basic action. It does not disclose side effects (e.g., navigation, waiting for page load), error handling, or whether the click is immediate or asynchronous. This is a minimal disclosure.

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 a single concise sentence that efficiently communicates the core purpose. It could be slightly improved by front-loading the action, but overall it is well-structured and not verbose.

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?

Given the simplicity of the tool (no output schema, few parameters), the description is minimally adequate but lacks context about what happens after a click (e.g., if it waits for a page load or returns anything). For a basic click tool, this is acceptable but not thorough.

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 baseline is 3. The description does not add extra meaning beyond the schema; it only mentions 'ref' while ignoring targetId, button, and doubleClick, but the schema already covers these adequately.

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 description clearly states the action (click), the target (element by ref), and the source of refs (from snapshot). It distinguishes this tool from siblings like browser_hover (hover) and browser_type (type text) by specifying the exact action.

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 provides no guidance on when to use this tool versus alternatives (e.g., browser_hover or browser_press_key). It does not mention prerequisites like needing a snapshot first, nor does it specify when a click is appropriate.

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

browser_evaluateA

Execute JavaScript in the page context via Playwright's page.evaluate(). Use for interacting with elements not in the accessibility snapshot (portal divs, framework overlays, shadow DOM). Can run arbitrary JS — click hidden elements, extract data, manipulate the DOM. Optionally scope to a specific element via ref.

ParametersJSON Schema
NameRequiredDescriptionDefault
expressionYesJavaScript expression or function body to evaluate in the browser. Can be a simple expression like `document.title` or a function like `() => document.querySelector('.menu').click()`. If ref is provided, receives the element as first argument: `(el) => el.textContent`.
refNoOptional element reference from snapshot (e.g., 'e1'). If provided, the expression receives the DOM element as its first argument.
targetIdNoTarget ID of the tab

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It discloses that it can run arbitrary JS, click hidden elements, extract data, and manipulate the DOM. It does not cover async behavior, error handling, or return value, but covers key behavioral traits.

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?

Three sentences each add value: first states core action, second gives use case, third adds optional scoping. No wasted words.

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?

The description explains when and how to use the tool, but does not mention the return behavior (the expression's result is returned). Given no output schema, this is a minor gap.

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

Parameters5/5

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

The schema has 100% coverage, but the description adds significant value beyond schema by explaining that expression can be a function body and that ref passes the element as argument, with examples.

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 description clearly states the verb 'Execute JavaScript' and the resource 'in the page context'. It distinguishes from sibling tools by specifying it is for interacting with elements not in accessibility snapshots, such as portal divs and shadow DOM.

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?

The description explicitly says to use this tool for elements not in the accessibility snapshot, providing clear context. However, it does not mention when not to use it or suggest alternative tools like browser_click.

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

browser_fill_formA

Fill multiple form fields at once

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsYesArray of form fields to fill
targetIdNoTarget ID of the tab

TDQS

A3.6/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 full behavioral disclosure burden. It fails to mention any behavioral traits such as error handling, field visibility requirements, or side effects. This is a significant gap 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.

Conciseness5/5

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

The description is a single efficient sentence with no fluff. It front-loads the purpose ('Fill multiple form fields at once') and every word adds value.

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?

The tool has no output schema, so the description should explain return values or effects. It does not mention success/failure indicators or prerequisites. Given the complexity of form filling and multiple sibling tools, the description is incomplete.

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 100%, and the description adds no additional meaning beyond what the input schema already provides for parameters. The baseline of 3 is appropriate as the schema describes the parameters adequately.

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 description 'Fill multiple form fields at once' clearly states the action (fill), resource (form fields), and scope (multiple at once). It effectively distinguishes from sibling tools like browser_type (single field) and browser_click (clicking).

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?

The phrase 'at once' implies batch efficiency, providing clear context for when to use this tool. However, it lacks explicit when-not-to-use guidance or alternative mentions. This is acceptable as the context is clear.

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

browser_hoverC

Hover over an element

ParametersJSON Schema
NameRequiredDescriptionDefault
refYesElement reference from snapshot
targetIdNoTarget ID of the tab

TDQS

C2.9/5.0
Behavior2/5

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

The description does not disclose behavioral details such as whether hovering triggers JavaScript events, if the element must be visible, or if there are side effects. Since no annotations are provided, the description carries full burden but provides minimal insight.

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 description is extremely concise at one sentence, but it lacks structure or front-loading of key details. While it is not verbose, it is also not particularly well-organized for quick comprehension.

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?

Given the tool's simplicity (hover action with 2 parameters), the description is adequate but not complete. It does not mention prerequisites like a visible element or behavior on failure, which are important for a browser automation tool.

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?

Both parameters have descriptions in the schema, achieving 100% coverage. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is 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 'Hover over an element' clearly states the action (hover) and the target (element), making the tool's purpose unambiguous. It does not explicitly differentiate from siblings like browser_click, but the verb 'hover' is distinct enough.

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?

No guidance is provided on when to use this tool (e.g., to trigger hover effects before clicking) or when not to use it. Alternatives like browser_click are not mentioned, leaving the agent without context for tool selection.

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

browser_navigateA

Navigate to a URL in a specific tab. Use targetId from browser_tabs to specify which tab.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL to navigate to
targetIdNoTarget ID of the tab (from browser_tabs). If not provided, uses first available tab.

TDQS

A3.9/5.0
Behavior2/5

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

No annotations are provided, so the description bears full burden. It only states 'Navigate to a URL', but does not disclose whether it waits for page load, timeout behavior, error handling for invalid URLs, or if it replaces current page content. Minimal behavioral context.

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 with no wasted words. The first sentence front-loads the core purpose, and the second provides essential usage guidance. Highly efficient and easy to parse.

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?

The tool has no output schema, so the description should cover return values. It does not mention what happens after navigation (e.g., returns page info?). Also lacks preconditions (browser must already have tabs open). Adequate for a simple tool but gaps remain.

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 already describes both parameters. The description adds value by clarifying that targetId is optional and defaults to the first available tab, which is not in the schema description. This enhances the agent's understanding of parameter behavior.

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 description clearly states the action (navigate), the resource (URL in a tab), and distinguishes from sibling tools like browser_click or browser_fill_form. 'Navigate to a URL in a specific tab' is specific and unambiguous.

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?

The description indicates when to use targetId (from browser_tabs) and implies fallback behavior (first available tab). However, it does not explicitly contrast with sibling tools or state when to use navigation vs. other interactions like clicking links.

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

browser_press_keyC

Press a keyboard key

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesKey to press (e.g., 'Enter', 'Escape', 'ArrowDown')
targetIdNoTarget ID of the tab

TDQS

C2.9/5.0
Behavior2/5

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

The description does not disclose any behavioral traits beyond the action. With no annotations provided, the description carries the full burden, but it fails to mention side effects, authentication needs, or whether the press triggers events. For a simulated input tool, more transparency is needed.

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 very concise at one sentence. It is front-loaded with the action. However, it is underspecified; conciseness is high, but it sacrifices necessary detail.

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 parameter count of 2, no output schema, and no annotations, the description is insufficient. It does not explain return values, behavior when targetId is missing, or how it fits with sibling browser tools. More context is required for an AI agent to use it correctly.

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?

The input schema covers both parameters with descriptions, and the tool description aligns with the key parameter. Since schema coverage is 100%, the description adds no extra meaning beyond what is already in the schema. Baseline 3 is 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 'Press a keyboard key' clearly states the verb and resource, and it implicitly distinguishes from sibling tools like browser_click or browser_type. However, it could be more specific about the context (e.g., sending a key event to the page).

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?

No guidance is provided on when to use this tool versus alternatives like browser_type or browser_click. There is no mention of scenarios where pressing a key is appropriate or where it is not.

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

browser_screenshotA

Take a screenshot of the current page or a specific element. By default saves to file and returns the path (saves context window tokens). Use ref to screenshot a specific element (from snapshot refs like e1, e2), or element for a CSS selector. Omit both for a full page screenshot.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetIdNoTarget ID of the tab (from browser_tabs). If not provided, uses first available tab.
refNoElement reference from snapshot (e.g., 'e1', 'e2') to screenshot a specific element.
elementNoCSS selector to screenshot a specific element (alternative to ref).
fullPageNoCapture the full scrollable page instead of just the viewport (default: false). Not compatible with ref/element.
typeNoImage format (default: png). Use jpeg for smaller file sizes.
qualityNoJPEG quality (1-100). Only applies when type is 'jpeg'. Default: 80. Lower values = smaller file size.
maxWidthNoMaximum width in pixels. Image will be scaled down proportionally if wider. Reduces base64 size for large/full-page screenshots.
returnAsNoHow to return the screenshot. 'file' (default) saves to disk and returns the file path — dramatically reduces context window usage. 'base64' returns inline image data (legacy behavior).
savePathNoCustom file path to save the screenshot to (only used when returnAs is 'file'). If not provided, saves to ~/.ultimate-playwright-mcp/screenshots/ with a timestamp filename.

TDQS

A4.4/5.0
Behavior4/5

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

Without annotations, the description effectively discloses key behaviors: saves to file by default to save tokens, supports element-specific or full-page capture, and allows base64 return. It does not mention potential performance impacts or that screenshots are read-only, which is acceptable.

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 sentences with no waste. The first sentence states the purpose, the second provides parameter usage guidance. All necessary information is front-loaded.

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 tool with 9 parameters and no output schema, the description covers core usage patterns and default behavior. It could mention return value details (path vs base64) but the schema already covers that. Adequate for agent decision-making.

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%, but the description adds value by grouping parameters (ref/element as alternatives, fullPage mutually exclusive) and connecting ref to snapshot references. This context is not present in the schema alone.

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 description clearly states the tool takes a screenshot of the current page or a specific element. It distinguishes from sibling tools by detailing methods for element targeting (ref from snapshot, CSS selector) and full page capture.

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?

The description provides clear guidance on when to use each parameter (ref, element, omit for full page) and highlights the default file-saving behavior to reduce context usage. However, it does not explicitly compare to alternatives like browser_snapshot for DOM analysis.

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

browser_snapshotA

Capture accessibility tree snapshot of the current page. Returns element references (e1, e2, etc.) that can be used with other browser tools like click, type, etc.

ParametersJSON Schema
NameRequiredDescriptionDefault
targetIdNoTarget ID of the tab (from browser_tabs). If not provided, uses first available tab.
maxCharsNoMaximum characters in snapshot. Truncates with notice if exceeded. Recommended: 5000-15000 for smaller models, omit for full snapshot.
compactNoRemove unnamed structural elements and empty branches. Reduces snapshot size significantly. Recommended for simpler tasks.
interactiveNoOnly include interactive elements (buttons, links, inputs, etc.). Dramatically reduces snapshot size. Best for form-filling and clicking tasks.
maxDepthNoMaximum tree depth to include (0 = root only). Use 3-5 for focused snapshots of complex pages.

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations, description carries full burden. Explains return format and purpose, but omits performance impact, size limits, or that snapshot is read-only. Lacks details on truncation behavior beyond what schema says.

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 efficient sentences, front-loaded with action. No extraneous words. Every clause serves a purpose.

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?

Schema covers parameters well, but description doesn't explain what accessibility tree is, why use it, or how to choose parameters (compact vs interactive). Lacks guidance on interpretation. 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?

All 5 parameters have detailed schema descriptions (100% coverage). Description adds no new parameter info; it only states output usage. Baseline 3 is appropriate as schema does the work.

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?

Clearly states 'Capture accessibility tree snapshot', verb+resource. Explains output (element references) and how they're used with other tools (click, type). Distinguishes from visual screenshot tools.

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?

Implies usage as prerequisite for interaction tools, but no explicit when-not-to-use or comparison with siblings like browser_screenshot or browser_checkpoint. Lacks explicit guidance for complex vs simple tasks.

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

browser_tab_groupA

Manage tab groups for session isolation. Multiple users/agents sharing one browser MUST create a tab group first, then pass the groupId to browser_tabs and other tools. This ensures each session only sees and controls its own tabs.

Actions:

  • 'create': Create a new tab group. Returns a groupId to use with all other browser tools.

  • 'list': List all tab groups with tab counts.

  • 'delete': Delete a tab group and optionally close its tabs.

⚔ IMPORTANT: Always create a tab group before opening tabs with browser_tabs.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesTab group action to perform
nameNoHuman-readable name for the group (for 'create' action)
colorNoVisual color for the group (for 'create' action)
groupIdNoGroup name (for 'delete' action)
closeTabsNoWhether to close all tabs in the group when deleting (default: true)

TDQS

A4.5/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It describes actions and parameter effects (e.g., delete optionally closes tabs, default true). However, it does not explain error handling, success responses, or potential side effects beyond the described actions.

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?

Very concise, with bullet-pointed actions and a clear, front-loaded important note. No extraneous text; every sentence serves a purpose.

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?

Given the tool's moderate complexity (5 parameters, no output schema), the description fully covers the workflow (create before use), all actions, and key parameter roles. It references sibling tools and provides actionable guidance.

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 100%, so baseline is 3. The description adds context for some parameters (e.g., groupId for delete, name/color for create) but does not significantly enhance the meaning beyond the schema's own descriptions.

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 description clearly states that the tool manages tab groups for session isolation and lists three specific actions (create, list, delete). It distinguishes from sibling tools like browser_tabs by explaining that tab groups must be created first and the groupId passed to other tools.

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?

Explicitly states when to create a tab group: 'Multiple users/agents sharing one browser MUST create a tab group first', and provides an important note: 'Always create a tab group before opening tabs with browser_tabs.' This guides the agent on proper ordering.

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

browser_tabsA

Manage browser tabs. When using tab groups (recommended for multi-user), pass groupId to scope operations to your group's tabs only.

Actions:

  • 'list': Show tabs. With groupId → only your group's tabs. Without → all tabs.

  • 'new': Create a tab. If groupId is provided, the tab is added to that group.

  • 'close': Close a tab by index or targetId.

  • 'select': Focus a tab by index or targetId.

⚔ IMPORTANT: Create a tab group first for multi-user isolation. Ungrouped tabs remain available as a fallback for local manual testing.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesTab action to perform
groupIdNoTab group name to scope this operation to (from browser_tab_group). Recommended for multi-user isolation.
urlNoURL for 'new' action (defaults to about:blank)
indexNoTab index for 'close' or 'select' actions (relative to group if groupId is set)
targetIdNoTarget ID for 'close' or 'select' actions (alternative to index)

TDQS

A4.7/5.0
Behavior4/5

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

No annotations provided, but description details action outcomes: list scopes by group, new adds to group, close/select by index/targetId. Lacks mention of error cases or side effects, but overall good disclosure.

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?

Concise with clear structure: intro, action list with brief explanations, and an important note. No redundant sentences, front-loaded with key information.

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?

Covers all actions and parameters, mentions group isolation. Lacks explicit return format for 'list', but this is minor given the tool's simplicity and schema details.

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

Parameters5/5

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

Schema coverage is 100%, yet description adds significant value: links actions to parameters (url for new, index/targetId for close/select) and explains groupId scoping. Also notes index is relative to group when groupId set.

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 description states 'Manage browser tabs' and lists actions (list, new, close, select) with clear verb-resource pairs. It distinguishes from sibling tools like browser_tab_group by mentioning tab groups.

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?

Explicit guidance: recommends tab groups for multi-user, explains behavior with/without groupId, and advises creating group first for isolation. No explicit 'when not to use', but context makes it clear.

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

browser_typeC

Type text into an element

ParametersJSON Schema
NameRequiredDescriptionDefault
refYesElement reference from snapshot
textYesText to type
targetIdNoTarget ID of the tab
submitNoPress Enter after typing

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only says 'type text into an element' without explaining key behaviors like whether it clears existing text, how submit works, or if it focuses the element first. This is insufficient for safe invocation.

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 description is very short (one sentence) and front-loaded, which is concise. However, it may be too under-specified, sacrificing informativeness for brevity.

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 no output schema and four parameters, the description is incomplete. It fails to explain return value, error handling, or how it interacts with the DOM. Sibling tool context is not leveraged to clarify use cases.

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 100% with each parameter described in the schema. The description adds no additional meaning beyond the schema, so it meets the baseline but provides no extra value.

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 clearly states the verb 'type' and the resource 'text into an element', indicating the tool's purpose. However, it does not distinguish this tool from siblings like browser_fill_form or browser_press_key.

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?

No guidance is provided on when to use this tool versus alternatives such as browser_fill_form or browser_click. The description lacks any context about prerequisites or typical scenarios.

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

browser_wait_forB

Wait for a condition (text, selector, load state, time, etc.)

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoWait for text to appear on page
textGoneNoWait for text to disappear from page
selectorNoWait for CSS selector
urlNoWait for URL to match pattern
loadStateNoWait for load state
timeMsNoWait for specific milliseconds
targetIdNoTarget ID of the tab

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description must fully disclose behavioral traits. It only states the tool waits, but fails to mention important details like blocking behavior, timeout handling, or what happens if the condition is never met. This is insufficient for a wait 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?

The description is a single sentence, concise and front-loaded. Every word earns its place, though it could be slightly more informative without becoming verbose.

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 7 parameters and no output schema or annotations, the description lacks critical behavioral context (e.g., blocking semantics, timeout defaults, return value). It is not complete enough for safe and effective use by an AI agent.

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%, meaning each parameter already has a clear description. The tool description adds no new meaning beyond summarizing the parameter list. Baseline score of 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?

The description clearly states the tool's purpose: waiting for a condition such as text, selector, load state, or time. This verb-resource combination is distinct from sibling tools like browser_click or browser_navigate.

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 when to use the tool (to wait for various conditions), but provides no explicit guidance on when not to use it or how it compares to sibling tools. No alternatives or exclusions are mentioned.

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. 14 tool updatesv0.2.1
    • First observedbrowser_checkpoint
    • First observedbrowser_checkpoint_report
    • First observedbrowser_click
    • First observedbrowser_evaluate
    • First observedbrowser_fill_form
    • First observedbrowser_hover
    • First observedbrowser_navigate
    • First observedbrowser_press_key
    • First observedbrowser_screenshot
    • First observedbrowser_snapshot
    • First observedbrowser_tab_group
    • First observedbrowser_tabs
    • First observedbrowser_type
    • First observedbrowser_wait_for

TDQS

A3.7/5.0

Scored across 14 tools

Disambiguation5/5

Each tool serves a distinct browser automation action (e.g., click, type, navigate, snapshot). Potential overlaps like browser_click vs. browser_hover are clearly differentiated by operation type, and browser_evaluate handles cases outside the snapshot tree.

Naming Consistency5/5

All tools follow a consistent 'browser_verb_noun' pattern using snake_case. For example, browser_click, browser_navigate, browser_tab_group. No mixing of conventions.

Tool Count5/5

With 14 tools, the server covers core browser automation tasks without being bloated. The count feels well-scoped for its purpose.

Completeness4/5

The tool set covers essential browser actions (navigation, interaction, snapshot, screenshots, tabs, checkpoints). Minor gaps exist, such as no explicit scroll or file upload, but these are advanced and not critical for most automation workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers