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 genuinely useful behavioral traits beyond that: the ~2 week data lag, newest-week-first row ordering, the parent_rollup aggregation semantics, and the truncated=false termination condition for paging. This is meaningful operational context that an agent cannot infer from the annotations or schema alone.

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?

Roughly 50 words carry a high density of information, with the core scope front-loaded ('organic search funnel per (ASIN, query) — impressions/clicks/cart-adds/purchases') before operational details. It is efficient, though it is structured as one long em-dash run-on sentence that slightly reduces scannability.

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 retrieval tool with no output schema, the description covers the essential envelope: data scope, metrics, aggregation mode, time-window semantics, data freshness, ordering, and the pagination loop. Remaining gaps are the interaction between weeks and the period enum, the expected format for asin, and semantics of the three undocumented parameters that appear to exist outside the visible properties.

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?

With only 22% schema description coverage, the description carries a heavy burden and partially compensates: it explains weeks ('counts back from the LATEST STORED week'), parent_rollup ('aggregates the product family'), and offset (paging until truncated=false). But notable gaps remain: asin, limit, and period (WEEK/MONTH/QUARTER) get no semantic guidance, and the description's 'parent_rollup' naming does not obviously match the schema's 'aggregate' boolean, which could confuse tool selection.

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 specifies a precise resource ('organic search funnel per (ASIN, query)') and the exact metrics returned ('impressions/clicks/cart-adds/purchases with shares'), which clearly distinguishes it from sponsored-search siblings. The main shortfall is that the verb is implicit ('Search Query Performance' is a noun phrase rather than 'Retrieves…'), and no sibling tool is named, though the 'organic' qualifier does most of the differentiation work.

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 gives strong how-to-use guidance: how weeks are counted ('counts back from the LATEST STORED week'), that data lags ~2 weeks, that rows are newest-week first, and the pagination recipe ('page with offset until truncated=false'). However, it never states when to prefer this tool over alternatives such as ppc_search_terms, ppc_query, or brand_top_search_terms, nor any exclusions — the usage context is implied by 'organic' rather than explicit.

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