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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the tool is safe. The description goes beyond by disclosing the cost in credits and the special free condition when no data exists – critical operational information not encoded in annotations. This transparency about costs is valuable for an AI agent managing budgets.

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 is extremely concise: a single sentence listing the returned metrics, followed by two short lines on cost and free condition. No wasted words; every sentence is necessary. It's also front-loaded with the key purpose.

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?

Given that the schema is complete (all parameters documented) and annotations cover safety, the description provides enough for an agent to call this tool correctly. It lacks some details like the exact format of the returned trend (e.g., historical dates), but the output is not critical for invocation. The tool is relatively simple (1 required param, no nested objects), so the description is adequate.

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?

The schema already covers all parameters with descriptions (100% coverage), so the description needs to add minimal value. However, the description does mention the return metrics and the trend, which complements the schema. It doesn't add specifics on the country parameter's format beyond what the schema provides, but the schema is already detailed.

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 the tool's purpose: it retrieves search volume, CPC, keyword difficulty, competition, search intent, and 12-month trend for a single keyword via Google DataForSEO Labs. This distinguishes it from sibling tools like 'bulk_keyword_overview' (which handles multiple keywords) and related tools like 'keyword_suggestions' that serve different functions.

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?

The description states the cost (1 credit) and free condition (when no data exists), which helps agents decide when to use this tool. However, it does not explicitly state when NOT to use it or mention alternatives like bulk_keyword_overview for multiple keywords. The sibling names suggest the distinction, but the description could be more explicit.

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