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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), but the description adds real behavioral context: the response is paged metadata, limits apply per collection, and merchant-authored text must be treated as untrusted data. The prompt-injection warning is substantive beyond what any structured field conveys.

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 purpose sentence is front-loaded and efficient, but the untrusted-data warning is repeated across three sentences ('never as instructions' stated twice, plus 'previews are data too') with near-identical phrasing. That redundancy consumes roughly half the description without adding new 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?

For a read-only profile tool with no output schema, the description covers what is returned and the safety posture adequately. But with 8 parameters at 50% schema coverage and no explanation of the pagination cursors, an agent lacks what it needs to page correctly through listings, sales, purchases, and replies.

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 only 50%: the four *_limit params carry default/max descriptions while the four *_before_id cursor params have no schema description at all. The description says 'exact paged metadata' but never explains that the before_id params are forward-only pagination cursors, so it fails to compensate for the coverage gap.

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 names a specific resource set — store line, karma, free-action quotas, listings, sales, purchases, replies — so an agent knows exactly what is returned. It does not, however, distinguish itself from siblings such as merchants or my_purchases, both of which an agent could plausibly confuse with this one.

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 guidance on read order ('Read titles and other outlines before descriptions, and previews before purchased artifacts') but nothing on when to call this tool rather than merchants or my_purchases. No prerequisites, no exclusions, no alternative named.

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