This server provides a browser automation toolkit with both high-level Stagehand-based interaction and low-level agent-browser CLI control, plus the ability to record narrated demo videos.
Session management: Create/close browser sessions (local or Browserbase cloud), configure viewport size.
Navigation: Navigate to URLs, including localhost tunneling via ngrok for cloud browsers.
Direct page actions: Perform atomic actions like click, type, fill forms via natural-language instructions; supports variables for sensitive data.
Data extraction and observation: Extract structured data from the page; find interactive elements matching a detailed description.
Screenshots and URL: Capture full-page screenshots and get the current page URL.
Autonomous agent: Run a sub-agent to complete a multi-step task on the page (e.g., 'find the most controversial post and summarize comments').
Scenario testing: Execute arrange/act/assert test scenarios with structured pass/fail results.
Run custom scripts: Execute Stagehand scripts (from file or inline source) against the active session, with optional context.
Record narrated demo videos: Given a list of {instruction, narrate} pairs, run each via stagehand.act while capturing CDP screencast, generate TTS narration (via OpenAI), and stitch into a final.mp4. Configure voice, output location, capture size, trailing delay, and whether to keep intermediates.
Low-level CLI control: Access agent-browser help and run arbitrary agent-browser commands (e.g., snapshot, click by ref, eval, network inspection) sharing the same browser session.
Uses Google's Gemini model for AI-powered browser actions in hybrid mode, enabling natural language control of the browser.
Provides tunneling for cloud browser sessions, allowing localhost URLs to be accessible from the cloud.
Leverages OpenAI's TTS model (gpt-4o-mini-tts) for generating narrated demo videos of browser scripts.
Automatically injects the x-vercel-protection-bypass header when accessing Vercel preview deployments, enabling seamless automation.
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., "@Browser Automation MCP go to google.com and search for 'MCP'"
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.
Narrated demo videos from agent-browser flows.
You write a list of steps — agent-browser commands plus the sentence to say over them — and get back an mp4: each step runs as one agent-browser batch, the daemon's viewport stream is captured while it runs, narration is synthesised per step, and the segments are stitched together with the last frame of each held until its narration ends.
agent-browser owns the browser. Point it at local Chrome, a running Chrome over --cdp, or a cloud provider (-p browserbase|kernel|browserless|agentcore), and record the same way.
# 1. Get the page to the starting state (explore with `agent-browser snapshot -i`)
npx agent-browser open https://app.example.com/login
# 2. Describe the demo
cat > steps.json <<'JSON'
{
"steps": [
{ "narrate": "Sign in with the demo account.",
"commands": [["fill", "#email", "demo@example.com"],
["fill", "#password", "hunter2"],
["find", "text", "Sign in", "click"],
["wait", "--load", "networkidle"]] },
{ "narrate": "The dashboard shows this week's numbers.",
"commands": [["find", "text", "This week", "click"], ["wait", "500"]] }
]
}
JSON
# 3. Record
OPENAI_API_KEY=... npx -p @popoverai/browser-automation browser-demo steps.json --out ./demo
# → ./demo/final.mp4(npx -p @popoverai/browser-automation browser-demo because the package is scoped and the bin is not; pnpm add -D @popoverai/browser-automation gives you a bare browser-demo.)
--silent renders the same video with a silent audio track sized to the narration, so you can iterate on the steps without any key.
Related MCP server: hanzi-browse
The binary documents itself, so an agent can be told "use browser-demo" and work the rest out:
browser-demo guide # the full workflow guide (SKILL.md), version-matched to the binary
browser-demo schema # JSON Schema for the steps file
browser-demo example # a starter steps file
browser-demo validate FILE # check a file without opening a browserbrowser-demo --help opens with those, and a failed step prints hints (wrong selector syntax, re-snapshot here, later steps didn't run). SKILL.md is the same guide for agents reading the repo.
{
"url": "https://app.example.com", // optional — `open`ed before recording
"openArgs": ["--headers", "{\"x-vercel-protection-bypass\": \"...\"}"], // optional extra args for `open`
"speech": {
// optional — narration; default is openai:gpt-4o-mini-tts, voice "alloy"
"provider": "elevenlabs",
"model": "eleven_v3",
"voice": "JBFqnCBsd6RMkjVDRZzb",
"instructions": "Warm and unhurried.",
"providerOptions": { "elevenlabs": { "stability": 0.4 } },
},
"steps": [
{
"narrate": "What is said over this step.",
"commands": [
["click", "@e3"],
["wait", "300"],
], // agent-browser argv arrays
"trailingDelay": 1000, // optional, ms (default 1000)
"speech": { "voice": "..." }, // optional per-step override (voice, instructions, speed, language)
},
],
}commands are exactly what agent-browser batch reads on stdin: one argv array per command. Anything the CLI accepts works — click, fill, find text … click, press, scroll, wait --text, eval, …
Each step is one batch --bail. A failing command aborts the demo (the page is then in a state the next narration doesn't describe); the CLI prints which command failed.
trailingDelay is how long to keep capturing after the last command so the final repaint lands in the segment.
Leave url out to record whatever the daemon already has open.
browser-demo <steps.json>
-o, --out <dir> output directory (default: a unique temp dir)
--tts <provider[:model]> narration provider (default: openai:gpt-4o-mini-tts)
--voice <voice> voice id for the narration provider
--silent silent audio track; no key needed
--keep keep per-segment audio/mp4/frames next to final.mp4
--session <name> agent-browser --session to drive
--agent-browser "<cmd>" how to invoke agent-browser (default: "npx agent-browser")
--trailing-delay <ms> default trailing delay for steps (default 1000)
--max-fps <n> cap the stream's frame rate (default: uncapped)
--ffmpeg <path> ffmpeg binary (default: ffmpeg-static's)
--json print a result summary as JSON on stdoutWithout --json, the path to final.mp4 is printed on stdout and progress goes to stderr.
Narration goes through the AI SDK's generateSpeech, so any AI SDK speech provider works. Five ship with the CLI: openai (default), elevenlabs, lmnt, hume, deepgram. Each reads its key from its own env var.
provider |
| key | model examples |
OpenAI |
|
|
|
ElevenLabs |
|
|
|
LMNT |
|
|
|
Hume |
|
| (single model) |
Deepgram |
|
|
|
Where the configuration lives:
Voice, instructions, speed, language, provider options belong in the steps file's speech block — they're part of the demo's content, and voice ids are provider-specific so the model goes with them. A step's own speech block overrides voice/instructions/speed/language for that step only.
Credentials stay in the environment, using each provider package's convention. The CLI checks for the key up front and fails before opening the browser if it's missing.
Flags are one-off overrides: --tts elevenlabs:eleven_v3 --voice <id>, or --silent. Precedence is flags → steps file → default.
Any other AI SDK provider resolves the same way: --tts acme:model imports @ai-sdk/acme, preferring the copy installed in the current project, so npm i @ai-sdk/acme (or npx -p @ai-sdk/acme -p @popoverai/browser-automation browser-demo …) is all it takes.
The recorder talks only to the local agent-browser daemon, so where the browser runs is the daemon's business:
# Built-in providers (see `agent-browser --help` for their env vars)
BROWSERBASE_API_KEY=... npx agent-browser --session demo -p browserbase open https://app.example.com
npx -p @popoverai/browser-automation browser-demo steps.json --session demo
# Or provision the session yourself and hand agent-browser the CDP URL —
# keeps provider-specific features (contexts, proxies, replay) in the provider's own SDK
npx agent-browser --session demo --cdp "wss://connect.browserbase.com?..." open https://app.example.com
npx -p @popoverai/browser-automation browser-demo steps.json --session demoA remote browser adds one round-trip of latency to each frame; segment boundaries skew late by that much, which trailingDelay covers.
import { elevenlabs } from "@ai-sdk/elevenlabs";
import {
AgentBrowserClient,
attachAgentBrowserDemoRecorder,
} from "@popoverai/browser-automation";
const client = new AgentBrowserClient({ session: "demo" });
await client.run(["open", "https://app.example.com"]);
const demo = await attachAgentBrowserDemoRecorder({ client });
try {
await demo.step(
[
["find", "text", "Sign in", "click"],
["wait", "--load", "networkidle"],
],
"Signing in.",
);
const { videoPath } = await demo.render({
outputDir: "./out",
speech: { model: elevenlabs.speech("eleven_v3"), voice: "<voiceId>" }, // omit for a silent track
});
} finally {
await demo.stop(); // idempotent; safe before, after, or instead of render()
}Export | Purpose |
| Enable the daemon's stream, connect, return a recorder. |
| Run one batch, record one narrated segment. Throws |
| Read the captured |
| Stop capturing, narrate + encode, return |
| Close the stream without rendering. |
| Thin spawn-based wrapper over the CLI ( |
| The render pipeline on its own, for frames captured some other way. |
|
|
| The CLI's |
attachAgentBrowserDemoRecorder enables agent-browser stream — a localhost WebSocket on which the daemon relays CDP Page.screencastFrame as JPEG — and stamps each frame on receipt. Step boundaries are stamped from the same clock around each batch, so frames bucket into segments consistently. The stream is change-driven: a static page produces no frames, and the renderer holds the previous frame.
It deliberately does not use agent-browser record. As of agent-browser 0.36, record start opens a fresh browser context in a new tab — cookies and localStorage survive, but the DOM, SPA state, and anything typed do not, so every step would begin with a reload — and record stop needs ffmpeg on PATH and encodes at 10 fps.
Segment length is max(video, audio): the last frame is held until the narration finishes, and an action that outlasts its narration plays to completion over silence.
agent-browser is resolved with npx by default; no global install needed. Its engines asks for Node ≥ 24 (it runs on 22 with a warning). Chrome is found automatically or via agent-browser install / open --executable-path.
ffmpeg. ffmpeg-static downloads a binary at install time; pnpm 10 blocks that until you run pnpm approve-builds. Otherwise pass --ffmpeg <path> or set FFMPEG_BIN. Needs libx264 + aac (any standard build).
Narration needs a key for whichever provider you pick (see Narration); --silent needs none.
Selectors. text=… isn't a selector syntax agent-browser accepts; use find text <value> click or refs from snapshot -i.
OPENAI_API_KEY=... # narration with the default provider (not needed with --silent)
ELEVENLABS_API_KEY=... # or LMNT_API_KEY, HUME_API_KEY, DEEPGRAM_API_KEY, per --tts
FFMPEG_BIN=... # override the ffmpeg binary
# plus whatever agent-browser needs for your provider:
# BROWSERBASE_API_KEY, KERNEL_API_KEY, BROWSERLESS_API_KEY, AWS_* (agentcore), …This package began as a fork of @browserbasehq/mcp-server-browserbase (Apache 2.0) and for a while carried a Stagehand MCP server alongside the demo recorder. That surface — the MCP tools, Stagehand scripts and scenarios, Browserbase session management, ngrok tunnelling — was removed once agent-browser covered the driving side better; agent-browser ships its own agent skills (agent-browser skills get core), so an MCP wrapper wasn't pulling its weight.
Apache 2.0. See LICENSE.
Show help for agent-browser, a low-level browser automation CLI for precise, deterministic control. Call this to see available commands.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral transparency. It clearly states the behavior: showing help and displaying available commands. As a help command with no parameters or side effects, this is sufficient disclosure, though it doesn't detail output format or any prerequisites.
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 two sentences, with the purpose front-loaded in the first sentence ('Show help for agent-browser'). It provides relevant context and usage without any extraneous text.
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 zero-parameter tool with no output schema, the description is complete. It explains what the tool does, what it returns (available commands), and when to call it, which fully covers the agent's needs.
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 has zero parameters, so the baseline for parameter semantics is 4. The description doesn't need to add parameter details, and it correctly makes no mention of parameters.
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 function with a specific verb+resource: 'Show help for agent-browser'. It distinguishes itself from sibling tools by describing agent-browser as a 'low-level browser automation CLI', which sets it apart from the stagehand tools and agent_browser_run.
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 gives explicit usage guidance: 'Call this to see available commands.' It also implies a context difference by calling agent-browser 'low-level' and 'precise, deterministic control', suggesting it is for CLI-level help rather than higher-level stagehand operations, though it doesn't explicitly mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a low-level browser command. Use over Stagehand when you need precise, deterministic control — element-by-ref interactions, DOM inspection, network debugging, JS evaluation. Shares the same browser session as Stagehand.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes | Arguments to pass to agent-browser CLI (e.g. 'snapshot -i', 'click @e2', 'open https://example.com') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds key context: the tool is low-level, deterministic, and shares the browser session with Stagehand. However, it does not mention risks such as side effects on the browser state or that arbitrary commands could be destructive, which prevents a perfect score.
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 three tightly written sentences. The action is front-loaded, and every sentence adds value: purpose, usage guidance, and session-sharing context. No redundant or filler content.
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 simple one-parameter command runner, the description provides strong context: what it does, when to prefer it, and its relationship to Stagehand. It lacks explicit return/output or error behavior, but the presence of sibling agent_browser_help and the schema's examples mitigate this 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 only parameter, 'args', has 100% schema description coverage with examples. The description doesn't add parameter-level details beyond the schema, so the 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 opens with a specific verb and resource ('Run a low-level browser command') and immediately differentiates from Stagehand by emphasizing 'precise, deterministic control'. It lists concrete use cases (element-by-ref interactions, DOM inspection, network debugging, JS evaluation), making the tool's scope clear.
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 use this tool over alternatives: 'Use over Stagehand when you need precise, deterministic control'. Also notes it shares the same browser session as Stagehand, implicitly warning against creating a separate session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform a single action on the page (e.g., click, type).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. Should be as atomic and specific as possible, i.e. 'Click the sign in button' or 'Type 'hello' into the search input'. | |
| variables | No | Variables used in the action template for sensitive data. Reference them in the action as %varName%. Shape: {varName: {value: "...", description?: "..."}}. Example: {"action": "type %password% into the password field", "variables": {"password": {"value": "hunter2"}}}. Globally-configured variables (from STAGEHAND_VARIABLES) are automatically merged; per-call variables override globals on key conflict. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It merely says 'perform' without explaining side effects, whether the action can be undone, if it requires a page to be loaded, or what happens on failure. Since this is likely a state-changing 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 a single, concise sentence that immediately states the tool's purpose with examples. Every word earns its place; no filler or redundancy.
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?
Despite having 2 parameters, nested objects, and no output schema, the description is minimal. It does not explain return values/outcomes, how it connects to other stagehand tools, or the scope of 'action'. Given the complexity and sibling toolset, more context is needed for an agent to select and 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?
Schema description coverage is 100%, with detailed descriptions for both 'action' and 'variables' including examples and variable merge behavior. The description itself adds no parameter information beyond what the schema already provides, so the baseline 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 it performs a single action on the page, with concrete examples (click, type). This distinguishes it from multi-step tools like stagehand_agent or stagehand_scenario, though it doesn't explicitly name sibling tools. The verb 'perform' and resource 'action on the page' are specific 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?
Usage is implied by the phrase 'single action'—suggesting it's for one-off interactions rather than multi-step flows. However, there is no explicit guidance on when to use this tool vs. alternatives like stagehand_observe or stagehand_extract, nor any mention of exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a task autonomously using Stagehand agent in hybrid mode. The agent uses both DOM-based and coordinate-based actions for maximum reliability.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The task prompt describing what you want the sub-agent to accomplish. Be clear and specific about the goal. For example: 'Go to Hacker News and find the most controversial post from today, then summarize the top 3 comments'. The agent will autonomously navigate and interact with web pages to complete this task. Reference sensitive values as %varName% to have them substituted at runtime from variables. | |
| maxSteps | No | Maximum number of steps the agent can take. Default: 20. | |
| variables | No | Variables for sensitive data. Reference them in the prompt as %varName%. Shape: {varName: {value: "...", description?: "..."}}. The description helps the agent understand when to use each variable. Globally-configured variables (from STAGEHAND_VARIABLES) are automatically merged; per-call variables override globals. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds a behavioral detail: 'uses both DOM-based and coordinate-based actions for maximum reliability.' However, it does not disclose potential side effects, permission requirements, return behavior, or the fact that the agent may navigate and interact with external pages, leaving significant behavioral ambiguity.
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—two short sentences that front-load the core purpose ('Execute a task autonomously') and a supporting operational detail ('uses both DOM-based and coordinate-based actions'). Every word contributes meaning, with no redundancy.
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?
This is a high-complexity agent tool with no output schema and no annotations, yet the description is minimal. It does not explain what the agent will do beyond 'execute a task,' how it handles variables or steps, or what the result will look like. The rich parameter schema helps but does not compensate for the missing behavioral and output context.
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%, with detailed descriptions for all three parameters (prompt, maxSteps, variables) already provided in the schema. The tool description itself adds no parameter-specific semantics, so 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 clearly states the tool's purpose: 'Execute a task autonomously using Stagehand agent in hybrid mode.' The verb 'execute' and resource 'task' are specific, and the mention of 'autonomously' distinguishes it from more targeted sibling tools like stagehand_act or stagehand_extract, though it does not explicitly name alternatives.
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 usage for autonomous, multi-step tasks through the word 'autonomously' and 'hybrid mode,' but it does not explicitly state when to use this tool over alternatives or provide exclusions. It lacks direct guidance on when not to use it or how it relates to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a narrated demo video of a known-good Stagehand script. Each action runs through stagehand.act with a CDP screencast attached; per-action narration is generated via OpenAI TTS; per-segment mp4s are concatenated into a single final.mp4. Uses the active Stagehand session — make sure the page is at the desired starting state before calling. Requires OPENAI_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| voice | No | OpenAI TTS voice id. Default: 'alloy'. | |
| actions | Yes | Ordered list of {instruction, narrate} pairs. Each action runs through stagehand.act and becomes one narrated segment of the final video. | |
| maxWidth | No | Screencast capture max width. Default: 1280. | |
| maxHeight | No | Screencast capture max height. Default: 720. | |
| outputDir | No | Absolute directory to write the mp4 (and any intermediates). Defaults to a unique subdir under the OS temp dir. | |
| trailingDelay | No | Milliseconds to wait after each action before recording its end timestamp. Default: 1000ms. Lets in-flight CDP frames arrive. | |
| keepIntermediates | No | If true, keep the per-segment audio + mp4 + frame PNGs alongside final.mp4. Default: false (cleaned up). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It explains the full pipeline: actions run via stagehand.act with CDP screencast, narration via OpenAI TTS, and concatenation into final.mp4. It discloses the need for OPENAI_API_KEY and the prerequisite of an active session at the desired starting page. It does not mention potential side effects on the page state, but this is implied by running 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?
The description is four sentences, each contributing: purpose, process, prerequisite, and environment requirement. It is front-loaded with the main verb and resource, and every sentence adds operational detail without redundancy.
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 complexity (7 parameters, no output schema), the description provides a solid overview of the workflow and key constraints. It explains the pipeline, the active-session dependency, and the need for an API key. It does not explicitly describe the return value, but the outputDir parameter and mention of final.mp4 make the output clear. Minor gap: no mention of failure behavior or cleanup (though keepIntermediates parameter addresses intermediates).
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 provides 100% coverage with descriptions for all 7 parameters, so the description is not required to add much. The description adds context about how actions are processed (via stagehand.act with screencast) and the TTS generation, which indirectly explains the voice and narrate parameters, but it doesn't go beyond the schema's own descriptions. This meets the baseline for high schema coverage.
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 opens with a specific verb and resource: 'Record a narrated demo video of a known-good Stagehand script.' It clearly differentiates from siblings like stagehand_act or stagehand_run_script by emphasizing narration, CDP screencast, and final mp4 concatenation.
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?
It states a clear prerequisite: 'Uses the active Stagehand session — make sure the page is at the desired starting state before calling.' This gives context for when to call. It also indicates this is for 'known-good' scripts, implying not for exploratory use. However, it does not explicitly name alternative tools or state 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.
Extract structured data or text from the current page using an instruction.
| Name | Required | Description | Default |
|---|---|---|---|
| instruction | Yes | The specific instruction for what information to extract from the current page. Be as detailed and specific as possible about what you want to extract. For example: 'Extract all product names and prices from the listing page'.The more specific your instruction, the better the extraction results will be. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states that extraction happens from the current page and uses an instruction, which implies a read-only operation, but it does not explicitly mention side effects, prerequisites, or output format. The description provides minimal but accurate 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose and key requirement. There is no redundant information or filler.
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 (one parameter, no output schema), the description adequately communicates the core functionality and scope. It could clarify the return format further, but 'structured data or text' gives a sufficient general sense. The description is complete enough for an agent to make a basic selection decision.
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 already covers the parameter with 100% description coverage, including a detailed explanation and example. The tool description only adds the phrase 'using an instruction,' which does not meaningfully enhance understanding beyond the schema.
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 function with a specific verb ('Extract'), the resource ('the current page'), and the outcome ('structured data or text'). This distinguishes it from sibling tools like stagehand_navigate or stagehand_screenshot.
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 that the tool is used when you need to extract data from the current page, but it does not explicitly mention when to use it versus alternatives like stagehand_observe or stagehand_act. No exclusions or alternative tool names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the current page URL (full URL with query/fragment).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns the full URL including query/fragment, which clarifies scope and implies a non-mutating read operation. It does not mention error behavior or prerequisites, but for a simple getter this is reasonable.
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 that is front-loaded with the verb and resource, and every word adds value. It is concise without sacrificing necessary detail about the URL format.
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 has no parameters and no output schema, the description sufficiently describes the return value (full URL with query/fragment). It is complete for a trivial getter 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?
The tool takes zero parameters, so the schema provides complete coverage. The baseline for no parameters is 4, and the description does not need to add parameter semantics because none exist.
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 uses the specific verb 'Return' and identifies the exact resource: 'current page URL', with explicit detail that it includes query/fragment. This clearly distinguishes it from sibling tools like stagehand_navigate or stagehand_extract.
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 usage from its simple getter nature, but it does not explicitly state when to use this tool over alternatives or mention any prerequisites (e.g., requiring an active page). No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find interactive elements on the page from an instruction; optionally return an action.
| Name | Required | Description | Default |
|---|---|---|---|
| instruction | Yes | Detailed instruction for what specific elements or components to observe on the web page. This instruction must be extremely specific and descriptive. For example: 'Find the red login button in the top right corner', 'Locate the search input field with placeholder text', or 'Identify all clickable product cards on the page'. The more specific and detailed your instruction, the better the observation results will be. Avoid generic instructions like 'find buttons' or 'see elements'. Instead, describe the visual characteristics, location, text content, or functionality of the elements you want to observe. This tool is designed to help you identify interactive elements that you can later use with the act tool for performing actions like clicking, typing, or form submission. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the tool finds elements and optionally returns an action, without detailing side effects, return format, session requirements, or any safety implications. This is insufficient for a tool that likely interacts with a live page.
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 that front-loads the main purpose. However, the phrase 'optionally return an action' is vague and could confuse the agent about what the tool actually returns, reducing clarity without adding meaningful structure.
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 is simple (one parameter, no output schema), and the schema description provides extensive guidance on the instruction parameter. However, the description lacks context about the tool's role in the overall workflow (e.g., observing before acting) and its return behavior, making it minimally 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?
The input schema has 100% coverage for the single parameter, with a detailed description of how to formulate the instruction. The tool description adds no new parameter information, matching the baseline of 3 for high schema coverage.
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 finds interactive elements from an instruction, with a specific verb ('find') and resource ('interactive elements on the page'). It also hints at an optional action output, distinguishing it from sibling tools like stagehand_act (which performs actions) and stagehand_extract (which extracts data).
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 explicit guidance is provided for when to use this tool instead of alternatives. The description does not name sibling tools or exclusion criteria, though the 'optionally return an action' phrase implies it may precede act. The schema description mentions later use with the act tool, but the description itself lacks this context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a Stagehand script (default export from defineScript) against the
current browser session. Accepts either a file path or inline
source — exactly one. Returns {status: "passed"|"failed", durationMs}.
On failure also returns error and stack. Use after authoring a script
to validate it; the MCP's live session is reused, so no separate setup
is required. Inline source mode resolves bare imports against the
MCP's own node_modules (no install needed); path mode resolves
from the script's project.
| Name | Required | Description | Default |
|---|---|---|---|
| ctx | No | Optional context object forwarded to the script as `ctx`. The default Ctx shape accepts baseUrl, username, password, and any other string fields without schema declaration. Scripts that declare a custom Ctx generic are responsible for their own runtime validation. | |
| path | No | Path to a .ts or .js file whose default export was produced by defineScript(...). Relative paths resolve against the MCP process's current working directory. Bare imports from the script resolve against the script's own node_modules tree, so the script's project must have the needed deps installed (including @popoverai/browser-automation for defineScript). Mutually exclusive with `source`. | |
| source | No | Inline script source as an alternative to `path`. Useful when the caller has no filesystem access, or when the script is ephemeral. The script is run from a temp location inside the MCP's own package, so bare imports (defineScript, zod, etc.) resolve against the MCP's node_modules — no install required anywhere else. Mutually exclusive with `path`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: it returns {status, durationMs}, includes error and stack on failure, reuses the current session, and explains how bare imports resolve differently in inline vs path mode. It also notes that inline mode runs from a temp location, providing valuable runtime context beyond the schema.
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 well-structured into three logical sections: core behavior, return value, and usage guidance. Every sentence adds informative value without redundancy, making it efficient and easy to parse.
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?
Despite the absence of an output schema, the description fully specifies the return format and explains edge cases like errors, import resolution, and mutual exclusivity. For a tool with three params and a nested object, it provides complete operational context.
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 thoroughly described. The description adds a concise top-level constraint ('exactly one' of path/source) and summarizes the mode-specific difference in import resolution, adding practical meaning beyond the schema's already detailed field 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 states a specific verb and resource: 'Run a Stagehand script... against the current browser session,' and clarifies it executes a default export from defineScript. This clearly differentiates it from sibling tools like stagehand_navigate or stagehand_act by focusing on script execution.
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 use ('Use after authoring a script to validate it') and explains the advantage of reusing the live session with no separate setup. It also provides when-to-use guidance for inline 'source' vs 'path' modes, including the scenario where the caller lacks filesystem access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a multi-step test scenario (arrange/act/assert) using the Stagehand agent. Returns structured pass/fail/blocked results per assert step.
| Name | Required | Description | Default |
|---|---|---|---|
| maxSteps | No | Maximum number of agent steps. Default: 30. | |
| scenario | Yes | A multi-step test scenario with arrange/act/assert steps |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that execution is agent-driven and returns structured pass/fail/blocked results per assert. Yet it does not mention potential side effects (e.g., navigation, state changes) or whether a session is required, leaving behavioral details partially undisclosed.
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 two concise sentences, front-loaded with the core action and outcome. Every word earns its place, with no redundant 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?
The schema covers parameter semantics thoroughly, and the description explains the tool's purpose and result format. However, it omits prerequisites like session usage and does not discuss how this relates to sibling tools, leaving some contextual gaps for a complex 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?
Schema description coverage is 100%, so the schema already documents all parameters in detail. The description adds no parameter-specific meaning beyond what the schema provides, matching the baseline of 3.
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 executes a multi-step test scenario using the Stagehand agent, with specific arrange/act/assert structure. It distinguishes itself from sibling tools like stagehand_act (single action) and stagehand_navigate by emphasizing the multi-step scenario nature.
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 usage for multi-step test scenarios and mentions returns per assert step, giving context. However, it does not explicitly state when to prefer this over alternative tools or exclude single-action cases, so it lacks direct exclusions but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture a full-page screenshot and return it (and save as a resource).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The name of the screenshot |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the screenshot is returned and saved as a resource, adding useful side-effect information. However, it lacks details on output format, resource naming, or whether an active page is required, leaving some behavioral ambiguity.
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 of 12 words, immediately conveying the core function and side effect. Every word contributes value, with no redundant or vague filler.
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 simple tool with one parameter and no output schema, the description covers the essential action and the resource-saving behavior. It is complete enough for a basic screenshot tool, though it could clarify what 'return it' means (e.g., base64, URL) or that an active page context is required.
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 has a single parameter 'name' with full description, achieving 100% schema description coverage. The tool description does not add additional meaning to the parameter beyond what the schema already provides, aligning with the baseline 3 for high schema coverage.
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 'Capture a full-page screenshot and return it (and save as a resource)' clearly states the action (capture) and the resource (screenshot), while specifying 'full-page' to differentiate it from partial screenshots. It is distinct from sibling tools like stagehand_navigate or stagehand_extract, which serve different purposes.
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 stagehand_observe or stagehand_demo_video. There is no mention of prerequisites (e.g., an active session or page) or exclusions, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the current browser session and reset the active context.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses two concrete actions (closing session and resetting context), which is more than a bare 'Close session'. However, it does not mention side effects like unsaved data loss, reversibility, or prerequisites, which would be expected for a destructive 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 that is concise and front-loaded with the action. Every word contributes to the meaning, with no unnecessary fluff.
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 zero-parameter, no-output-schema tool, the description covers the essential action and context reset. It does not elaborate on cleanup or timing, but these are less critical given the tool's simplicity. It is mostly complete for an agent to understand when to invoke it.
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 tool has zero parameters, so the schema is empty. The description adds no parameter-specific details, but none are needed. Baseline for zero parameters is 4.
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 uses a specific verb ('Close') and resource ('current browser session'), and adds 'reset the active context' which clearly distinguishes it from sibling tools like navigate or extract. This is a precise statement of the tool's core function.
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 explicit when/when-not guidance or alternative mentions are included. The purpose implies it should be used to end a browser session, and sibling pair with stagehand_session_create suggests the opposite operation, but no direct usage context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a browser session and set it as active. Uses local Playwright by default; set cloud=true for Browserbase cloud.
| Name | Required | Description | Default |
|---|---|---|---|
| cloud | No | Use Browserbase cloud browser instead of local Playwright. Default: false (local). | |
| sessionId | No | Optional session ID to use/reuse. If not provided or invalid, a new session is created. | |
| browserWidth | No | Browser viewport width in pixels. Default: 1024 (local) or 1288 (cloud). | |
| browserHeight | No | Browser viewport height in pixels. Default: 768 (local) or 711 (cloud). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the default backend (local Playwright), the option to use cloud, and the side effect of setting the session as active. However, it does not mention error conditions, session reuse behavior, or return values.
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 two sentences, front-loaded with the action, and every sentence provides useful information without waste. It is appropriately sized for the tool's simplicity.
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 4 optional parameters and no output schema. The description covers the core behavior and the main configuration option, and the schema covers all parameters. However, the description does not mention what the tool returns or the behavior when reusing a sessionId, which may be necessary for an agent to use the tool correctly in all 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?
The input schema has 100% coverage, so the baseline is 3. The description explicitly mentions the cloud parameter and its default, but does not add meaning to browserWidth or browserHeight beyond the schema. Overall, the description adds minimal value over the schema.
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 uses a specific verb 'Create' and a specific resource 'browser session', and also states that the session is set as active. This clearly distinguishes it from sibling tools like stagehand_session_close, which is for closing sessions.
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 usage for creating a session but does not explicitly state when to use this tool versus alternatives. It provides configuration guidance (local vs cloud) but no exclusion criteria or references to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.13.11agent_browser_helpagent_browser_runstagehand_actstagehand_agentstagehand_demo_videostagehand_extractstagehand_get_urlstagehand_navigatestagehand_observestagehand_run_scriptstagehand_scenariostagehand_screenshotstagehand_session_closestagehand_session_createScored across 14 tools
Several tools overlap in purpose, particularly the multi-step execution tools (stagehand_agent, stagehand_scenario, stagehand_run_script, stagehand_demo_video) and the action/observation pair (stagehand_act, stagehand_observe). The descriptions do provide distinguishing details, but the boundaries are not immediately obvious.
Naming conventions are mixed: some tools use verb_noun (stagehand_session_create, stagehand_run_script), some use bare verbs (stagehand_navigate, stagehand_act), and some use nouns (stagehand_agent, stagehand_scenario). Additionally, there are two different prefixes (stagehand_ vs agent_browser_) without a consistent pattern across the whole set.
14 tools is on the higher end of the typical range. While each tool has a distinct function, the set includes several tools for running multi-step workflows (agent, scenario, run_script, demo_video) that could have been consolidated, making the count slightly over-scoped but still reasonable.
The tool set covers the full browser automation lifecycle: session management, navigation, interaction, extraction, screenshots, script execution, and low-level control. There are no obvious missing operations for the domain.
MCP server for building and testing AI agents with multi-model experimentation and insights.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
