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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the SP+SD vs SB asymmetry (SB per-ASIN spend exists only in blended P&L), the sorting by spend, status classification, and the family_totals aggregation behavior. This is a meaningful addition, though it doesn't detail pagination or error cases.

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: first sentence states the core query and data grain, second explains the return sorting and status classification, third covers input modes and family_totals. Every sentence earns its place with no filler, and the most important scoping information is front-loaded.

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 tool with 10 optional parameters and no output schema, the description gives sufficient context to invoke it correctly: supported lookup modes, the family aggregation path, the unique SB data limitation, and status classification. It could mention pagination behavior (offset/next_offset) explicitly, but the schema provides parameter hints and the core usage scenarios are well covered.

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 70%, so the schema documents most parameters. The description adds conceptual meaning beyond the schema by explaining the relationship between asins and family_totals, and notes that profile_id is optional when the token has exactly one. It also clarifies that SB per-ASIN spend is only in blended P&L, which affects interpretation of results. Some uncovered parameters (start_date, end_date, period_days, offset) lack detailed semantics, but the description's added context compensates well.

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?

Description states a specific verb ('Query') and resource ('product/ASIN-level performance'), and distinguishes itself by noting the SP+SD/SB grain and the per-program split. It also contrasts with family aggregation via sibling ppc_product_family, helping an agent tell it apart from other ppc_* 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?

Provides explicit guidance on when to use single ASIN vs multiple ASINs vs SKU lookup, and references sibling tool ppc_product_family as a source for child ASINs. It also states the status classification behavior and the family_totals return when multiple ASINs are supplied, giving clear context for selection.

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