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

Beyond the read-only annotations, the description discloses output shape ('Returns last plus purchases[]'), test-mode behavior with gray test coins, the usePastPurchases edge case, authentication retry logic with sessionId, and explicit prohibitions around begin_agent_link and connector settings. This substantially exceeds what annotations alone 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 dense and front-loaded with purpose and trigger phrases before diving into workflow and constraints. Most sentences earn their place, though the negative instructions overlap somewhat ('Never begin_agent_link again', 'Never ask the owner to edit connector settings or reconnect', 'Never web-search') and could be trimmed without losing meaning.

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 tool with no output schema, the description gives a minimal return outline ('last plus purchases[]') and enough workflow context to proceed. It also covers test mode, empty-history edge case, and authentication retry. A more detailed return schema would make it fully complete, but the description handles the major gaps.

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 the input schema already documents limit, storeId, category, and sessionId fully. The description adds little parameter-specific meaning beyond what the schema says; the mention of sessionId mostly repeats the schema. It also references usePastPurchases, which is not a parameter in the input schema, creating slight ambiguity.

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 opens with a specific verb-resource pair: 'List the owner's recent AgentPay purchases (bought statuses only) with line items.' It clearly distinguishes the tool from status-lookup and product-search siblings by emphasizing 'bought statuses only' and 'line items'. The trigger phrases further reinforce its scope.

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 gives explicit trigger phrases and the 'wants to reorder' condition, plus a concrete workflow: use last.items, then search_products/get_product, then create_purchase. It also provides when-not-to-do guidance such as 'Do not invent a past basket' and 'If usePastPurchases is false, history is empty.' It does not explicitly name a sibling for one-off purchase-status checks, so it stops short of a 5.

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