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

Annotations already cover readOnly/idempotent/non-destructive, so the 'Read-only' sentence is redundant; the real value is the disclosure that invite rows are recorded but NOT enforced when invite_only is false. That is a genuine behavioral trait not present in any structured field and prevents a serious misreading of the results. Minor deduction only for the repeated safety claim and the absence of any note on result size or ordering.

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 return payload is front-loaded, followed by the interpretation rule and then sibling routing — a sensible order. It is dense but every sentence does work, except the redundant 'Read-only' clause that repeats the annotation block.

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?

There is no output schema, and the description compensates well by enumerating the returned fields and the invite_only flag. The remaining gap is parameter-level: an agent knows what it will get back but not what `app_id` should be, which matters for a tool requiring both parameters.

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 0%, so the description carries the full burden, and it only partially does: 'a coupon' implies that `code` identifies the coupon, but the `app_id` parameter is never mentioned or explained. With just two required parameters and no schema documentation, a brief note on whether code is the coupon code and what app_id scopes would have closed the gap.

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 plus the exact payload returned: per-address status (invited / redeemed / revoked), invite source, timestamps, and the coupon's invite_only flag. It explicitly differentiates itself from list_coupons, invite_to_coupon, and revoke_coupon_invite by name, so no sibling ambiguity remains.

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?

Routes the agent precisely: list_coupons for terms, invite_to_coupon to add addresses, revoke_coupon_invite to withdraw one. It also gives the interpretation rule ('read that FIRST' on invite_only) that determines whether the returned rows actually mean anything, which is exactly the kind of conditional guidance an agent needs before acting.

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