ask

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

With no annotations, the description carries the full burden and does most of it: it discloses that the call blocks and waits, that the user can override the buttons with free text, the three return shapes (ANSWER, ANSWER (typed), NO ANSWER), that marks are removed after answering, that DONE is prefixed when all marks are auto-detected complete, and that browser_highlight opens full screen and closes afterward. Remaining gaps are timeout/no-answer timing and what happens if the user dismisses the bubble, which the description leaves unspecified.

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?

Front-loaded with purpose and primary use case, and every sentence carries behavioral information rather than filler. It is dense and parenthetical-heavy, with long compound sentences, but nothing is clearly expendable.

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 no-annotation, no-output-schema tool with 4 params, the description covers the return values, the blocking behavior, the two highlighting modes, and the confirm hand-off — everything an agent needs to call it correctly and interpret the result.

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%, so baseline is 3, but the description adds real value beyond the schema: it explains that browser_highlight is used "instead of highlight" (mutual exclusivity not expressible in JSON Schema), that highlight marks make the question avoid covering the screen, and that marks auto-clear plus trigger the DONE result. It does not add format guidance for question/options beyond the schema.

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?

"Ask the user a question in the Buddy bubble and wait for the answer" gives a specific verb, resource, and interaction model (blocking UI prompt) that no sibling shares. It also explicitly distinguishes itself from confirm ("it is not an approval") and from point_out (highlight is described as carrying point_out semantics).

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?

States the triggering condition explicitly ("when you need the user to choose or decide ... instead of guessing") and names the alternative for the approval case ("still call confirm before anything outward-facing"). The hand-over-to-user pattern with highlight is scoped with a concrete example and result shape.

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