browser_handoff

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries most of the burden and does well: it discloses that browser state (tabs, sign-ins) is preserved across the handoff and that the mode flips between headed and headless. It stops short of saying whether the call returns immediately or blocks, and gives no timeout/abort guidance if the human never finishes.

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?

Dense and front-loaded with the primary action, and every clause carries information (why, what state is preserved, what to do next). It loses a point for a convoluted run-on structure with nested parentheses and the dangling phrase 'a CAPTCHA you cannot do', which takes a second read 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?

For a one-enum-parameter tool with no output schema and modest annotations, the description covers the essential mechanics: what changes, what is preserved, and how to proceed afterward. The only real gap is what happens while control is handed off (blocking behavior, failure if the human does nothing).

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 an enum, so the baseline is 3; the description goes slightly further by explaining what each mode means operationally — 'it comes on screen with the same tabs and sign-ins' for show and 'headless again' for hide — beyond the schema's terse 'show: to the person; hide: back to you'.

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?

States a specific verb+resource pair ('hand the browser to the person') and defines both modes of operation (show/hide) with the exact effect on browser state (on screen with same tabs and sign-ins vs headless again). This is clearly distinguishable from siblings like browser_navigate or browser_snapshot, which do not transfer control to a human.

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?

Gives concrete triggering conditions — a login, a 2FA prompt, or a CAPTCHA the agent cannot complete — which is exactly the when-to-use guidance an agent needs to decide between handoff and its own automation tools. It also names the correct follow-up sibling (browser_wait_for) rather than leaving the agent to guess how to resume.

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