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

Annotations already declare readOnlyHint=true, covering the safety profile. The description goes beyond annotations by disclosing real behavioral traits: cached AI pre-validation, the internal mechanism (keyword search then brand-field filtering), the no-match fallback that returns alternative brands, and that results are restricted to rows whose brand field actually matches. This enriches what the agent can predict about behavior beyond the read-only hint.

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 compact — three sentences plus a brief 'How to use' framing. It front-loads the primary action, then explains the mechanism and fallback, and closes with the intended analytical application. No wasted words, though the 'How to use' sentence is somewhat abstract and could arguably be trimmed without loss.

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 read-only listing tool with a rich schema (80% param coverage, nested filters object, enums for sort and marketplace), the description covers the distinctive behaviors (AI pre-validation, brand matching, no-match alternative suggestion). No output schema exists, so the description could have mentioned return structure, but the emphasis on which rows are included is sufficient for a filtered-list tool. Solid coverage overall.

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 80%, so the schema does most of the parameter documentation work (brand, count, sort, marketplace, filters are all described inline). The description adds the semantics of the 'brand' parameter (that it is pre-validated and matched against the brand field) but does not add further detail on sort/count/marketplace/filters beyond what the schema already provides. At 80% coverage the baseline 3 is appropriate.

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 states a specific verb+resource ('List products under a specific Amazon brand') plus a distinctive mechanism (pre-validates via cached AI, filters keyword results by brand match, returns alternatives on no-match). It clearly distinguishes this from sibling tools like amzscout_search_products (keyword search) and amzscout_analyze_product (deep dive on a single product). The 'How to use' line gives the analytical framing that differentiates it from pure listing tools.

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 explains when to use it ('assess the brand's Amazon footprint') and how the tool behaves on no-match (returns alternative brands), which guides a caller to suggest alternatives. It does not explicitly name competing sibling tools for exclusion, but the brand-scoped mechanism plus the no-match fallback is clear enough context. Slightly short of truly explicit when-not-to-use guidance.

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