DialogBrain

browser_handoff

Read-onlyIdempotent

When a site asks for verification (2FA, captcha, identity check, re-login) that only the person can do, call this tool with the browser identity name and the URL that needs them. Returns a link to give the person — clicking it opens their browser identity already on that page. When they finish they press Done, and you can continue. For several pages in a row, navigate the SAME prepared window rather than preparing a new one: the person keeps watching one window.

With prepare=True (optional): start the identity's browser server-side on the URL, attach it for form-filling, and return a page_id. Use the page_id with browser.fill / browser.click to fill the form in the live browser before giving the person the link — they will see it already filled and only need to review and complete verification steps that only they can do (CAPTCHA, consent, 2FA code). The window stays open for 30 minutes; if you do not send the link within that time, the window closes and the person must start over.

Input Schema

TableJSON Schema

Name	Required	Description
`url`	No	The URL that needs the person's attention. Must be https or http, and on the same domain as the identity's origin (e.g. https://dashboard.stripe.com/auth/verify). Subdomains are allowed.
`close`	No	If true (optional, default false): close the identity's prepared window that nobody has opened yet. Use this when you no longer need the window you prepared with prepare=true; a window the person has opened is left to them. Returns whether a window was closed. Requires EDIT role (same as prepare). The window only closes if it belongs to this workspace. OMIT for a normal handoff.
`reason`	No	Why the person is needed (optional, for context). E.g. '2FA code entry', 'identity verification', 'security check'.
`prepare`	No	If true (optional, default false): start the identity's browser server-side on the URL and attach it so you can fill the form with browser.fill / browser.click before giving the person the link. Returns a page_id you can drive with the generic browser tools, plus the handoff link. False or omitted: just build and return the link — the browser starts when the person opens it.
`identity`	Yes	The browser identity, by name or id (as browser.open takes it). Must be an active identity in this workspace.
`in_workspace`	No	Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 16, 2026

changedInput schema / properties / close / description

Previous value: -"If true (optional, default false): close the identity's prepared window that nobody has opened yet. Use this when you no longer need the window you prepared with prepare=true; a window the person has opened is left to them. Returns whether a window was closed. Requires EDIT role (same as prepare). The window only closes if it belongs to this workspace."New value: +"If true (optional, default false): close the identity's prepared window that nobody has opened yet. Use this when you no longer need the window you prepared with prepare=true; a window the person has opened is left to them. Returns whether a window was closed. Requires EDIT role (same as prepare). The window only closes if it belongs to this workspace. OMIT for a normal handoff."

Changed2 schema fields changedOct 15, 2026

addedInput schema / properties / close

Added value: +{
+  "description": "If true (optional, default false): close the identity's prepared window that nobody has opened yet. Use this when you no longer need the window you prepared with prepare=true; a window the person has opened is left to them. Returns whether a window was closed. Requires EDIT role (same as prepare). The window only closes if it belongs to this workspace.",
+  "type": "boolean"
+}

changedInput schema / required

Previous value: -[
-  "identity",
-  "url"
-]New value: +[
+  "identity"
+]

Changed1 schema field changedOct 15, 2026

addedInput schema / properties / prepare

Added value: +{
+  "description": "If true (optional, default false): start the identity's browser server-side on the URL and attach it so you can fill the form with browser.fill / browser.click before giving the person the link. Returns a page_id you can drive with the generic browser tools, plus the handoff link. False or omitted: just build and return the link — the browser starts when the person opens it.",
+  "type": "boolean"
+}

AddedOct 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations cover safety (readOnlyHint, destructiveHint=false, idempotentHint, openWorldHint), and the description adds rich context beyond them: the 30-minute window lifetime, that the window closes and the person must start over if the link is not sent in time, that the person presses Done to release control, and the fill-before-handoff workflow. These are exactly the behavioral facts an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

Front-loaded with the trigger condition and core action, then a second paragraph for the prepare path. Mostly earns its length, though the prepare paragraph restates details already present in the schema and the 'several pages in a row' sentence is somewhat padded.

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

Completeness4/5

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

No output schema exists, and the description does cover returns (a link to give the person, optionally a page_id) and the important lifecycle constraints. It is thorough for a 6-parameter tool, with only minor gaps such as exact error/edge behavior when the identity is missing or invalid.

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

Parameters4/5

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

Schema coverage is 100%, so parameter documentation is already strong, and the description does not need to re-explain each one. It still adds value by wiring the parameters into a workflow (identity + url produce a link; prepare returns a page_id to drive with browser.fill / browser.click), going slightly beyond the schema baseline.

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

Purpose5/5

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

The description names a specific action (hand a browser identity off to a person for verification) and enumerates the triggering conditions (2FA, captcha, identity check, re-login). It also distinguishes the two modes (plain link vs. prepare=True) and points to browser.fill / browser.click for the prepared path, so an agent can separate it from the generic browser_* siblings.

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

Usage Guidelines5/5

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

Explicit when-to-use ('When a site asks for verification that only the person can do'), explicit when to choose prepare=True (to pre-fill a form before handing the link over), and guidance for the multi-page case (reuse the SAME prepared window). This is a complete routing rule for the tool.

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

All DialogBrain tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?