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

Annotations only declare the write-safety profile; the description adds the behaviors that matter here — blocking, timeout default/max, the timed_out: true signal on expiry, cursor advancement so arrivals between calls are not missed, and replay-before-first-call semantics. One wrinkle: it says max 300 while the schema's maximum is 3600, a constraint mismatch worth noting.

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 sentences, front-loaded with purpose, then default cursor semantics, then timeout/retry. No filler and no restating of the title or schema.

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?

Output schema exists and the description correctly points to get_request for the return shape, and the timeout/cursor model is covered. It does not say whether a returned request is also still retrievable via get_request, or how concurrent waiters interact with the shared position — the main remaining gaps.

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 the baseline is 3. The description goes beyond it by clarifying that the saved cursor is scoped to "this inbox and these filters," which explains how method/path_prefix interact with the default position — meaning the schema alone does not convey.

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 ("Block until a request arrives, then return it in full") and anchors the return shape to a named sibling (get_request), so an agent can tell it apart from the passive reads. The blocking wait semantics are unambiguous.

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?

Explains the default behavior (next not-yet-returned request for this inbox and filters) and prescribes the follow-up action ("call it again to keep waiting"), which tells the agent how to run the polling loop. It never excludes alternatives explicitly, e.g. when to use get_request or list_requests instead of blocking.

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