Wait for something

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description is consistent with them ('Read-only'). It adds real behavioral context the annotations do not: the call blocks server-side so no network traffic occurs while waiting, it returns one line describing the event, and it fails with an error on timeout. Return-shape and failure details are exactly what an agent needs for a blocking call.

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 block-on conditions are front-loaded and the operational notes (server-side watching, return value, timeout failure) follow in a logical order. Every sentence carries information, though the long opening sentence packs several modes together and could read more cleanly as a list.

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 five-parameter, nested-object, blocking tool with no output schema, the description covers the essential gaps: what it waits for, that it blocks on the server, what it returns, and how it fails. Only the relationship to overlapping sibling wait tools is left unexplained.

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 all five parameters are already documented. The description restates the mode semantics in prose (including gone=true and 'screen settles (stops changing)') but adds no new distinctions, such as how region interacts with name or default behavior when name is omitted for change/still. Baseline 3 applies.

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 states a specific verb and resource ('Block until something happens on the Amiga') and enumerates the trigger classes: window/task appearance or disappearance, file appearance, screen change, screen settling. It is clear what the tool does, but it never distinguishes itself from siblings like amiga_wait_text or amiga_region_changed, which cover overlapping waiting use cases.

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?

'Use it after starting a program or clicking something that takes time' gives a concrete usage context. It also implicitly contrasts with sleeping, which is a useful framing. However, it offers no when-not guidance and no pointer to the text- or region-specific wait alternatives.

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