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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description goes beyond them by disclosing the billing side effect (cache misses trigger a billable lookup) and the 30-day cache window. It does not mention rate limits or latency, so it stops short of a 5.

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?

Three short sentences, front-loaded with the trigger, then the payload, then the cost caveat and the exclusion. Every sentence carries distinct information with no filler.

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?

An output schema exists, so return-field detail is not required, yet the description still summarizes what comes back. Combined with the billing disclosure, batch limits, country scoping and the ranking exclusion, an agent has everything needed to invoke it correctly.

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 100%, so the schema already documents terms, country and lang including the 50-item cap and code patterns. The description restates 'up to 50 terms in one country' and adds the useful point that a batch is scoped to a single country, but contributes little else beyond the schema.

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?

States a specific verb+resource (look up keyword search volume) and enumerates the returned metrics: monthly Google web-search volume, difficulty, CPC and competition. It also preempts a likely confusion by clarifying this is a demand proxy rather than app-store search counts, which separates it from the app/store siblings.

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?

Opens with an explicit trigger ('when someone asks how popular a keyword is or which keyword ideas are worth targeting') and closes with an exclusion ('Not for rankings'), routing the agent to get_keyword_rank. The batch constraint (up to 50 terms in one country) further bounds correct usage.

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