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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds genuinely new behavior: pagination semantics (count equal to limit usually means another page exists, but with active filters a smaller count does not guarantee the end), partial-failure reporting via "sites_failed", and the caveat that a failed site does not mean the product is absent there. It stops short of auth/rate-limit details, so a 4 rather than 5.

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?

Purpose and marketplace scope come first, then filtering/sorting, then pagination and failure caveats — a sensible information hierarchy. Despite the density of parentheticals every sentence contributes operational detail an agent would otherwise have to infer.

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 an 11-parameter, multi-marketplace tool with nested site_filters, the description covers the hard parts: default site behavior, opt-in sites, pagination interpretation, and partial failure. Return fields (image_url, price, count, page) are described even though an output schema exists, which is mildly redundant but not harmful.

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 schema already explains every parameter including the site_filters marketplace-specific shapes. The description largely restates schema content (price_min/price_max range, sort: price_asc = cheapest) with only marginal added meaning around currency units. Baseline 3 applies when the schema carries the load.

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 and resource ("Busca produtos por palavra-chave") plus the exact scope: which marketplaces are queried by default and under which API credentials (Shopee/AliExpress/Amazon via Creators API, Kabum/Magalu only when "site" is set). An agent can distinguish this from get_product (single item) and convert_links (link conversion) without opening 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?

Gives concrete usage context: filter by price range, sort with price_asc for cheapest first, and the explicit rule that kabum/magalu are opt-in only. It even prescribes when to reach for key_seller_only (when many unavailable sellers appear). What it lacks is an explicit statement of when NOT to use this tool in favor of get_product or get_bot_info, which keeps it below a 5.

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