Research keywords

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing write-scope requirement, that billing runs through the project's own DataForSEO account, that results are cached 12 hours and shared with API/UI, and that clickstream refinement doubles cost. These are exactly the behavioral facts an agent needs before incurring spend.

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?

A dense six-sentence paragraph that front-loads the critical 'Requires API write scope' constraint and avoids filler. Most sentences earn their place, though the rate-card/get_provider_rates sentence is slightly tangential to the call itself.

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 costly write-scope tool with 9 parameters and no output schema, it covers billing, caching, cost guards, and the already_tracked return marker. The main gap is that it never outlines the shape of the returned keyword data, which the absent output schema leaves to the description.

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?

Descriptions cover roughly 56% of the 9 parameters, and the prose meaningfully enriches several: estimate_only as a free dry run, max_cost_cents as a best-effort guard, clickstream doubling provider cost, and one-seed-per-call. mode, fresh, and result_limit remain unexplained, so it compensates well but not fully.

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 name/title and the line 'Paid keyword research uses the project's own DataForSEO account' make clear this is a paid keyword-research operation against a seed. It references get_provider_rates as an adjacent tool, giving some differentiation, but it never plainly states what the tool produces (e.g., keyword/volume results), so it stops short of a crisp 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?

Offers concrete guidance: 'When cost matters, call with estimate_only first for a free dry run,' 'Send one seed per call,' and use max_cost_cents as a guard, plus a pointer to get_provider_rates for pricing. It gives clear context but doesn't explicitly contrast against siblings like estimated cost or suggestion-listing tools.

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