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

Annotations already declare readOnlyHint=true, so the safe-read profile is known. The description adds value by clarifying the tool is a pure data fetch with no AI analysis layer and enumerating the aggregation dimensions returned. However, it doesn't disclose rate-limit behavior, response size/pagination, or whether the data is live vs. cached snapshot. With readOnly annotations present, the bar is lower, but the behavioral disclosure of return-data shape is only partially covered.

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 well-structured: a purpose sentence, a clarifying caveat, then a bulleted 'How to use' section. Each sentence earns its place, and the analytical-application guidance is genuinely useful. Slightly verbose in the 'How to use' enumeration, but the density of practical value justifies the length. Not zero-waste like the TDQS-4.3 example, but appropriately organized.

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 data-fetch tool with readOnly annotation and 100% schema coverage, the description covers the core purpose, the interpretation guide, and the non-AI caveat. The complexity (nested filters object, 4 params, no output schema) is well-supported by the schema's detailed param descriptions. Gaps: no mention of the output structure/shape and no rate limits, but given the no-AI-nature disclosure and rich schema, completeness is strong.

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 every parameter (keyword, count, marketplace, filters) has its own schema description — the schema does the heavy lifting. The description adds marginal value by mentioning the aggregate dimensions (revenue concentration, brand spread) that help interpret the filter outputs, but it doesn't explain filter semantics beyond schema. Baseline 3 is correct given full schema coverage.

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 clearly states the verb+resource ('Market snapshot for an Amazon niche/keyword') and lists the specific computed outputs (top products, price/sales/revenue/review distributions, concentration, brand spread). It explicitly distinguishes from siblings by noting 'Pure data fetch (no AI analysis)' — differentiating it from amzscout_agent and amzscout_recommend_tool. The name and purpose align precisely.

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?

Provides a full 'How to use' section on when to apply the tool — judging niche attractiveness through demand concentration, price bands, review moats, and brand dominance. It also includes the exclusion note 'no AI analysis — reason over the returned data yourself,' which clarifies when NOT to reach for this vs. agent-based tools. This is exceptional guidance beyond just stating usage context.

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