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

Goes well past the annotations (readOnly/destructive/openWorld) by disclosing the 7-day recency window, newest-first ordering, the three-per-store cap, the exclusion of a store's first full catalog read or first feed snapshot, and the bias toward affiliate-programme stores. It also flags that store names, seller text, and discountOffers terms are untrusted data rather than instructions — a genuinely valuable safety note for open-world web content.

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 essential facts are front-loaded in the first two sentences, but a sizeable middle chunk describes how genesispay_catalog_search orders results and handles price and newest orders — detail that belongs to the sibling and does not help an agent call this tool. Roughly a third of the text is tangential for a one-parameter tool.

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 what is returned, how it is ordered, what is deliberately excluded, and a data-trust caveat. Return field detail is reasonably delegated to the search sibling, so no important calling information 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 coverage is 100% and the single limit parameter is already documented with bounds and default, so the baseline is 3. The description adds real meaning beyond that by revealing the per-store cap of three, which explains why the returned count may be lower than limit.

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 and resource (lists store products indexed most recently) and pins the exact scope: first seen in the last 7 days, newest first, at most three per store. It also anchors itself against the sibling by saying the results carry the same fields as a store product from genesispay_catalog_search, so the agent can distinguish it from the other catalog tools.

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?

Explicitly tells the agent what this ranking is NOT (not sales, popularity, or a rating) and that search results from the sibling are ordered by match quality instead, which is useful routing context. It stops short of stating an explicit when-to-use-this-instead-of-X rule, so the guidance is clear but not fully prescriptive.

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