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

Annotations already mark readOnly and idempotent. The description adds that it is a POST request (non-modifying query), returns an array of records, and mentions API credit cost and speed, which are useful beyond 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?

Three brief paragraphs with clear sections: purpose, args, and return/guidance. No unnecessary words; efficient and well-organized.

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 simple inputs, existence of output schema, and annotations covering safety, the description fully addresses purpose, parameters, output, and usage guidance. No obvious gaps.

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 100% with descriptions for all parameters. The description restates most constraints but adds context like response format options and market code examples, adding marginal value.

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 fetches volume, CPC, YoY change, and seasonality for up to 1000 keywords via POST. It distinguishes from the sibling 'marketing_miner_get_search_volume' by explicitly recommending batch over looping.

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?

Explicitly advises to use this tool over calling the singular version in a loop, citing cost and speed. Provides key usage constraints (up to 1000 keywords, 2-80 chars, market codes) and formats.

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

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

The description adds significant behavioral context beyond the annotations: it explains pagination (limit/offset), the effect of with_keyword_data, return fields (total_available, has_more, next_offset), and the 'Omit for a general mix' for suggestions_type. No contradiction with 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?

The description is concisely structured with a main sentence followed by bullet points for arguments and return. Every sentence adds value; no extraneous words. The purpose is front-loaded.

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 the tool's moderate complexity (7 params, 2 required), high schema coverage, and presence of annotations and output description, the description is complete. It covers input semantics, output structure, and pagination, leaving no major gaps for an AI 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 coverage is 100%, but the description adds crucial semantics beyond the schema: it clarifies 'client-side window size' for limit, 'client-side offset into API results' for offset, the default behavior of with_keyword_data, and what 'Omit' means for suggestions_type. This provides valuable insight for proper invocation.

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 verb ('Retrieve'), resource ('related keyword suggestions'), and optional metrics. It explicitly lists specific use cases (topical research, FAQ mining, trend discovery) that distinguish it from sibling tools focused on search volume and website stats.

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 provides explicit use cases for the tool (e.g., 'Use for topical research, content-cluster ideation, FAQ mining'). While it does not explicitly state when not to use or name alternatives, the context signals (sibling tools) and the clear use cases give adequate guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. The description adds details on return fields and output format, which is useful but does not contradict annotations. It could mention rate limits or auth, but not required given read-only nature.

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 concise: three sentences covering purpose, arguments, return structure, and usage guidance. No fluff, front-loaded with the main action.

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?

The tool has 3 parameters with schema coverage 100% and an output schema exists. The description covers all necessary information: what it does, parameters, return fields, and when to use it versus siblings. It is complete.

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 100% with well-described parameters. The description adds value by explaining the purpose of response_format (human reading vs structured processing) and listing market codes explicitly. It also clarifies keyword length constraints, though schema already has them.

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 it fetches monthly search volume, CPC, year-over-year change, peak month, and seasonality for a single keyword. It uses a specific verb ('Fetch') and resource ('search volume' for a keyword), and distinguishes from the sibling batch tool.

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?

Explicitly says 'Use when you need volume/CPC/seasonality for ONE keyword. For multiple keywords, use marketing_miner_batch_search_volume.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context on the output structure: 'stats[] per result_type (organic, paid, ai_overviews, ...) plus totals.' This goes beyond the annotations, providing useful behavioral insight. No contradictions.

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 concise (four sentences) with front-loaded summary. It uses a clean 'Args' block for parameter details. Every sentence earns its place, no redundancy. Structured format aids quick parsing.

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 the output schema exists, the description adequately explains the return values (stats per result type plus totals). All parameters are explained with examples. The tool's complexity is moderate, and the description covers all necessary information for an agent to use effectively.

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 covers all 5 parameters with descriptions (100% coverage). The description adds value by providing concrete examples for 'target' (e.g., 'seznam.cz') and clarifies the usage of 'scheme' parameter. This enhances understanding beyond the 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?

The description clearly states it aggregates organic/paid traffic, keyword counts, and result-type breakdown for various URL granularities. It explicitly names the resource ('website stats') and the verb ('aggregate'). Sibling tools like batch search volume and keyword suggestions are distinct, so no confusion.

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 provides explicit use cases: 'competitor sizing, SEO audits, and SERP-feature distribution analysis.' This gives clear context on when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, but the use cases are sufficient for differentiation.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds behavioral details beyond these, such as the output structure (stats_range[] with date, result_type, estimated_traffic, and optional competitors), the maximum of 10 competitors, and the response format options. No contradictions.

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 concise, with clear sections for Args and Returns. It is front-loaded with the core purpose and every sentence is necessary. No fluff or repetition.

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 the complexity (7 parameters, optional output schema), the description is complete. It explains the purpose, each parameter's role (with additional context for competitors), the return structure, and typical use cases. The presence of an output schema reduces the need to detail return values, but the description still provides a useful summary.

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 high (86%), but the description adds meaningful context: it clarifies that competitors use the same 'type' as the primary target, and it explains the output structure. The schema already documents most parameters well, so the description provides incremental value without redundancy.

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 it provides 'Historical traffic time series (daily/weekly/monthly) for a target, with optional competitor comparison.' It uses a specific verb ('get') and resource ('time range'), differentiating it from sibling tools like 'get_website_stats' (likely single-point) and others.

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 explicitly states 'Use for trend analysis, year-over-year charts, and competitor benchmarking.' While it doesn't explicitly state when not to use this tool, the context implies it's for time-range data, distinguishing it from single-point alternatives. No explicit alternative tools are named, but the sibling list is available.

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