browser_dismiss_overlays

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is heuristic-based, how it locates close affordances, the effect of scope values (non_critical preserves form inputs, aggressive dismisses everything), and that it returns a list of what was dismissed. This is strong transparency, though it could have noted potential edge cases like shadow DOM or unclosable overlays.

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 compact and front-loaded: purpose, heuristic mechanism, usage examples, and return value are each covered in a few tight sentences. There is no filler or redundant restatement.

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 no annotations and no output schema, the description covers the key decision factors: what the tool does, when to use it, how it behaves heuristically, and what it returns. The main gap is not explicitly excluding native JavaScript dialogs, which could cause confusion with the sibling browser_handle_dialog, but overall an agent can invoke 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%, so the baseline is 3 and the schema already explains both scope and max_passes. The description adds useful context for max_passes ('some overlays reveal others when closed') and reinforces the scope trade-off, but it does not carry the parameter-documentation burden.

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 and resource: dismiss visible popups, modals, tooltips, banners, and 'Are you sure?'-style overlays in one call. The heuristic details (finding close affordances via aria-label, text, or ×) distinguish it from related siblings like browser_handle_dialog, which handles native dialogs.

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?

Provides clear usage context: 'Use when a flow is interrupted by unexpected dialogs' with concrete examples such as cookie banners, onboarding tooltips, and Meta Ads draft-confirm prompts. It does not explicitly state when not to use it or mention alternatives for native dialogs, but the described conditions are unambiguous.

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