Research keywords

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

Annotations declare readOnlyHint=false (mutation possible), destructiveHint=false, and openWorldHint=true. The description meaningfully adds context beyond annotations: it requires API write scope, consumes the project's own paid DataForSEO account budget, caches results for 12 hours shared across API/UI, enforces one-seed-per-call, and introduces max_cost_cents as a best-effort guard. This is substantial behavioral disclosure that annotations couldn't 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?

The description packs substantial information into ~90 words and is front-loaded with the critical 'Requires API write scope' and paid-account caveat. However, it's a wall of sentences without any structuring (headers, lists, separators), and several facts (12-hour cache, clickstream cost, already_tracked) are concatenated in a way that makes them easy to skim past. The density is high but organization is flat.

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?

This is a complex, cost-bearing, stateful tool with 9 parameters, no output schema, and non-trivial caching and pricing behavior. The description covers the key operational risks: cost estimation flow, per-call seed constraint, cache sharing, clickstream surcharge, and rate-card source. Gaps remain (no explanation of mode differences, no description of what results look like given no output schema), but for a stateful paid tool the essential context is well covered.

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 56%, and several params (mode, fresh, include_clickstream, result_limit) lack schema descriptions beyond enums/types. The description compensates for some gaps but not all. It clarifies already_tracked (marks tracked keywords), explains estimate_only as a free dry run, positions max_cost_cents as a best-effort guard, and flags clickstream cost implications. However, the fresh flag and result_limit semantics are not explained in either schema or description.

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 opens by stating it's 'Paid keyword research' using a provider account, and combined with the tool name 'research_keywords' and input schema (mode/seed/result_limit), the purpose is reasonably clear. However, it never uses a crisp verb+resource sentence like 'Research keyword suggestions for a seed term' — the actual action is implied through schema context rather than stated. It doesn't explicitly distinguish itself from siblings like get_keyword_metrics, add_keywords, or run_rank_check, though the cost-estimate framing partially differentiates it.

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?

This is excellent. It explicitly instructs when to use estimate_only first for cost control, warns 'Send one seed per call', explains caching behavior shared with API and UI, flags that clickstream doubles cost, and notes the rate card comes from get_provider_rates. Coupled with the required project_id and seed parameters, the agent has clear operational guidance on how and when to invoke this tool vs free alternatives.

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