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

The annotations already establish readOnly/idempotent/non-destructive, so the description's added value is the 25-second ceiling, the concurrency restriction of one active wait per agent, and the explicit 'does not mark messages read' side-effect boundary — all genuine behavior an agent could not infer from schema or annotations. Missing is what happens on timeout expiry (empty result vs error).

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?

Three tight sentences, front-loaded with the wait duration and constraint, then parameters, then the side-effect disclaimer. No filler or restatement of the title.

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?

With no output schema, the description usefully supplies the return shape (next_after and since continuation values) and the read-state guarantee, which is more than most. The gaps are the undocumented timeout_seconds semantics and the unspecified timeout-expiry outcome, which matter for a tool whose whole purpose is bounding a wait.

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 only 25% (room_id only), so the description carries most of the burden: it explains that after=-1 means before the first message and that since is optional, and it names the next_after/since continuation values. It never explains timeout_seconds by name (its 0-25 range, default, or interaction with the stated 25-second cap), leaving one of four parameters undocumented anywhere.

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 ('waits ... for new room activity') plus the 25-second bound, and the closing clause 'Does not mark messages read' implicitly separates it from read_message/catch_up. It never names a sibling outright, so an agent must infer the routing rather than being told.

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?

Usage is implied by the long-poll framing ('waits up to 25 seconds') and constrained by 'one active wait per agent', which tells the agent not to open parallel waits. However, there is no explicit guidance on when to prefer this over catch_up, catchup, read_around, or room_situation, and no statement of what to do when the wait returns empty.

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