Citable — everything about one keyword, in one call

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

Annotations already declare readOnlyHint and openWorldHint. Description adds meaningful behavioral context: cost per call, non-charge on failure, merged source logic, and that both-sources is the strongest signal. Does not cover pagination behavior, but reads safe due to annotations.

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?

Five sentences, each carrying essential information: cost, core function, output content, source-strength semantics, and alternative routing. Front-loaded with the pricing and failure policy that matter for invocation decisions.

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 explains the return semantics well (merged rows, metrics, source indicator). It also addresses cost, failure, and sibling differentiation. Lacks an explicit note on default page size or output shape, but enough for a competent agent.

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 baseline 3 applies. Description reinforces 'seed' as the central input and hints that seed is the keyword topic, but adds no new parameter detail beyond schema.

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?

Description states a specific verb/resource: one seed returns keywords and questions with volume, CPC, difficulty, intent, merged from autocomplete and paid index. It distinguishes from sibling citable_keyword_ideas and citable_keyword_metrics by explicitly comparing cost and 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?

Gives explicit when-to-use guidance: use this combined call instead of citable_keyword_ideas plus citable_keyword_metrics; reach for those only when controlling exactly what you pay for. This directly routes an agent to the right choice among siblings.

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