ui_dialog

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

With no annotations present, the description carries the full burden and does so: it discloses blocking semantics, the accept/dismiss mapping to OK/Leave and Cancel/Stay, that text applies only to prompt dialogs, the one-shot nature of a pre-set answer ('one answer, used once'), and the safety-timeout auto-dismiss. It also states that the reply reports what the interrupted action did next, which is behavior no schema field conveys.

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 front-loaded with the core action and the blocking condition before the field semantics, and nearly every sentence adds real information. Minor redundancy is the accept/dismiss mapping, which duplicates the enum descriptions and could have been dropped in favor of the less obvious pre-set and timeout behavior.

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?

There is no output schema, so the description takes responsibility for return behavior by explaining that the reply reports the outcome of the interrupted action. Combined with the timeout and pre-set rules, an agent has everything needed to call this correctly in the blocking, the pre-set, and the multi-session 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?

Schema coverage is 100% and the description largely mirrors what the schema already documents – the accept/dismiss meanings are copied nearly verbatim from the enum descriptions. It adds no syntax or format guidance for `text` beyond 'for a prompt add text', and never mentions `session_id`, though the schema covers the multi-session requirement adequately.

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 names a specific verb and resource ('Answer a native browser dialog') and enumerates the four dialog types (alert, confirm, prompt, beforeunload). This is clearly distinct from the surrounding ui_click/ui_fill/ui_navigate siblings, which perform page actions rather than answering modal 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?

It gives an explicit trigger ('When a tool call opens one, its reply says "Browser is waiting on a <type> dialog"') and an explicit blocking condition ('every other tool is refused until you answer here'). It also covers the opposite case – no dialog waiting – where the call pre-sets the answer for the next dialog, which is a genuine when-to-use branch an agent would otherwise get wrong.

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