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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: the deck is recent-ordered, deduplicated to one bottle per expression, photo-bearing, and pre-filtered for blocked and hidden accounts. Pagination/limit behavior is not described, but the filtering and dedup rules are valuable context.

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?

A single dense sentence with no filler, front-loaded with the resource ('The Explore tab's bottle deck') followed by qualifying clauses. It reads a little colloquially but every clause carries information an agent can use.

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 simple read-only listing tool with one optional parameter and no output schema, the description covers the essentials: what is returned, ordering, dedup, and exclusion rules, while annotations cover the safety profile and the schema carries limit's default/bounds. Only the semantics of limit itself are left unstated.

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?

There is one parameter (limit) with 0% schema description coverage, so the description must carry its meaning and it does not mention limit, the default of 30, or the maximum of 50. Only a faint implication of recency/ordering touches the parameter indirectly; the agent gets no guidance on how limiting affects the deck.

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 identifies a specific resource and scope: recent public shelf bottles with photos, one per expression, filtered for blocked/hidden accounts. It is distinguishable from search_public_bottles and get_feed by the 'Explore tab's bottle deck' framing, though the tool name ('catalog') and the description ('bottle deck') are slightly out of step, adding a small amount of ambiguity.

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 explicit when-to-use or when-not-to-use guidance, and no sibling alternative is named even though search_public_bottles, search_catalog, and get_feed are plausible overlaps. The usage is only implied by the 'Explore tab' framing, leaving the agent to infer the distinction.

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