Get keyword metrics

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

Annotations already convey readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: requires write scope, uses project's own DataForSEO account, caches keywords for 12 hours, has a max_cost_cents best-effort guard, and details the cost model. This goes well beyond the annotations. Slight gap: doesn't state what the response/return format looks like or error behavior when cost exceeds guard.

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?

All sentences earn their place and the description is information-dense without bloat. It's moderately long but every clause adds operational value. Could be slightly more front-loaded with the primary action stated first, but the structure is effective and efficient.

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 7-parameter tool with no output schema and only 71% schema coverage, this description is thorough: it covers auth requirements, cost model, batching limits, caching behavior, cost guards, and clickstream implications. It effectively compensates for the missing schema coverage on fresh and include_clickstream semantics. Sophisticated enough for an agent to make intelligent cost-aware decisions.

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 71% with 5 of 7 parameters described. The description adds meaning to max_cost_cents (best-effort guard), estimate_only (free dry run), include_clickstream (doubles cost, refines volumes), and fresh. This meaningfully augments what the schema provides, especially around cost semantics which is the tool's differentiator.

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 states this tool fetches keyword metrics and costs money, with specific operational details. However, it doesn't use a crisp verb+resource framing (e.g., 'Fetch paid keyword metrics') and relies on the tool name for the basic action, though it does add substantial context about cost and caching that distinguishes its purpose.

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?

Excellent guidance: tells the agent to call with estimate_only first when cost matters, documents pricing via get_provider_rates, explains the 700-keyword batch limit, 12-hour cache behavior, and how clickstream-refined volumes double cost. It explicitly names get_provider_rates as an alternative resource and gives clear decision heuristics around cost sensitivity.

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