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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower, but the description still adds substantial behavior: return shape ('each with its 'gift_cards' list and a 'gift_cards_url' page'), ordering ('best match first, one entry per country'), empty-result semantics ('an empty 'gift_cards' list means no discounted cards right now'), and presentation requirements including the tracked purchase link. This goes well beyond what annotations provide.

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 description is long (~140 words) but every sentence earns its place and the core purpose is front-loaded before routing and presentation details. It packs purpose, when-to-use, examples, return shape, exclusions, and output handling into one dense block. A minor trimming of the presentation guidance could tighten it, but it remains highly structured and information-dense.

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 lookup tool with an output schema, a 100%-covered 2-parameter schema, and full annotations, the description is complete: it explains result ordering, empty-list meaning, country behavior, seller-list structure, and how to present results. An agent has everything needed to select and invoke the tool correctly without opening the schema or output schema.

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% with strong per-parameter descriptions, so baseline is 3. The description adds value on top: it shows natural-language query forms ('best gift card discount for Gap') reinforcing how users phrase store_name, and repeats the plain-name-only guidance. It doesn't add syntax details for country_code beyond the schema, but the marginal enrichment of store_name justifies a 4.

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 a specific verb ('Finds a store by name and returns the discounted gift cards currently on sale for it') with a precise resource and scope, and clearly differentiates from siblings by naming get_gift_cards_by_store_id and get_cashback_rates_by_store_name. The title and first sentence alone tell an agent exactly what this tool does.

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?

Explicit when-to-use guidance: 'This is the preferred first call for any gift card question that names a store' with four real query examples, plus 'No prior lookup is needed'. It also states exclusions and alternatives explicitly: use get_ift_cards_by_store_id only when store_id is known, and get_cashback_rates_by_store_name for cashback questions. Nothing is left to inference.

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