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

Annotations only say read-only and closed-world; the description adds substantial behavior: the return payload shape (summary, next_steps, tool_hint), long-polling semantics capped at 30s, cursor-based resumption, and the OAuth constraint that only one side (buyer or seller) is visible per call. That last constraint is exactly the kind of non-obvious behavior an agent needs. Missing: whether the stream terminates, ordering guarantees, or rate limits.

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 compact sentences, front-loaded with the resource and payload, no filler. The telegraphic fragment style ("role buyer|seller (OAuth: one side per call)") is dense and slightly hard to parse on first read, but nothing is wasted.

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?

Without an output schema, the description does describe the returned keys, and it covers long-polling and cursor resumption well. It is still incomplete for a 6-parameter, zero-coverage tool: order_id scoping, limit behavior, and what an empty/timed-out response looks like are unaddressed.

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% across 6 parameters, so the description must compensate. It meaningfully explains role (buyer|seller), since (cursor or "now"), and wait_seconds (long-poll timeout ≤30). It leaves limit, api_key, and especially order_id (scoping to a single order?) unexplained, which is half the surface.

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?

"Events on your orders (game currency)" names a resource and an implicit verb (fetch/subscribe), and the payload keys (summary, next_steps, tool_hint) hint at what an event looks like. However, "events" is never defined (state changes? chat? payment?), and nothing distinguishes it from siblings like webaz_buyer_orders or webaz_notifications.

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?

"since = last next_cursor or 'now'" and "wait_seconds ≤30 returns when one arrives" effectively tell the agent how to poll/long-poll, which is real usage guidance. There is still no explicit when-to-use-this-vs-alternative statement, and no note on what to do when nothing arrives within the wait window.

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