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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the return is a HAL collection embedding fx:coupons, and it maps to the hAPI endpoint GET /stores/{store_id}/coupons. It does not describe pagination limits or default page size behavior, which the schema only partially implies.

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 short sentences, front-loaded with the purpose, followed by return shape and the underlying endpoint. Nothing is padded, though the hAPI endpoint reference is only useful to agents already familiar with Foxy's API conventions.

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?

For a read-only list tool with fully documented schema parameters and no output schema, this covers purpose, return container (HAL collection), and endpoint. The main gap is a lack of pagination expectations, but nothing an agent needs to invoke it correctly is missing.

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 100%, so all four parameters (zoom, limit, offset, store_id) are already well documented in the schema itself. The description adds no parameter-level detail such as valid zoom values or the default-store fallback semantics. Baseline 3 applies when the schema does the heavy lifting.

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 ('List') and resource ('a store's coupons'), with a clarifying gloss that coupons are discount codes plus their rules. The resource is unique among siblings (carts, customers, items, subscriptions, transactions), so no explicit sibling disambiguation is needed. It stops short of distinguishing itself from any alternative, so 4 rather than 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?

The description says what the tool does but never says when to reach for it: no mention of related calls (e.g. fetching a single coupon or a store), no note that store_id may be omitted to fall back to the default store, and no guidance on paginating large coupon sets. Usage must be inferred entirely from the name and schema.

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