Skip to main content
Glama

Browser Wait

browser_wait

Waits for a page element to reach a specified state, such as visible or hidden, using a CSS selector and timeout to synchronize UI actions.

Instructions

Wait for an element to reach a specific state. IMPORTANT: Only useful with a selector - calling without a selector is pointless because MCP round-trip time already provides natural delays. Good uses: wait for element to appear (state='visible') or loading spinner to disappear (state='hidden'). Args: selector = CSS selector to wait for, timeout = max wait in ms, state = 'visible'/'hidden'/'attached'/'detached'.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "browser_wait"
  }
}

Input Schema

NameRequiredDescriptionDefault
stateNoTarget state ('visible', 'hidden', 'attached', 'detached').visible
sessionNoSession ID (e.g., "s1", "s2"). None uses primary session.
timeoutNoMax wait time in milliseconds.
agent_idNoAgent identifier for binding check. Optional.
selectorNoCSS selector to wait for.

Output Schema

NameRequiredDescriptionDefault
errorNoError message if success=False
popupNoPresent when a popup dialog is active on screen
stateNoElement state waited for: 'visible', 'hidden', 'attached', or 'detached'
successNoWhether the operation succeeded
timeoutYesTimeout duration (ISO 8601 format in JSON, e.g., 'PT30S')
selectorNoSelector waited for
active_windowNoWhich window was operated on (e.g., 'wnd[0]', 'wnd[1]'). If 'wnd[1]' or higher, a modal dialog is open.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are supplied, so the description carries the burden, and it does disclose the key non-obvious behavior: the tool is inert without a selector because round-trip latency already supplies delay, which also implies selector is de facto required despite being optional in the schema. It omits what happens when the timeout expires (error, exception, or a false return) and whether the call blocks, which matters for a wait primitive.

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-loads the important constraint before any parameter talk, and the bold IMPORTANT marker concentrates the actionable warning in one clause. The trailing 'Args:' sentence largely duplicates a schema with full descriptions and is the one part that does not earn its space.

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?

Output schema exists, so return values need no explanation, and the description covers the selector/state/timeout semantics and session targeting adequately for a 5-parameter tool. The remaining gap is timeout-expiry behavior, which is the most consequential unknown for a waiting tool.

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 the baseline is 3, but the description adds meaning the schema does not: it frames selector as effectively mandatory and pairs each state value with a concrete scenario (visible for appearing, hidden for disappearing). The Args line otherwise restates the schema, and the session/agent_id binding behavior is not elaborated beyond the session note.

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

Purpose4/5

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

States a specific verb and resource: 'Wait for an element to reach a specific state', and immediately qualifies its applicability with 'Only useful with a selector'. It is unmistakably distinct from the surrounding browser_* action tools (click, fill, navigate), though it never names a sibling to route against.

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?

Gives both when-to-use and when-not-to-use with a rationale: calling without a selector is 'pointless because MCP round-trip time already provides natural delays', and it offers two concrete good uses (element appear with state='visible', spinner disappear with state='hidden'). An agent has everything needed to decide whether to call this at all.

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