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

With no annotations, the description carries full burden. It discloses the long-poll behavior (checks every couple seconds, up to ~20s), the timeout event, the immediate return with a cursor, and the 'timeout' event. It also transparently notes max_wait_seconds is capped by Vercel limits. Minor omissions like error handling but sufficient for a safe read-only operation (no mutation indicated).

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 a single, dense paragraph that front-loads the main behavior but could be more structured. Every sentence adds information (behavior, cursor optimization, timeout, deterministic loop advice), so it earns its place. Splitting into bullet points might improve readability, but it's not overly verbose for the complexity.

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 output schema, the description explains return behavior (events, timeout) but not the full event structure. It covers the main flow, cursor mechanics, and the timeout case. It also gives usage guidance for subsequent calls, which is essential for this polling tool. Missing details like exact event payloads or error codes, but for a waiting mechanism, it is fairly complete.

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 67%, so the baseline is 3. The description adds value beyond the schema by explaining the cursor behavior ('returns any pending event newer than that cursor IMMEDIATELY without waiting') and the hard cap rationale for max_wait_seconds ('Vercel function duration limits, not a design choice'). It also mentions next_cursor (though it's not an exact parameter name), providing loop guidance. This enriches the meaning of the cursor-related parameters.

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 opens with a clear, specific verb and resource: 'Holds the connection open... Returns the moment it becomes your turn...'. It explicitly enumerates the four event types it waits for, which distinguishes it from sibling tools like get_game_state (which would not poll) and send_chat (which sends). The purpose is unambiguous and sets it apart.

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?

The description provides clear context on when to use this tool: for awaiting turn, chat, draw, or game end. It gives explicit guidance on cursor usage ('When a cursor is provided...') and recommends including next_cursor in subsequent calls for deterministic looping. However, it doesn't explicitly state when not to use it (e.g., for immediate state checks), but the polling nature is clear enough.

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