This server is an MCP browser-automation toolkit: it drives a real browser through Stagehand's AI actions and a low-level agent-browser CLI, runs autonomous agents and scripted test scenarios, and can even render a narrated demo video of a flow.
Session lifecycle — stagehand_session_create / stagehand_session_close: open a browser with local Playwright (default) or a Browserbase cloud browser, set viewport size, reuse a session id.
Navigation — stagehand_navigate: go to a URL (localhost tunneling via ngrok for cloud sessions).
AI-driven page interaction — stagehand_act clicks/types from a plain-English instruction, with %varName% variables for secrets.
Page inspection — stagehand_observe (find interactive elements), stagehand_extract (structured data/text), stagehand_screenshot (full-page capture), stagehand_get_url.
Autonomous agents — stagehand_agent (hybrid DOM + coordinate mode, up to N steps) and stagehand_scenario (arrange/act/assert test scenarios with per-step pass/fail/blocked results).
Script execution — stagehand_run_script: run a defineScript Stagehand script from a file path or inline source against the live session.
Narrated demo videos — stagehand_demo_video: replays known-good actions with a CDP screencast, adds OpenAI TTS narration, and concatenates into a final.mp4.
Low-level control — agent_browser_help / agent_browser_run: raw agent-browser CLI commands (element-by-ref clicks, DOM inspection, network debugging, JS eval), sharing the Stagehand 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 of your web app, recorded by your coding agent.
Ask Claude Code, Codex, Cursor, or any agent that can run shell commands for a walkthrough of a flow. It explores the app with agent-browser, writes a short script (the browser commands for each step and a sentence to say over it), and agentic-demo records the script as an mp4 with a voiceover. No screen recorder, no microphone, no editing.
The script stays behind as a file. Nothing improvises during the take, so the same script gives the same video, and when the app changes you re-record instead of redoing the demo.
Paste this into Claude Code, or any coding agent:
Use `agentic-demo` to create a demo of this feature. Start from `npx agentic-demo --help`.The agent does the rest. It will tell you if it needs anything from you, such as an OpenAI API key for the voiceover. You get a video file, plus the script it was made from, so you can ask for a fresh recording whenever the feature changes.
Related MCP server: hanzi-browse
The voiceover costs money. It is generated by a voice provider (OpenAI by default) and billed to your account with them.
Your pages reach your agent's model. Your coding agent reads the pages it explores, and like anything else it reads, that content goes to the model behind it. agentic-demo itself sends only the narration text, to the voice provider (or the voice endpoint you point it at); the recording and the video stay local. A cloud browser's provider sees the pages too.
The video shows whatever is on screen. Record against demo data, not real customers.
Passwords stay out of the script. The guide tells your agent to sign in through agent-browser's encrypted credential store, so no password is written into the file.
Add this to your project's instructions so your agent reaches for agentic-demo whenever you ask for a demo:
## Demo Videos
Use `agentic-demo` to record narrated demo videos of web flows. Run `npx agentic-demo guide` for the workflow before writing a steps file.npm install -g agentic-demo # Global
npm install -D agentic-demo # Pinned in a project
npx agentic-demo --help # Without installing
npm install -g agentic-demo@latest # UpdateRequires Node.js 22+. Installing downloads an ffmpeg binary (about 77 MB); pnpm 10 blocks that download until you run pnpm approve-builds, or point --ffmpeg / FFMPEG_BIN at another ffmpeg. agent-browser runs as npx agent-browser, which uses your installed copy if there is one. The same CLI is also published as @popoverai/browser-automation.
Versions are 0.x, so a minor version can break things. The changelog lists every change.
agentic-demo <steps.json> # Record to an mp4 (same as `record <steps.json>`)
agentic-demo validate <steps.json> # Check a steps file without opening a browser
agentic-demo guide # Print the workflow guide for agents
agentic-demo schema # Print the steps file's JSON Schema
agentic-demo example # Print a starter steps fileFor the step-by-step workflow, run agentic-demo guide.
Option | Description |
| Output directory (default: a new temporary directory) |
| Narration provider and model (default: |
| Get narration from a voice endpoint instead |
| Voice id for the narration provider |
| Silent audio track sized to the narration; no key needed |
| Keep each segment's audio, video and frames next to |
| agent-browser session to drive |
| How to run agent-browser (default: |
| Default |
| Cap the capture frame rate (default: uncapped) |
| ffmpeg binary (default: ffmpeg-static's, or |
| Print the summary in |
Without --json, stdout is the path to final.mp4 and progress goes to stderr.
A recording writes final.mp4 and, beside it, final.json: the video's length, and for each step where it begins in the video and how long it took. Every run writes it, narrated or --silent; --json prints the same summary.
{
"videoPath": "/home/me/demo/final.mp4",
"outputDir": "/home/me/demo",
"durationSeconds": 16.16, // Length of final.mp4
"segments": [
// One per step, in the steps file's order
{
"index": 1, // The step's position in the steps file, from 0
"instruction": "click #red", // The step's commands
"narrative": "Turn the page red.", // The step's narration
"startSeconds": 2.323, // Where the step begins in final.mp4
"captureSeconds": 1.01, // How long its commands took to run
"narrationSeconds": 1.6, // Length of its narration
"renderedSeconds": 1.88, // Its length in final.mp4
"frameCount": 2, // Frames captured; 1 means the step changed nothing on screen
},
],
}startSeconds is the time of the step's first frame in final.mp4, rounded up to the millisecond, so a player that seeks there shows that step rather than the end of the one before. Use it to open the video at a step. Don't add up renderedSeconds instead: joining the steps starts each one a few hundredths of a second later than that sum.
{
"url": "https://app.example.com/login", // Optional: opened before recording; omit to record the current page
"speech": { "provider": "openai", "voice": "alloy" }, // Optional: narration settings
"steps": [
{
"narrate": "Sign in with the demo account.", // Said over this step
"commands": [
["auth", "login", "demo", "--no-navigate"], // "demo": credentials saved with `agent-browser auth save`
["wait", "--load", "networkidle"],
], // agent-browser commands, one argv array each
"trailingDelay": 1000, // Optional: ms to keep capturing after the last command
},
],
}Also optional: openArgs (extra arguments for open), speech.endpoint (a voice endpoint URL, in place of speech.provider), speech.model, speech.instructions, speech.speed, speech.language, speech.providerOptions, and a per-step speech block. agentic-demo schema prints the full schema.
A step can change the browser's size, with ["set", "viewport", "375", "667"], to show a flow on a phone after a desktop. The video keeps one size, the widest and tallest the recording reached, and fits the smaller view inside it, centred on black.
If agent-browser stops sending the browser's picture partway through, the recording stops with an error that names the step, instead of finishing a video that freezes there.
Five voice providers ship with the CLI. Each reads its key from its own environment variable:
Provider |
| Key | Models |
OpenAI |
|
|
|
ElevenLabs |
|
|
|
Hume |
|
| (single model) |
Deepgram |
|
|
|
Vercel AI Gateway |
|
|
|
Choose the provider and voice in the steps file's speech block, or for one run with --tts and --voice.
The AI Gateway reaches several providers' voices with one key. Its model ids name the provider too, as in --tts gateway:openai/tts-1; the AI Gateway model list has the current set. Without --voice, the model's own default voice speaks.
Instead of calling a voice provider itself, agentic-demo can ask an HTTP endpoint for each narration line. Use this when the machine that records should not hold a provider key: your app keeps the key, decides whether to narrate, and returns the audio. Name the endpoint with --tts https://… or "speech": { "endpoint": "https://…" }, and put the credential your endpoint expects in AGENTIC_DEMO_TTS_TOKEN.
Before it opens the browser, agentic-demo narrates the first step, so a refused token or a used-up quota stops the run before any recording. The rest of the lines are requested while the video is rendered, in parallel, one request per step. The first line's audio is reused, so a run makes one request per step in all.
Request
POST <endpoint URL>
Authorization: Bearer <AGENTIC_DEMO_TTS_TOKEN>
Content-Type: application/json
Accept: audio/*
{
"text": "Sign in with the demo account.",
"model": "gpt-4o-mini-tts",
"voice": "alloy",
"instructions": "Friendly product walkthrough; unhurried.",
"speed": 1.0,
"language": "en",
"outputFormat": "mp3",
"providerOptions": { "openai": { } }
}Authorization is sent only when AGENTIC_DEMO_TTS_TOKEN is set.
text is always present. outputFormat is "mp3" unless the steps file sets another. Every other field is present only when the steps file (or --voice) sets it, and is passed through without checking, so your endpoint decides which to honour and which models and voices to allow.
model and voice come from the steps file only when its speech block names this same endpoint; a voice chosen for a provider is not sent. --voice is always sent. A step's own speech block overrides voice, instructions, speed and language for that line.
Success: any 2xx status with the audio bytes as the body and an audio/* Content-Type (audio/mpeg, audio/wav, …). The format is read from the bytes, so any format ffmpeg can decode works. A 2xx answer without an audio/* Content-Type is treated as an error.
Refusal: any non-2xx status. Put the message for the person in the body, as JSON or as plain text:
HTTP/1.1 402 Payment Required
Content-Type: application/json
{ "error": "Your team has used this month's narration quota. Upgrade at https://example.com/billing." }agentic-demo stops, exits with status 1, and prints the error string exactly as sent, on its own line after the status. When the body is not JSON with a string error, it prints the whole body. It does not retry. A 401 or 403 when AGENTIC_DEMO_TTS_TOKEN is unset also says that no credential was sent.
[agentic-demo] the voice endpoint https://app.example.com/api/voice refused to narrate (HTTP 402):
Your team has used this month's narration quota. Upgrade at https://example.com/billing.Apache-2.0. Originally forked from @browserbasehq/mcp-server-browserbase.
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.
