keyword_ideas

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

Annotations declare openWorldHint and non-read-only, but the description adds the important operational context that this is a DataForSEO Labs query and that in SANDBOX mode it returns dummy data with no payment — a cost/quota signal the annotations do not convey. It also describes the return envelope, which is valuable given no output schema. It does not say what happens in production regarding billing or rate limits, keeping it below 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?

Information is front-loaded: capability, cap, then routing alternatives, then return shape, then sandbox caveat. Each sentence carries distinct value, though the parenthetical vendor attribution and the enumerated return fields make it slightly denser than necessary.

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?

With no output schema, the description correctly compensates by naming the return keys (seed_keywords, total_available, ideas), and the sandbox note covers the paid-API concern. The remaining gap is production billing/credit behavior, which the sandbox hint only implies.

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 100%, so all three parameters are already fully documented, including language/location defaults and the payment-refusal behavior. The description only confirms the single-seed constraint ('words of one seed phrase'), adding little beyond the schema's maxItems: 1. Baseline 3 is appropriate.

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 states a specific verb, resource, and cap: keyword suggestions containing the words of one seed phrase, up to 25, with volume/CPC/competition metrics. It explicitly names the siblings it is not (keyword_metrics, keyword_difficulty), so an agent can route without opening either schema.

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 an explicit when-to-use ('find new phrases around one seed') and names two alternatives with the conditions that select them: keyword_metrics for exact volumes of known keywords, keyword_difficulty for ranking difficulty. Exclusions are stated, not inferred.

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