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

Annotations already indicate a read-only, non-destructive operation, and the description adds valuable behavioral detail beyond that: returned buyUrls require a two-step HTTP 402 payment flow with a signed X-PAYMENT header, and user confirmation must precede payment. No contradiction exists with the readOnlyHint because the mutation happens via external GET requests, not through this tool.

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 front-loaded with the core purpose, then provides the necessary purchase protocol and safety instruction. Every sentence adds essential information, and there is no fluff or repetition of schema fields.

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?

Despite having no output schema, the description covers the returned data (products, USDC prices, x402 buyUrls), the non-obvious payment behavior, and the required user confirmation. For a single-parameter lookup tool, this is complete enough for an agent to call it and act on the result safely.

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 only one parameter and schema description coverage is 100%; the schema already provides the meaning and example for 'handle'. The tool description does not add meaningful parameter semantics beyond what the input schema contains.

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 precise verb and resource: 'List the real products a swop.id sells on their SmartSite.' It further distinguishes itself from payment-focused siblings by stating that the tool returns prices and x402 buyUrls, not payment execution itself.

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 makes the usage context clear: an agent should use this tool to retrieve a storefront's products and buyUrls, then follow the x402 flow to purchase. It does not explicitly name alternative tools to avoid, but it gives enough workflow context to guide correct use.

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