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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds substantive behavior an agent could not infer: callback data is untrusted and sender unverified, the inbox must stay valid for the whole timeout, 'at no extra cost', and the precise meaning of a deadline. The clarification that a timeout means 'no matching retained event was observed, not that the sender never tried' prevents a costly misreading.

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?

Nearly every sentence carries load, and the critical constraint (returns a job ID, not a held connection) appears early. The telegraphic run of short sentences around matching and cursors is dense but slightly fragmented, and the 'at no extra cost' clause is the weakest line.

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?

An output schema exists, so return values need no explanation, and the description covers trust model, deadline semantics, inbox validity and the confirm gate. The remaining gap is timeout_sec behavior and what request_key is for, which matters for a long-polling tool with a configurable deadline.

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 0%, so the description must compensate, and it partly does: it defines match as exact matching on up to four top-level JSON scalar fields, explains that omitting after means only new events while a saved cursor includes retained history, and flags confirm. But timeout_sec, request_key, api_key and inbox_id are never given meaning, leaving four of seven parameters undocumented.

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 ('wait asynchronously for an event in your private callback inbox') and immediately clarifies the non-obvious scope: it returns a job ID rather than holding a connection. That single clause separates it from a naive blocking-wait interpretation and from the read_callback_events sibling it later names.

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?

Gives an explicit workflow and routes to alternatives: 'Poll read_readiness_jobs every 15s; matched gives event_id for read_callback_events', plus the hard gate 'Nothing starts without confirm=true'. It stops short of stating when NOT to use this tool (e.g. if the event may already have arrived), so it is a strong 4 rather than a 5.

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