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

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: what counts as a claim (click on the claim link, once per visitor per day), that counts are never seeded, and that an empty list is explicitly reported.

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?

Two dense sentences with no filler; the counting definition and the window come first, and the honesty/empty-state guarantee closes it. Every clause carries information.

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 does the job of explaining what the returned list represents and how counts are derived, including the degenerate empty case. Ordering guarantees and result-shape details remain unstated but are minor for a read-only top-N list with a limit parameter.

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, but the description adds meaning the schema lacks by defining what a 'claim' actually is and clarifying the 7-day vs all-time window as real observation periods. It still says nothing about how category slugs are resolved or how ties are ordered.

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?

The description states the concrete resource (offers ranked by real user actions) and the two ranking signals plus time windows, which is more specific than the title alone. It does not explicitly contrast itself with the closest sibling, early_offers, so an agent must infer the difference from 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?

Usage is implied by the ranking semantics (popularity this week vs all time), and it explains the empty-result case, but there is no explicit statement of when to pick this over early_offers, recently_changed, or get_offer. The agent is left to infer the selection rule.

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