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

Annotations only declare readOnly/openWorld/non-destructive; the description goes much further by disclosing the signed-out visibility limit, the typical 5-13 review window with local reviews first, the reviewsGated flag and empty-reviews fallback, the guarantee that all fields are present and null when absent, and the proxy_country/exitCountry behavior.

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?

It is front-loaded with return fields and covers the essentials, but the single dense paragraph enumerates every field rather than summarizing, repeats 'JSON' twice, and ends with an off-target billing sentence about max_results that does not correspond to any parameter here.

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?

There is no output schema, so the field-by-field return description is doing necessary work, and the gating behavior, null semantics, and proxy defaults leave nothing an agent needs to know before calling this tool unaddressed.

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 already 100%, but the description adds real meaning: the asin+marketplace vs url either/or identification rule, and the clarification that proxy_country does not change which reviews are returned (only exitCountry reports it). The closing reference to 'max_results' is confusing because no such parameter exists in the schema.

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 concrete verb and resource ('Returns the review data an Amazon product page shows to a signed-out visitor') and immediately enumerates what is returned (rating, reviewCount, histogram, customersSay, reviews), which separates it from amazon_product, amazon_search and trustpilot_reviews without the agent needing to open any schema.

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?

Usage context is explicit: it explains this is the public review slice on the product page, not a complete export, and that amazon.com often gates reviews with reviewsGated=true. It stops short of naming alternatives (e.g. use amazon_product for price/details), so the agent must infer those boundaries, which is the only gap.

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