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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with those. Beyond annotations, it adds substantial behavioral detail: what each section returns (e.g., 'target_gaps (proven-relevant terms with no serving keyword target)'), volume semantics ('amazon_sqp = TRUE market volume, estimated_from_rank with volume_band otherwise'), and even hints at suggested actions ('bid-down test candidates'). This gives the agent a rich understanding of the tool's output and implications, far exceeding the annotation baseline.

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 information-dense but efficiently structured. It opens with the critical 'start here' directive, then enumerates the five sections in a compact parenthetical list, includes volume semantics, and closes with pointers to alternative tools. Every sentence carries actionable information, and the length is justified by the tool's complexity and its role as an entry point. There is no fluff or repetition.

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?

Given the tool has 7 parameters, no output schema, and is positioned as the front door for keyword research, the description is remarkably complete. It explains the return structure ('every row with evidence + volume + a suggested next action'), defines volume metrics, and outlines the purpose of each section. It also directs to primitives for raw exploration. While it doesn't describe exact response formatting, the absence of an output schema makes the description's hints about row contents and section purposes sufficient for an agent to know what to expect. Nothing critical for calling the tool correctly is missing.

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 high (86%), so the baseline is 3. The description does not add explicit parameter semantics beyond what the schema already provides, though it indirectly relates sections to the 'sections' parameter and mentions profile_id's role in 'Amazon-recs and serving-target legs' only implicitly via 'profile_id' schema. It does not describe asins, limit, weeks, parent_asin, or seller_connection_id beyond the schema, so it adds minimal value for parameter understanding. This meets the baseline but doesn't exceed it.

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 identifies this tool as the primary entry point for keyword research on a product, using a specific verb ('start here') and resource ('any keyword question about a product'). It enumerates five distinct intent sections (target_gaps, discover, asin_targets, organic_strength, defend) with concrete outputs, and differentiates from siblings by naming the primitive tools (keyword_finder, keyword_research) that serve raw exploration. This makes it unmistakable what the tool does and how it differs from others.

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?

It explicitly states 'start here for any keyword question about a product (new or established)' and provides clear routing to alternatives: 'Primitives for raw exploration: keyword_finder (ASIN-anchored), keyword_research (term universe).' This tells the agent exactly when to use this tool versus its siblings, leaving no ambiguity about the decision boundary.

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