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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description still adds substantial operational context: seconds-scale latency (~15-35s fresh, ms when cached), cache TTLs (30 min category, 24 h root), credit pricing including free root and unbilled failure modes, API-key requirement, and honesty caveats about language, null prices and null node_ids. This is exactly the beyond-annotations content the dimension rewards.

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?

Front-loaded with purpose, then USE/DON'T USE, RETURNS, HONESTY, LATENCY, MARKETPLACES, COST — every block is load-bearing for a live, billed, cached fetcher. It is long, and the RETURNS enumeration could be trimmed slightly, but there is no filler and no repetition.

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?

No output schema exists, so the description carries the full return-shape burden and does so thoroughly (both page_type variants, field-by-field, plus observed_at/cached). Combined with latency, billing and marketplace coverage, an agent has everything needed to call it correctly and set expectations.

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% so the baseline is 3, but the description adds real semantics beyond the schema: the marketplace is derived from the URL host, the url/country pair must agree, and — most importantly — the tree-walking contract that subsequent calls should reuse URLs returned by a previous answer. It stops short of adding format syntax the schema lacks, so a 4 rather than a 5.

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+resource ('LIVE Amazon Best Sellers list for one category') with the exact payload (top 100 in rank order, breadcrumb name, subcategories) and the dual-mode behavior (category URL vs. root URL returns top-level categories). An agent can distinguish it from serp, product and shopping without opening the 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?

Explicit USE WHEN conditions (what sells best in a category right now, top-100 list, browsing best-seller categories) and explicit DON'T USE with named alternatives: keyword search -> serp, curated shortlist -> shopping, one ASIN -> product, rank history -> product with bsr_history. This is as close to a routing table as a description gets.

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