ultimate-playwright-mcp
Provides browser automation capabilities for Google Chrome, enabling control of tabs, navigation, clicks, form filling, and checkpoint captures through a shared Chrome instance with multi-agent tab isolation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ultimate-playwright-mcpopen a new tab and navigate to example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ultimate Playwright MCP
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
groupIdand 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 | ā 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-mcpOr run directly with npx:
npx ultimate-playwright-mcp --cdp-endpoint http://localhost:9222Quick 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-debug2. 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 |
| Create/list/delete tab groups for isolation |
|
| List, create, close, or select tabs |
|
| Navigate to a URL |
|
| Capture accessibility tree with refs |
|
| Click an element |
|
| Type text into an element |
|
| Hover over an element |
|
| Press a keyboard key |
|
| Fill multiple form fields |
|
| Wait for conditions |
|
| Capture a structured checkpoint for a tab |
|
| Generate reports from stored checkpoints |
|
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/checkpointsby 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
Create a group at the start of your session
Open tabs within the group using
groupIdWork with tabs using
targetIdas beforeDelete 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 helpMulti-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.plistDevelopment
# Install dependencies
npm install
# Build
npm run build
# Type check
npm run type-check
# Lint
npm run lint
# Watch mode
npm run watchLicense
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)
Links
OpenClaw - Source of browser control code
MCP Specification - Model Context Protocol
Playwright - Browser automation library
Available Tools
14 toolsbrowser_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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Unique checkpoint name for this capture. | |
| targetId | No | Target ID of the tab. If omitted, uses the first available tab. | |
| description | No | Long-form description of what the checkpoint captures. | |
| highlightSelector | No | CSS selector to highlight in the screenshot artifact. | |
| fullPage | No | Capture a full-page screenshot when the screenshot collector runs. | |
| collectors | No | Per-collector overrides. Set a collector to false to disable it or provide an options object. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Single report format to generate. Defaults to html. | |
| resultsDir | No | Optional directory containing checkpoint manifests. Defaults to the server-managed checkpoint results directory. |
TDQS
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.
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.
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.
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.
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.
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)
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Element reference from snapshot (e.g., 'e1', 'e2') | |
| targetId | No | Target ID of the tab | |
| button | No | Mouse button to click (default: left) | |
| doubleClick | No | Perform a double-click |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| expression | Yes | JavaScript 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`. | |
| ref | No | Optional element reference from snapshot (e.g., 'e1'). If provided, the expression receives the DOM element as its first argument. | |
| targetId | No | Target ID of the tab |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Array of form fields to fill | |
| targetId | No | Target ID of the tab |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Element reference from snapshot | |
| targetId | No | Target ID of the tab |
TDQS
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.
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.
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.
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.
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.
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_press_keyC
Press a keyboard key
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Key to press (e.g., 'Enter', 'Escape', 'ArrowDown') | |
| targetId | No | Target ID of the tab |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| targetId | No | Target ID of the tab (from browser_tabs). If not provided, uses first available tab. | |
| ref | No | Element reference from snapshot (e.g., 'e1', 'e2') to screenshot a specific element. | |
| element | No | CSS selector to screenshot a specific element (alternative to ref). | |
| fullPage | No | Capture the full scrollable page instead of just the viewport (default: false). Not compatible with ref/element. | |
| type | No | Image format (default: png). Use jpeg for smaller file sizes. | |
| quality | No | JPEG quality (1-100). Only applies when type is 'jpeg'. Default: 80. Lower values = smaller file size. | |
| maxWidth | No | Maximum width in pixels. Image will be scaled down proportionally if wider. Reduces base64 size for large/full-page screenshots. | |
| returnAs | No | How 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). | |
| savePath | No | Custom 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
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| targetId | No | Target ID of the tab (from browser_tabs). If not provided, uses first available tab. | |
| maxChars | No | Maximum characters in snapshot. Truncates with notice if exceeded. Recommended: 5000-15000 for smaller models, omit for full snapshot. | |
| compact | No | Remove unnamed structural elements and empty branches. Reduces snapshot size significantly. Recommended for simpler tasks. | |
| interactive | No | Only include interactive elements (buttons, links, inputs, etc.). Dramatically reduces snapshot size. Best for form-filling and clicking tasks. | |
| maxDepth | No | Maximum tree depth to include (0 = root only). Use 3-5 for focused snapshots of complex pages. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Tab group action to perform | |
| name | No | Human-readable name for the group (for 'create' action) | |
| color | No | Visual color for the group (for 'create' action) | |
| groupId | No | Group name (for 'delete' action) | |
| closeTabs | No | Whether to close all tabs in the group when deleting (default: true) |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Tab action to perform | |
| groupId | No | Tab group name to scope this operation to (from browser_tab_group). Recommended for multi-user isolation. | |
| url | No | URL for 'new' action (defaults to about:blank) | |
| index | No | Tab index for 'close' or 'select' actions (relative to group if groupId is set) | |
| targetId | No | Target ID for 'close' or 'select' actions (alternative to index) |
TDQS
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.
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.
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.
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.
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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Element reference from snapshot | |
| text | Yes | Text to type | |
| targetId | No | Target ID of the tab | |
| submit | No | Press Enter after typing |
TDQS
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.
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.
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.
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.
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.
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.)
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Wait for text to appear on page | |
| textGone | No | Wait for text to disappear from page | |
| selector | No | Wait for CSS selector | |
| url | No | Wait for URL to match pattern | |
| loadState | No | Wait for load state | |
| timeMs | No | Wait for specific milliseconds | |
| targetId | No | Target ID of the tab |
TDQS
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.
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.
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.
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.
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.
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.
14 tool updates
v0.2.1- First observed
browser_checkpoint - First observed
browser_checkpoint_report - First observed
browser_click - First observed
browser_evaluate - First observed
browser_fill_form - First observed
browser_hover - First observed
browser_navigate - First observed
browser_press_key - First observed
browser_screenshot - First observed
browser_snapshot - First observed
browser_tab_group - First observed
browser_tabs - First observed
browser_type - First observed
browser_wait_for
TDQS
Scored across 14 tools
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.
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.
With 14 tools, the server covers core browser automation tasks without being bloated. The count feels well-scoped for its purpose.
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
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
Live browser debugging for AI assistants ā DOM, console, network via MCP.
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA Playwright-based MCP server that exposes a live browser as a traceable, inspectable, debuggable and controllable execution environment for AI agents.3,661 npm57-
- FlicenseNot gradedqualityDmaintenanceA multi-agent orchestrator that enables multiple AI agents to share a single Chrome browser instance with tab isolation and shared state. It preserves local browser data like cookies and logins while allowing concurrent agent sessions through the official Playwright MCP.9-
- AlicenseNot gradedqualityDmaintenanceMCP server enabling AI agents to control and inspect Chrome/Arc browsers via DevTools, with Arc-specific tab reuse.11 npm1Apache 2.0
- FlicenseBqualityDmaintenanceMCP server for AI agents to control Google Chrome via Playwright with full iframe support, enabling end-to-end browser automation including navigation, interaction within iframes, and diagnostic tools.24-