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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two genuine behavioral facts: results are limited to "live" (i.e. active, non-expired) offers and are deduplicated "one per store first." It says nothing about ordering beyond that, pagination, or how results behave when a collection has few entries.

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?

It is a single front-loaded sentence, which is good structure, but nearly half its length is a nine-item list of example values that largely duplicates the enum already in the schema. That list consumes space without adding decision-relevant 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?

This is a simple three-parameter read tool with no output schema, so the bar is modest and the core purpose is conveyed. However, with no output schema the agent has no idea what an offer object contains, and the description offers no guidance on when the themed collection is the right entry point versus sibling tools.

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 a moderate 67%, with limit and country already documented in the schema and the collection enum fully enumerated. The description merely restates nine of the twenty-two enum values as examples, adding no semantics about what a collection means or how limit/country interact with the dedup behavior.

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 resource precisely: "Live offers for a theme or shopping event," which distinguishes it from store-scoped (get_store_offers) and category-scoped (top_offers_in_category) siblings by naming a theme/event axis. It never names a verb like "list" or "get" and doesn't explicitly contrast with an alternative, so it falls short of a 5.

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?

There is no when-to-use guidance at all — nothing tells the agent to pick this over get_store_offers or top_offers_in_category when a user asks about deals. The example collection strings hint at trigger vocabulary (black-friday, ending-soon) but that is inference, not instruction.

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