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

With annotations covering only safety (readOnlyHint, openWorldHint), the description adds substantial operational detail: per-call credit costs for the results page (3 live / 1 cached), 3 credits per autocomplete call returning suggestions, computed worst-case totals per expand mode, early termination once limit is reached, and that autocomplete is always live. It also caps expectations explicitly with 'Ideas only: no search volumes.' This is far beyond what the annotations convey.

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?

Purpose and output contents are front-loaded in the first two sentences, and the cost sentence, while long, is information-dense and decision-relevant rather than filler. The dense credit enumeration reads as one run-on but each figure maps to a distinct expand mode, so little is wasted.

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 an 8-parameter tool with no output schema and no schema-level descriptions, the description covers the essentials: what is returned (ideas with sources and intent labels), safety profile via annotations, cost model, caching, and the expand vocabulary. It falls short on the geo/language parameters (gl, hl, location, location_code) and on return-shape specifics beyond the per-idea fields.

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 0%, so the description carries the load, and it does document several parameters: expand's permitted values (none/questions/alphabet/all), fresh's meaning, limit's early-stop role, and Arabic seed support. But gl, hl, location, and location_code are left completely undocumented in both schema and description, so half the parameters remain opaque.

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 names a specific verb+resource ('keyword ideas for a seed keyword') and enumerates the sources (Google autocomplete, People Also Ask, related searches) plus the enrichment applied (cleaned, de-duplicated, intent labels). It clearly separates this from SERP-scraping siblings by producing ideas rather than results. What it lacks is an explicit contrast with the other keyword-adjacent sibling tools, so it stops short of a 5.

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 gives real decision context: expand modes with their credit ceilings let an agent trade breadth against cost, default is stated ('questions'), and the fresh flag's live-vs-cache behavior is explained. It does not, however, say when to prefer this tool over google_serp or ai_answers, so no explicit exclusions or alternative routing.

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