AIsa Keyword Volume & Ads

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which annotations cannot 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?

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing information.

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?

For a zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret it correctly is missing.

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 tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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 concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling 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?

Explicit triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, 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?

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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?

For a read-only batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to correct invocation is missing.

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 the baseline is 3. The description adds real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded in 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?

States a specific verb and resource ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

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 sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative siblings.

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?

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for this tool.

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?

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly wasted.

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?

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed to call it correctly.

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?

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

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?

States a specific verb and resource ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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 names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

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 cover mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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 dense and front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better structured.

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 destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient for correct invocation.

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 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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 verb and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

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 gives explicit when-to-use and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little ambiguity.

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=false and openWorldHint, so the safety profile is covered. The description adds pricing context (usage-based billing, ~$0.012 default estimate), which is real value beyond the annotations, but discloses nothing about auth requirements or rate limits.

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 core sentence is a single front-loaded statement with no waste. The appended pricing block is templated boilerplate rather than prose, but it carries genuinely useful cost information rather than filler.

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 an output schema present, return values need no explanation, and annotations already carry the safety profile; the empty parameter set means there is little else to document. The one omission is that the description never tells the agent what to do with the returned industry_id, leaving the connection to the audience live endpoint implicit.

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 tool takes zero parameters and the input schema is an empty object, so there is nothing for the description to disambiguate. Per the rubric, zero parameters establish a baseline of 4.

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?

States a specific verb and resource: it returns the list of industries with their industry_id as supported by the Bing Ads Audience Estimation endpoint. It is clear what the tool yields, but it does not explicitly distinguish itself from lookup siblings such as get_dataforseo_keywords_bing_audience_job_functions, which serve the same reference-data role.

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 says what you receive but never states when to call it or what alternative exists. The natural use case, feeding industry_id values into post_dataforseo_keywords_bing_audience_live, is only hinted at through the phrase 'supported by Bing Ads Audience Estimation endpoint' and is left for the agent to infer.

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 readOnly, idempotent, non-destructive, and open-world behavior, so safety is covered by structured data. The description adds the pricing/billing context which is a useful but boilerplate operational note; it doesn't describe pagination or what the returned list looks like beyond the field name.

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 core sentence is front-loaded and clear, but it's buried by a large HTML-comment pricing block with a dollar estimate that is boilerplate and not specific to this tool's behavior. That padding reduces signal.

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 no-param lookup with an output schema and strong annotations, so not much is required. Still, the description could name the sibling distinction (industries) and mention that the result feeds the audience live endpoint; without that, completeness is adequate but not rich.

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?

There are zero parameters, so the baseline is 4. The description adds no parameter detail because there is none to add, which 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 (receive/list) and resource (job functions with job_function_id) for the Bing Ads Audience Estimation endpoint, which is clear. It doesn't proactively differentiate from siblings like get_dataforseo_keywords_bing_audience_industries, though those names make the distinction implicit.

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 says what you get back, not when to call this versus the industries sibling or when to use the live audience endpoint (post_dataforseo_keywords_bing_audience_live). No exclusion criteria or alternatives are stated.

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 cover readOnly/idempotent/openWorld, but the description adds substantial context: zero upstream cost, reference-data semantics, the 46 MB catalogue size warning, and the critical caveat that catalogues are not shared between families (same endpoint name can return a different list). These are non-obvious behaviors that materially change how an agent should call it.

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 purpose and alternative routing are front-loaded, which is good, but 'Free: upstream cost is 0' is stated twice in close succession, which is wasteful repetition. The injected pricing block further bloats the text. Content is useful but not tightly edited.

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?

An output schema exists, so return values need no explanation. Combined with the cost note, caching guidance, sibling differentiation, and the cross-family catalogue warning, nothing an agent needs to invoke this reference tool correctly is missing.

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 tool takes no parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies a zero-argument enumeration call, though it adds no parameter detail because none exists.

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 names a specific resource (the language list) and the exact consumer endpoint it serves (`post_dataforseo_keywords_bing_kw_for_url_live`), so an agent knows precisely what it returns and for which call. It explicitly distinguishes itself from the sibling `get_dataforseo_keywords_bing_languages`, which serves the rest of the Bing family.

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 states when to use it (to obtain valid language values for the URL endpoint), names the alternative for the rest of the Bing family, and gives a caching directive ('fetch once and keep what you need rather than calling it per request'). The warning to check the list belonging to the endpoint actually being called is explicit routing 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, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds a useful piece of non-annotation context: usage-based billing with a default estimate of $0.012 USD and a note that account pricing may differ. It adds nothing about auth or rate limits.

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?

Short and front-loaded: the returned resource appears in the first clause. The opening 'Using this endpoint you can get' is slightly wordy and the pricing block is raw HTML-comment markup buried in the text, but overall it is not padded.

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?

For a zero-parameter reference-data lookup with an output schema and full annotation coverage, the description of what is returned is sufficient. The only mild gap is the lack of any cue about how this list relates to the other locales/locations endpoints in the sibling set.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The empty schema and the description's statement that it returns the supported locations and languages are consistent.

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?

States a clear verb and resource: retrieves the full list of locations and languages. It also scopes the resource to 'Keyword Performance endpoints of Bing Keywords Data API', which partially separates it from the sibling languages/locations tools. However, it never explicitly names or contrasts those siblings, so the differentiation is left to inference.

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?

There is no explicit when-to-use, prerequisite, or alternative-selection guidance. In a sibling set that already contains get_dataforseo_keywords_bing_languages and get_dataforseo_keywords_bing_locations, the description does not say why an agent would pick this one over them. Usage is only implied by the 'Keyword Performance' scoping.

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, openWorldHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description's only added behavioral context is the usage-based billing note with a $0.012 estimate, which is genuinely useful but does not address freshness, caching, or result scope.

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 functional sentence is short, front-loaded, and free of waste. The appended pricing block is boilerplate but clearly demarcated and does not obscure the core statement.

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?

An output schema exists, so return-value explanation is unnecessary, and with no parameters the description is nearly sufficient. It still lacks any hint of how this language list relates to the parallel locales/locations lookup tools, leaving the agent to guess which reference endpoint to call.

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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond confirming the call is argument-free.

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?

States a clear verb (receive) and specific resource (list of languages supported by Bing Ads API), so an agent knows exactly what it returns. However, it offers no differentiation from the many sibling reference-list tools such as get_dataforseo_keywords_bing_kw_for_url_languages, get_dataforseo_keywords_bing_locations, or the various *_locales tools, which all return lookup lists.

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?

Usage is implied: as a no-parameter lookup of supported languages, an agent can infer it is called to validate or enumerate language codes before issuing a Bing keywords request. There is no explicit when/when-not guidance and no mention of which sibling lookup (locales, locations, kw_for_url_languages) to prefer for a given need.

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 readOnly, idempotent, openWorld, and non-destructive. The description adds only the usage-based billing note, which is useful but not behavioral in the invocation sense; it doesn't state response format or refresh cadence since output schema covers returns.

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 core sentence is efficient, but the large pricing comment block is injected boilerplate that interrupts flow and bloats the definition.

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?

Output schema exists, so return values needn't be explained, and there are no params. However, no differentiation from the many sibling list tools and no mention of how results relate to Bing Ads contexts leaves a small gap.

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?

Zero parameters, so baseline is 4. No param semantics needed and description doesn't need to compensate.

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?

States a specific verb and resource: receives the list of Bing Ads supported locations. This is clear and distinguishable from siblings like get_dataforseo_keywords_bing_languages, though it doesn't explicitly contrast with them.

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?

No guidance on when to use this versus the Bing languages tool or trends locations. An agent must infer that this lists geographic locations for Bing keyword data.

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 annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a billing signal (usage-based, ~$0.012 default estimate, account-specific pricing), which is genuinely useful context not present in structured fields, but says nothing about response shape, caching, or rate behavior.

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 functional sentence is front-loaded and concise. The injected pricing comment block is boilerplate that doesn't help tool selection, but it is short and clearly delineated.

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?

An output schema exists, so return values need no explanation, and a zero-parameter lookup tool has minimal documentation burden. The main gap is the lack of any hint about how to apply the returned locales in downstream Search Volume History calls.

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?

Zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify, and schema coverage is reported at 100%.

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 ('receive the list') and resource ('locations and languages supported by Bing Search Volume History endpoint'), which is narrower than the generic sibling tools get_dataforseo_keywords_bing_languages and get_dataforseo_keywords_bing_locations. It's clear but largely restates the title, and it doesn't explicitly distinguish itself from those near-identical siblings beyond the endpoint qualifier.

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?

No guidance on when to call this versus get_dataforseo_keywords_bing_languages, get_dataforseo_keywords_bing_locations, or get_dataforseo_keywords_bing_kw_performance_locales, all of which sound like locale/location lookups. The agent must infer that this one is scoped to the Search Volume History endpoint specifically.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: usage-based billing with a default request estimate of $0.012 and a caveat that account-specific pricing and final settlement may differ. It does not discuss rate limits or auth, but the cost disclosure is a meaningful addition beyond structured fields.

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 content is short and front-loaded: purpose first, then a clearly delimited pricing note. The pricing block is boilerplate but relevant to invocation planning. The stray leading zero-width character is a minor formatting blemish, and the pricing text is slightly verbose for what it conveys.

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?

An output schema exists, so return structure need not be described. With annotations covering the safety profile and no parameters to explain, the description only needs to establish purpose and cost, which it does. The one remaining gap is sibling differentiation, which matters here given the many parallel locale/language listers.

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 tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

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 and resource: retrieve the full list of locations and languages supported in the DataForSEO Clickstream Data API. The name and title reinforce the same scope. However, it does not distinguish this clickstream locales endpoint from sibling locale/language listers such as get_dataforseo_keywords_bing_languages, bing_locations, or get_dataforseo_keywords_trends_locations, so an agent must infer the API-surface distinction from the tool name alone.

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 phrase 'using this endpoint you can get...' implies the tool is a reference/dimension lookup, but there is no explicit statement of when to call it versus the many sibling lister tools. No prerequisites, no exclusions, and no named alternatives are given despite a crowded sibling set.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only a generic price disclaimer, not operational behavior, auth needs, rate limits, or error handling. It does not contradict annotations, but it adds almost no useful behavioral context.

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 text is short but consists entirely of boilerplate pricing markup that does not help an agent select or invoke the tool. It is not front-loaded with purpose or usage information.

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?

Despite having an output schema and rich annotations, the description fails to tell the agent what data is fetched, what the return represents, or how this fetch tool relates to its sibling submit tool. For a fetch-by-id operation in a large family, the definition is contextually inadequate.

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%, and the single id parameter is fully documented in the schema with format, example, and 30-day validity. The description adds nothing about parameters, so the baseline of 3 applies when the schema does the heavy lifting.

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 contains only a pricing disclaimer and never states what the tool does. The title alone carries the purpose, but the description itself provides no verb, resource, or scope. This is a missing 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?

No guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or sibling tools like post_dataforseo_keywords_gads_ad_traffic_submit.

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 cover read-only, idempotent, open-world, non-destructive semantics, so the bar is lower. The description adds genuine behavioral context beyond them: the monthly update cadence, the data-lag consequence (falling back to an earlier month), and a billing note (usage-based, ~$0.012 estimate).

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 core purpose is front-loaded in the first sentence, and the October/September example usefully illustrates the lag concept. The trailing pricing block and a stray leading whitespace character add minor noise but do not obscure the meaning.

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 zero parameters and an output schema present, the description need not describe return values. It supplies the conceptual model (data freshness/lag) an agent needs to interpret the result, leaving only explicit routing guidance as a gap.

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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing parameter-wise for the description to document or compensate for.

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 purpose: determining whether Google has refreshed Google Ads keyword data for the prior month. It conveys the verb (check/learn status) and resource (GAds keyword data freshness) clearly. It does not explicitly differentiate itself from sibling freshness/inventory tools, but the concept is unambiguous.

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?

Usage is only implied — an agent infers it should call this before relying on GAds keyword data to know how current it is. There is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling endpoints.

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 annotations already declare the full safety profile (readOnly, idempotent, non-destructive, openWorld), so the description doesn't need to restate that. It adds genuinely new context in the usage-based billing note ($0.012 estimate), which is useful for an agent weighing cost, but the 'tasks array' sentence merely restates what the output schema already provides.

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 first two sentences largely restate each other (you receive the list of categories / you receive JSON with the categories), and the pricing HTML comment block adds noise. The core information is front-loaded, but the redundancy keeps it from being tight.

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?

For a no-parameter read-only listing tool with a full output schema and complete annotations, the description covers what's needed. Only the missing when-to-use routing against the large sibling set is a gap.

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 tool takes zero parameters, which is the baseline-4 case. There is nothing for the description to clarify beyond confirming the call needs no input.

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 and resource: it returns the list of categories supported by the Google Trends API. This is clear enough to distinguish from the Bing/GAds/Clickstream category siblings, though it never explicitly contrasts itself with close siblings like get_dataforseo_keywords_trends_locations or list_categories.

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?

There is no guidance on when to call this versus the many sibling category/list tools, nor any prerequisites or exclusions. The description only states what the response contains, leaving the agent to infer the use case.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds genuine value beyond that with cost disclosure (usage-based billing, ~$0.012 default estimate) and the country-level minimum-scope restriction, but nothing about pagination, result shape, or freshness.

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 purpose is front-loaded and the body is short, with the geographic-scope caveat placed after the core statement. The only filler is the roundabout 'You will receive ... by calling this API' construction, which could be a single directive verb.

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?

For a parameterless read-only lookup with an output schema already describing return values, the description covers purpose, a scope constraint, and cost. An agent has what it needs to call it correctly; only the sibling-routing information is absent.

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 tool takes zero parameters, so per the baseline the schema carries the full burden and the description need contribute nothing. The mention of filtering 'by country' is mildly ambiguous given the empty schema, but it reads as a downstream-task note rather than a claim of an existing parameter, so it does not materially mislead.

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 resource ('the list of DataForSEO Trends locations') retrieved by the tool, which is clearly distinct from sibling list tools in the naming. However, it never explicitly contrasts itself with near siblings like get_dataforseo_keywords_bing_locations, so an agent must infer the 'Trends' scope distinction from the tool name alone.

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 hints at downstream usage ('you can filter the list of locations by country when setting a task') and states the country-level scope floor, which is an implied constraint on how the result can be used. But there is no explicit when-to-use vs. when-not, and no routing to alternative location-list tools.

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 readOnly/idempotent/non-destructive and openWorld, so the safety profile is fully covered. The description adds a genuinely useful behavioral fact beyond the annotations: the usage-based cost estimate (~$0.012). However, it says nothing further about the nature of the response or edge cases; with annotations carrying the load, this is adequate but not rich.

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 core purpose is one front-loaded sentence, and the pricing note is confined to a clearly delimited comment block. Minor redundancy (the endpoint is named twice) but overall tight for a simple tool.

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?

An output schema exists, so return values need not be described. For a zero-parameter reference endpoint with full annotation coverage, the description supplies everything an agent needs to invoke it correctly; only explicit routing against siblings is absent.

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 has zero parameters, so the baseline is 4. There are no parameter semantics to document and the description correctly implies a parameterless lookup.

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?

States a specific verb+resource: fetching the full list of supported languages for the Google Categories for Keywords endpoint. An agent can tell it is a static reference list tied to that one endpoint, though the description never explicitly contrasts it with siblings like post_dataforseo_labs_google_categories_for_kw_live.

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?

Usage is implied by the name (discover supported language codes before calling the categories-for-keywords endpoint), but the description states no when-to-use, no prerequisite, and no alternative. Nothing tells the agent when this lookup is or isn't needed.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description's only contribution is the cost disclosure ($0.04 USD estimated, usage-based, account-specific) — genuinely useful and not present in the annotations — but it says nothing about result volume, latency, or what 'broad match' actually returns.

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 text is short, which is superficially good, but it is short because it omits the essential content rather than because it is efficient. The markup comments and repeated price hedging ('not a fixed price', 'may differ') consume the entire budget that should have described the tool.

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?

An output schema exists, so return values need not be explained, but that does not excuse the total absence of purpose, usage, and parameter meaning for a two-parameter tool. As written, an agent has no basis for choosing or correctly invoking this tool other than its name.

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 0% and the description supplies no information about either parameter. The required 'phrase' argument and the 'database' argument (its allowed values, e.g. which Semrush regional/global databases are valid) are completely undocumented in both places, which is exactly the case where the description must compensate.

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 never states what the tool does — not a verb, not a resource, not even the word 'keyword'. It consists solely of a pricing/billing block wrapped in HTML comments, so an agent cannot tell from the description that this retrieves Semrush broad-match keyword data, nor how it differs from siblings like get_semrush_question_keywords or get_semrush_keyword_overview.

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?

There is no when-to-use, when-not-to-use, or alternative-selection guidance of any kind. With ~55 sibling keyword tools available, the absence of any routing hint leaves selection entirely to name-guessing.

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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description's only added value is a usage-based billing note ($0.02 default estimate), which is genuine cost context not present in annotations, but nothing is said about scope, database semantics, or result limits.

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?

It is short, but the content is an HTML-comment-wrapped billing banner rather than front-loaded task information. Brevity here reflects missing content, not conciseness.

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?

An output schema exists so return values need not be explained, but for a two-parameter query tool with 0% schema coverage the description supplies nothing an agent needs to invoke it correctly – no purpose, no parameter meaning, no usage context.

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 0% for two required parameters (domain, database). With no enums and no schema docs, the description must compensate, and it says nothing about expected domain format or valid database values.

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 contains zero functional content – it is entirely a pricing banner. The only signal about what the tool does comes from the tool name itself, and there is no differentiation from siblings like get_semrush_url_organic_keywords or get_semrush_organic_competitors.

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?

No when-to-use guidance, no alternatives named, no prerequisites. An agent has no basis for choosing this over the many other Semrush/DataForSEO keyword tools listed as siblings.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add genuinely non-annotation information: a usage-based cost estimate (~$0.04/request) and a warning that final settlement may differ, which is useful behavioral context for a paid API call. It still omits rate limits, result shape, and any pagination behavior.

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 text is short and has no filler sentences, and the pricing caveat is front-loaded. However, its brevity is achieved by omitting the core purpose rather than by tight editing, so conciseness here is partly a symptom of incompleteness.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. But for a two-parameter, cost-incurring API call, the complete absence of purpose and parameter documentation leaves the definition too thin for an agent to invoke confidently.

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 0% and the description supplies no parameter information at all. 'domain' is largely self-evident, but 'database' (e.g. which regional Semrush database) is entirely undefined in both the schema and the description, leaving a required parameter ambiguous.

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 contains only a pricing/billing boilerplate block and never states what the tool does. The agent must infer the purpose entirely from the name/title 'Domain Paid Keywords', and the description does nothing to distinguish this from sibling get_semrush_domain_organic_keywords.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from this text why it would pick paid keywords over organic keywords (get_semrush_domain_organic_keywords) or the domain overview.

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, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is covered elsewhere. The description's sole contribution is cost transparency (usage-based billing, ~$0.005/request, account-specific settlement), which is genuinely useful but says nothing about data source behavior, batching limits implied by x-aisa-maxItems=20, or result freshness.

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 text is short, but it is boilerplate wrapped in HTML comment markers that consumes the entire description while conveying none of the tool's functional purpose. Brevity here stems from omission, not from disciplined editing.

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?

Although an output schema and rich annotations exist, the description omits everything an agent needs to select this tool over its many keyword-data siblings and to supply 'phrase'/'database' correctly. Pricing alone is insufficient for a 2-parameter, high-sibling-ambiguity tool.

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 0% for both parameters, and the description adds nothing about 'phrase' (multi-value, delimiter ';', max 20 items) or 'database' (which SEMrush database/region to query). With zero coverage on both sides, the agent is left to guess parameter meaning entirely.

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 never states what the tool does. It contains only a billing/pricing notice ('Usage-based billing; Default request estimate: $0.005 USD'), so an agent cannot tell this retrieves SEMrush keyword difficulty scores, nor distinguish it from siblings like get_semrush_keyword_overview or the DataForSEO difficulty tools.

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?

There is no when-to-use guidance, no prerequisites, and no reference to alternatives such as post_dataforseo_labs_google_bulk_keyword_difficulty_live or get_semrush_keyword_overview. The only conditional text is about pricing, not invocation context.

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, non-destructive and open-world behavior, so the safety profile is covered. The only added behavior is the per-request price ($0.001 USD per successful request), which is genuinely useful cost context beyond the annotations, but it is the sole non-template content.

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 blurb is short but consists entirely of an HTML-comment pricing artifact that does not earn its place for tool selection. It is not front-loaded with any purpose statement.

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?

Although an output schema and annotations exist, the description supplies zero information on what the tool returns or when to call it. For a keyword-lookup tool surrounded by dozens of similar siblings, this is completely inadequate for correct selection.

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 0% for both parameters, so the description must compensate and instead says nothing about the required 'phrase' or the 'database' default. There is no hint about accepted phrase format or database values such as 'us'.

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 contains only a pricing banner and never states what the tool does. Nothing indicates it returns Semrush keyword overview metrics for a phrase, nor distinguishes it from siblings like get_semrush_keyword_difficulty or post_dataforseo_labs_google_keyword_overview_live.

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?

There is no when-to-use guidance, no mention of alternatives, and no conditions for selecting this tool over the many keyword-data siblings. The agent is left to infer everything from the tool name.

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, openWorldHint and destructiveHint=false, so safety is covered. The description's only contribution is cost context ($0.08 estimate, usage-based billing, settlement may differ), which is genuinely useful but says nothing about what the call returns, its latency, or its external-data dependencies.

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?

It is short, but brevity here reflects omission rather than conciseness. The only content is a boilerplate pricing banner wrapped in HTML comments, which wastes the entire description budget on non-purpose information.

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?

Although an output schema exists (so return values need not be explained), the tool has a required parameter at 0% schema coverage and no stated purpose. For a 2-parameter keyword lookup with many near-identical siblings, the description is completely inadequate for correct selection or invocation.

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 0% for both parameters ('phrase' and 'database'), and the description adds no meaning whatsoever about what 'phrase' should contain or what values 'database' accepts. With two undocumented parameters, the description fails to compensate for the gap.

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 never states what the tool does. It contains only an HTML-wrapped pricing notice ('Usage-based billing; Default request estimate: $0.08 USD'). Nothing identifies the resource (question keywords) or the verb (fetch), so an agent cannot distinguish it from the dozens of sibling keyword tools.

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?

There is no when-to-use guidance, no conditions, and no mention of alternatives such as get_semrush_broad_match_keywords or get_semrush_keyword_overview. The text provides zero routing information.

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 readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds only a cost estimate (~$0.02, not fixed), which is genuinely useful context for a paid third-party API, but it omits auth needs, rate limits, and result shape.

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 text is short, but every line is irrelevant boilerplate about pricing rather than tool purpose. Brevity here reflects under-specification, not conciseness.

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?

Even granting that the output schema covers return values and annotations cover safety, the description omits the one thing only it can provide: what the tool returns and how it differs from its Semrush siblings. The definition is functionally incomplete.

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?

Two required parameters (url, database) with 0% schema description coverage, and the description supplies no meaning, format, or valid values for either. For a required 'database' field this is a real gap, as the agent cannot know whether it expects 'us', 'google.com', or a locale code.

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 never states what the tool does. It contains only a pricing banner, so the agent must infer purpose from the name alone, and nothing distinguishes it from sibling get_semrush_domain_organic_keywords.

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?

No guidance about when to use this tool versus the many sibling alternatives (domain organic keywords, organic competitors, Ahrefs/DataForSEO equivalents). The only conditional text is about billing, not usage.

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 cover the operational profile (readOnly, idempotent, openWorld, non-destructive). The description's only additive behavioral content is the billing model — usage-based, ~$0.075 per similarweb_credit — which is genuinely useful cost context. However, it discloses nothing about data freshness, result size, or what the returned keyword records contain.

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?

It is short, but the brevity is under-specification rather than efficiency: the entire body is boilerplate pricing with zero functional content. The one useful sentence (per-credit rate) is buried in a compliance block rather than front-loaded as tool guidance.

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?

An output schema exists, so return values need not be described, but for a 9-parameter, 5-required tool with 11% schema coverage and a crowded sibling namespace, the description supplies no purpose, no usage routing, and no parameter semantics — it is functionally empty.

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 11% (only 'country' is documented), and there are 9 parameters including five required ones (domain, start_date, end_date, granularity, limit). The description explains none of them — no date format, no domain input convention, no meaning for granularity or web_source — leaving the agent to guess.

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 contains no statement of what the tool does — it is entirely a pricing/billing notice. An agent must infer from the name and title alone that this retrieves SimilarWeb keyword data, and it cannot distinguish this from the many get_semrush_* and get_dataforseo_keywords_* siblings.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The pricing block states cost but not the conditions under which this tool should be chosen over the adjacent get_similarweb_landing_pages or the Semrush/DataForSEO keyword tools.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered without the description. The only added behavioral information is the usage-based pricing estimate ($0.075 USD per similarweb_credit), which is genuinely useful context not present in annotations, but it says nothing about data scope, rate limits, or result semantics.

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 text is short, but every sentence is off-topic boilerplate about billing rather than the tool's function. It is structurally compact yet fails the 'every sentence earns its place' test because no sentence helps an agent invoke the tool correctly.

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?

Although an output schema exists (so return values need not be explained), the description omits the tool's purpose, usage context, and parameter meaning for a 10-parameter tool with 4 required fields. For a complex, expensive, open-world query tool, this is completely inadequate.

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 only 10% across 10 parameters, so the description must compensate — and it does not. Parameters like domain, start_date/end_date formats, limit, offset, traffic_source, web_source, granularity and main_domain_only are left completely undocumented in both the schema and the 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 contains only auto-generated pricing boilerplate and never states what the tool does. Nothing in it indicates that the tool retrieves SimilarWeb landing page data, what a 'landing page' record contains, or how it differs from siblings like get_similarweb_keywords. An agent reading only the description would have no idea what this tool returns.

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?

There is no usage guidance of any kind — no when-to-use, no when-not-to-use, and no routing to the many sibling tools (get_similarweb_keywords, get_semrush_url_organic_keywords, etc.). The description gives the agent no basis for choosing this tool over alternatives.

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 declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=true, yet the description frames the endpoint purely as data retrieval ('provides', 'returns'), leaving that tension unaddressed. The only behavioral value added is the usage-based billing note ($0.09 estimate); it says nothing about auth requirements, rate limits, or what the non-idempotent/destructive flags imply for the caller.

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 substantive description is two front-loaded sentences with no filler, and the pricing block is boilerplate but relevant to cost. Structure is efficient; only the pricing fragment slightly dilutes focus.

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?

An output schema exists, so return-value explanation (which the description duplicates) is not strictly required. What is missing for a 1-param, zero-required, nested-object tool is usage context: when to call it, and that the helper endpoints supply valid industry/job_function ids. Adequate but with clear 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?

The top-level 'body' parameter has no schema description (coverage 0%) and the description adds no parameter-level meaning beyond the vague phrase 'specified targeting criteria'. It never explains that the body is a targeting object, how the mutually exclusive location selectors work, or the required-ness of location — all of which the agent must infer from nested schema text.

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 and resource: it 'provides estimated audience size for an ad campaign based on specified targeting criteria' and returns totals, suggested bid/budget and engagement metrics. That is clear enough to identify the tool, but it offers no differentiation from the many sibling keyword/volume endpoints (e.g. post_dataforseo_keywords_bing_search_volume_live), which an agent must disambiguate by name alone.

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?

There is no guidance on when to use this endpoint versus alternatives, and no mention of prerequisites even though the schema implies at least one location selector is required. The two companion lookup endpoints that provide valid industry/job_function ids (get_dataforseo_keywords_bing_audience_industries, ..._job_functions) are never referenced, so the agent gets no routing help.

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 the write/read profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description carries less burden. It adds genuinely useful operational context — the 200-keyword input cap, the 3000-suggestion output cap, and usage-based billing (~$0.09 estimate) — but it does not explain why this is flagged destructive or what auth is needed, leaving a notable gap.

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?

Two tight sentences front-load the purpose and limits, followed by a clearly delimited pricing block. A stray zero-width character and the boilerplate pricing comment are minor blemishes but the prose is efficient.

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?

An output schema exists, so return-value explanation is not required, and the description covers input/output caps and billing. However, for a billed, non-idempotent POST endpoint with a 0%-described top-level param, it stops short of clarifying the destructive/one-shot semantics or how the array body is structured.

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 top-level schema has only the single 'body' parameter with no description (0% coverage), but the nested object properties are documented in exhaustive detail (device, sort_by, date ranges, location/language options, negative keywords). The description only restates the 200-keyword limit that the schema already gives and adds the 3000-suggestion cap, so it adds marginal value over structured data.

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?

States a specific verb and resource: it selects relevant keywords for the seed keywords supplied, sourced from Bing Ads, returning up to 3000 suggestions. This differentiates it from siblings like kw_for_url_live and kw_for_site_live by implying the input is keywords rather than a URL or site, though it never names those alternatives explicitly.

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?

Usage is implied — you call it to expand seed keywords into Bing-suggested related keywords — but there is no explicit when-to-use guidance, no mention of when to prefer this over kw_for_url_live, gads_kw_for_keywords_live, or the Labs keyword-suggestion tools, and no prerequisites stated.

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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds useful behavior beyond that (the 3000-result cap, the pricing/usage-based billing note, and the cost estimate), but it says nothing about the live-call semantics, latency, or rate/limits, and it frames the call purely as data retrieval in a way that sits uneasily with destructiveHint=true.

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 prose is a single front-loaded sentence that delivers the return payload and the result cap immediately, followed by a clearly demarcated pricing block. Every sentence earns its place, though the pricing boilerplate is generic rather than tool-specific.

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?

An output schema exists, so return-value explanation is technically unnecessary and the description is not penalized for the metric details it repeats. However, for a live POST endpoint with a deeply nested body schema and dozens of near-identical Bing/Google Ads siblings, the definition never routes the agent to the correct variant, leaving a meaningful selection gap.

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?

Top-level schema coverage is 0% (the single body array carries no description), but the nested oneOf properties are documented extensively in the schema itself — target, device, date_from/date_to, location_code/name/coordinate, sort_by, keywords_negative. The description adds no parameter-level meaning at all, so it neither compensates for the top-level gap nor surpasses what the nested schema already provides.

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 and resource: it returns keywords relevant to a specified URL, and it enumerates the returned metrics (search volume, 24-month trend, CPC, competition) and the 3000-keyword cap. That distinguishes it in scope from keyword-seed siblings, but it never names an alternative and never mentions 'Bing' in the body text, so an agent must rely on the tool name to separate it from post_dataforseo_keywords_gads_kw_for_site_live.

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?

There is no when-to-use versus when-not-to-use guidance and no named alternative. The phrase 'specified URL' only weakly implies the input shape, and with close siblings like kw_for_keywords and kw_for_url present, the absence of routing guidance is a real gap.

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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-annotation context: the DataForSEO envelope layout (tasks[0].result vs tasks[0].status_code) and the critical detail that a rejected request still returns HTTP 200, which prevents false success detection.

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?

Front-loaded with the core purpose, then routing, then envelope/error semantics – each sentence earns its place. Slightly dense, and the boilerplate pricing comment sits outside the descriptive value, but nothing is redundant.

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?

For a single-parameter POST task submission with an output schema already present, the description covers routing, the alternative endpoints, and the response envelope, so return-value explanation is not needed. The only gap is the language_code/language_name selection rule, which is left entirely to the schema.

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?

Adds meaning to two parameters the schema names but does not explain functionally: 'exclude_brands drops brand terms, language_code scopes it'. However, with 0% reported schema description coverage, the description would need to carry more (e.g. the language_code/language_name mutual-requirement is left to the schema), so it only partially compensates.

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?

States a specific verb and resource ('Suggests Bing keywords for one page target') and crisply distinguishes the input mode: it reads the page itself rather than a seed list. It also names the sibling it is not (post_dataforseo_keywords_bing_kw_for_keywords_live) and the submit/fetch twins, so an agent can route without opening another 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?

Explicit trigger ('Use it when you have a URL and no keyword list yet') and explicit hand-off ('once you have seeds, ...expands them'), plus a note that the async twins do the same work at the same price for batches too large to wait on. When-to-use, when-to-use-something-else, and the cost-equivalence caveat are all present.

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=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description does add real behavioral context beyond structured fields: data is aggregated over the last month, and the pricing block discloses usage-based billing with a ~$0.09 per-request estimate. It still does not explain that each invocation re-triggers billing with no caching, which is the natural implication of the non-idempotent annotation.

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 core is two tight sentences with the aggregation window and device breakdown front-loaded. The HTML-comment pricing block and a stray zero-width character add some noise, but the substantive content is efficient and free of filler.

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?

An output schema exists, so return values need not be explained, and the description covers the essence of the data produced. However, for a paid live POST endpoint with 0 required top-level parameters and numerous selectable location/language fields, the description omits any prerequisite guidance and gives no hint that separate calls are needed to discover valid locales. Adequate but with visible 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?

The schema itself documents every field exhaustively (match types, device values, keyword limits, language/location alternatives, example coordinate format), so the schema carries the parameter burden. The description only echoes that match type, location, and language affect results without adding syntax or defaults beyond the schema. A baseline 3 is appropriate given the schema's thorough coverage.

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 and resource: it returns keyword performance stats (ad position, clicks, impressions) aggregated over the last month for a keyword group, broken down by match type, location, language, and device. That is clear and concrete. It does not, however, distinguish this tool from the many similarly named siblings such as post_dataforseo_keywords_bing_search_volume_live or post_dataforseo_keywords_bing_kw_for_keywords_live, so an agent cannot route between them from the text alone.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives. The agent is not told how this differs from search_volume, kw_for_keywords, or the Google Ads equivalents, nor when a live call is preferable. It merely describes the output, leaving tool selection to inference.

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 pricing note adds real behavioral context (usage-based billing, ~$0.09 default estimate) that annotations do not cover. However, the description says nothing about the non-idempotent, task-creating nature implied by readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the mutation/billing semantics remain only partially surfaced.

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?

One front-loaded sentence stating the returned data, followed by a compact pricing block. No filler, though the two halves (capability + price) are only loosely connected.

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?

An output schema exists so return values need not be explained, and the capability sentence covers the payload. But for a billable POST task endpoint with no annotations-level safety explanation and no usage routing, an agent still lacks the operational context needed to invoke it confidently.

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 description adds zero parameter meaning: it never mentions keywords, language, location, date ranges or sorting. Although the nested item schema is richly documented, the top-level schema coverage is reported at 0%, and the description does not compensate with any framing of the request body.

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?

States a specific verb and resource: this endpoint returns search volume for the last month, trend up to 24 months, CPC and competition values. The Bing scope is carried in the tool name, but the description itself does not distinguish this from similar siblings like gads_search_volume_live or clickstream_search_volume_live.

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?

There is no guidance on when to use this tool versus the many sibling search-volume endpoints (Bing vs Gads vs Clickstream), nor on prerequisites such as language/location requirements. The reader must infer usage entirely from the tool name.

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 the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description's job is to add context. It does add genuinely useful context beyond annotations — the 1000-keyword batch limit, 12-month history depth, and a default billing estimate of $0.09 — but it does not explain the destructive/non-idempotent behavior, auth needs, or rate limits.

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 core purpose is front-loaded in the first sentence, which is good, but the text opens with zero-width junk characters and carries a boilerplate pricing comment block. Roughly half the payload is non-descriptive scaffolding.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. Still, for an endpoint with a dozen confusingly similar siblings and an untyped body array, the description omits the routing rationale and request-shape essentials an agent needs to call it correctly.

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?

Top-level schema description coverage is 0%: the sole 'body' array parameter has no description of its own, and the nested oneOf does not mark keywords/location as required even though the endpoint needs them. The description only restates the 1000-keyword limit and vaguely alludes to 'location and language parameters', without explaining the body array structure or the location_code vs location_name choice.

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 names a specific resource ('Bulk Clickstream Search Volume endpoint of DataForSEO Keywords Data API') and states its scope: clickstream search volume for up to 1000 keywords in one Live request with up to 12 months of history. However, it never distinguishes itself from near-identical siblings such as post_dataforseo_keywords_clickstream_search_volume_live or post_dataforseo_keywords_clickstream_global_volume_live, so an agent still cannot tell them apart.

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?

No when-to-use guidance is given: nothing says when to prefer bulk over the single/global clickstream variants, or what prerequisites exist. The 1000-keyword cap and 12-month history are capacity facts, not selection 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 the write/billing profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description usefully adds beyond them: the 1000-keyword-per-request limit, that results include geographical distribution across all locations, and an account-specific usage-based price estimate (~$0.09 USD, explicitly not fixed). Cost and batch-size behavior are exactly the kind of context annotations cannot express. It does not cover rate limits or failure modes, so not 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?

Two purpose sentences followed by a fenced pricing note; the purpose is front-loaded and nothing is padded. The leading zero-width/whitespace characters and the raw `<!-- aisa-pricing -->` comment delimiters are visible formatting cruft that a cleaner definition would omit, but the content itself is tight.

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 an output schema present, return values need no explanation, and annotations cover the safety/mutation profile, so the remaining burden is scope, limits, and cost — all three are stated. The gap is routing: nothing tells an agent why to pick this clickstream global endpoint rather than its search_volume/bulk_volume siblings, which is a meaningful omission in a 60-tool namespace.

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 top-level `body` parameter has no description (0% schema coverage at that level), so the description must compensate, and it only partially does — it conveys the 1000-keyword limit and Live-request context. It says nothing about the array-of-task-objects shape, the optional `tag`, or the fact that keywords are lowercased and symbol-restricted, all of which live in the nested schema rather than the description. Baseline 3 for a schema that documents its nested fields well despite the flat coverage metric.

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 names a specific resource (Clickstream Global Search Volume endpoint of the DataForSEO Keywords Data API) and states the concrete payload: clickstream-based search volume for up to 1000 keywords in one Live request. That is a clear verb+resource statement. It stops short of distinguishing itself from near-identical siblings such as post_dataforseo_keywords_clickstream_search_volume_live and post_dataforseo_keywords_clickstream_bulk_volume_live, which an agent cannot disambiguate from this text alone.

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 only usage signal is 'in a single Live request' and the 1000-keyword ceiling. There is no statement of when to prefer this tool over the clickstream search-volume variant, the bulk-volume variant, or the Bing/GAds search-volume tools in the sibling list. No prerequisites, no exclusions, no routing 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 the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the bar is low. The description adds only cost context (usage-based billing, ~$0.09 default estimate), which is genuinely useful but is the sole behavioral detail; it says nothing about rate limits, async task handling, or what the 'live' POST actually triggers.

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?

Very short, but that shortness reflects absent content rather than tight writing. The only sentence present is the pricing disclaimer, which is useful but leaves the definition with no purpose statement to front-load.

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?

An output schema exists, so return values need not be explained, but the description still omits that the payload is an array of task objects, that keywords/language/location are effectively required despite 'required: []', and that this is a paid live task submission. For a billing-relevant, open-world write endpoint this is inadequate.

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?

Top-level schema description coverage is 0% — the single 'body' parameter carries no description in the schema, and the description adds nothing about it. The nested item properties are richly documented inside the schema (keywords max 1000, language/location code pairs, use_clickstream default), but the description itself contributes no parameter meaning at all.

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 body contains only a billing note and zero-width characters; it never states what the tool does. Nothing distinguishes it from the many sibling post_dataforseo_*_live endpoints (bing_search_volume_live, clickstream_bulk_volume_live, gads_search_volume_live, etc.) beyond what the name/title already implies.

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?

No when-to-use, when-not-to-use, or alternative selection guidance is present. An agent has no way to know whether to pick this over post_dataforseo_keywords_bing_search_volume_live, clickstream_bulk_volume_live, or clickstream_global_volume_live.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description's only genuine addition is the cost disclosure ($0.09 default estimate, not a fixed price), which is real but minimal; it says nothing about async task submission, result retrieval, or the pingback/postback flow that the schema implies.

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?

It is short and structurally clean, but the content does not earn its place relative to the tool's job: a purely commercial notice occupies the entire description while purpose and usage go unstated. Brevity here stems from under-specification rather than disciplined editing.

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?

For a task-submission endpoint wrapping a 1-parameter body array with many nested fields, the description omits purpose, usage, and behavioral context entirely. Although an output schema exists and annotations cover the safety profile, an agent still lacks the essential information to select and call this correctly.

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?

Reported schema description coverage is 0% and the top-level 'body' array has no description at all, so the description would need to compensate — which it does not. The nested item properties do carry detailed field-level descriptions (bid, match, keywords, dates), which prevents a 1, but the description itself adds zero parameter meaning.

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 body contains only a usage-based pricing notice; it never states what the tool does. The only signal of purpose comes from the tool name and title ('Setting Ad Traffic By Keywords Tasks'), which the description does not reinforce or clarify. An agent reading the description alone learns nothing about the operation.

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?

There is no when-to-use, when-not-to-use, or alternative guidance whatsoever. Siblings like get_dataforseo_keywords_gads_ad_traffic_fetch and post_dataforseo_keywords_gads_search_volume_live exist, but the agent is given no basis for choosing among them. The pricing block is not usage 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 the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description carries less burden. It does add useful behavioral context not present in annotations: the usage-based billing model with a $0.09 default request estimate and the note that Google Ads may return no data for certain keyword groups. It does not explain why the tool is flagged destructive or mention auth/rate behavior, leaving a gap.

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 most prominent content is an API-migration warning about AdWords vs Google Ads that is irrelevant to invoking this endpoint, plus a templated pricing block. The actual purpose sentence is buried in the middle of the description rather than front-loaded, so the reader must dig for the operative information.

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?

An output schema exists, so return values need no explanation here. But for a mutation/billing endpoint whose only top-level parameter is an undescribed array wrapper, the description should clarify how requests are structured and what gets generated; instead it spends its space on legacy-API migration trivia.

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 top-level 'body' parameter is an array of task objects with no schema description (reported coverage 0%), and the description does not explain this wrapper structure, the batching semantics, or ordering. The one detail it does give — 'up to 20 keywords in the keywords array' — merely duplicates what the nested schema already documents, so it does not compensate for the coverage gap.

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 operative sentence — 'provide relevant keywords for the specified terms... get keyword suggestions from Google Ads' — states a specific verb and resource, so the core purpose is discernible. However, the migration note about the legacy AdWords API dominates the opening, and the description never distinguishes this tool from close siblings like post_dataforseo_labs_google_keyword_suggestions_live or post_dataforseo_keywords_gads_search_volume_live. An agent must guess from the name alone which keyword tool to pick.

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 says 'Set up to 20 keywords in the keywords array and get keyword suggestions,' which hints at a mechanical usage but offers no when-to-use versus alternatives, no prerequisites, and no exclusions. With many overlapping keyword/suggestion siblings available, this is a meaningful omission.

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=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered by structured data (consistent with a task-creating POST endpoint). The description adds genuinely useful non-annotation context: usage-based billing at roughly $0.09 per request and the exact data fields returned. It does not explain the task/async lifecycle or whether a separate fetch step is required.

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?

Roughly half the text is a Google Ads vs AdWords migration notice that is irrelevant to selecting or invoking this tool, and it is placed first, ahead of the only sentence that describes the endpoint. The pricing boilerplate is useful but the definition is not front-loaded on the actual function.

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?

An output schema exists, so return values need not be described, and annotations cover safety. What is still missing is the batch/array nature of the request body, the async task semantics implied by the name and title, and any differentiation from the large sibling set — for a tool with this much overlapping competition, that leaves real 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?

Top-level schema description coverage is 0% and the description says nothing about the single 'body' parameter — notably it never explains that this is an ARRAY of task objects, i.e. that multiple tasks can be batched in one call. The nested item properties are thoroughly documented in the schema, which mitigates the gap, but the description itself fails to compensate for the structural ambiguity it should clarify.

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 second paragraph states a specific verb+resource: it returns 'a list of keywords relevant to the specified domain along with their bids, search volumes..., and competition levels'. That is concrete enough to know what the tool does, but it never distinguishes this from the many keyword siblings (post_dataforseo_keywords_gads_kw_for_keywords_live, post_dataforseo_keywords_bing_kw_for_site_live) or from the page-targeting variant. The front-loaded AdWords-vs-Ads upgrade notice adds confusion rather than clarity.

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?

There is no when-to-use guidance, no mention of prerequisites (credentials, task/queue model implied by the 'post' prefix and 'Setting ... Tasks' title), and no routing to any of the ~40 sibling keyword tools. The agent must infer the choice between site, url, and keyword-based variants entirely from the tool name.

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 supply the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true). The description adds genuinely useful behavioral context not in the annotations: usage-based billing with a default estimate of $0.09 USD and account-specific pricing. However, it says nothing about rate limits, synchronous vs task-based execution, or what 'destructive' means here. With annotations carrying the safety burden, this is an adequate 3.

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 text is short but poorly structured: it opens with a stray zero-width character and front-loads an irrelevant API-migration warning before any statement of purpose. Every sentence discusses migration or pricing rather than the tool's function, so the space is not spent on what an agent needs.

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?

Because an output schema exists, return values need not be explained, and the annotations cover the safety profile. But for a keyword-search-volume endpoint with a complex nested body and a 1000-keyword limit, the description omits the essentials: what it returns, that it runs live/synchronously, and any keyword/location constraints. The critical purpose and usage gaps make it incomplete.

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 description provides zero information about any parameter, and the top-level schema description coverage is reported as 0%. Although the deeply nested body fields (keywords, date_from/date_to, location_*) carry rich descriptions in the schema, the description does not compensate for the measured coverage gap as required. It adds nothing an agent could use to invoke the tool correctly.

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 never states what the tool does. Its two substantive sentences are about migrating from the legacy AdWords API and about pricing, neither of which describes the operation. An agent must fall back on the title ('Google Ads Search Volume Tasks') and the tool name to infer that it retrieves Google Ads search volume data for keywords, so the description itself is effectively tautological/boilerplate.

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?

There is no when-to-use guidance at all. The only condition stated ('if you're using the DataForSEO Google AdWords API, you need to upgrade') is a migration notice, not a routing instruction. No mention of alternatives such as post_dataforseo_ai_keyword_volume_live or post_dataforseo_keywords_gads_kw_for_keywords_live, and no indication of live-vs-task semantics.

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 destructiveHint=true, idempotentHint=false, openWorldHint=true, so the safety profile is covered externally. The description adds almost nothing behavioral: it does not explain the cost beyond the boilerplate pricing line, auth requirements, or that the endpoint accepts a POST body of tasks — and it silently conflicts with the 'Setting Tasks' title by framing itself as a simple data provider.

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?

Two tight, front-loaded sentences that earn their place, followed by a compact pricing note. No redundant restatement of the name, though the pricing boilerplate is generic template text.

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?

An output schema exists, so return values need not be described, and the core data description is clear. However, for a destructive POST endpoint the definition omits any behavioral or cost/auth context and gives no routing guidance among the dense set of trends siblings.

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?

Top-level schema description coverage is 0% for the single `body` parameter, and the description does not compensate. It never mentions that `keywords` is effectively required (max 5), the date/time_range behavior, or the location_code/location_name mutual exclusivity that the nested schema documents.

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?

States a specific verb and resource: it returns the demographic breakdown (by age and gender) of keyword popularity per term. This differentiates it from siblings like trends_explore_live, trends_merged_data_live, and trends_subregion_interests_live, and it scopes the data sources (Google Search, News, Shopping).

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 explains what data comes back but never says when to choose this tool over the many sibling trends/labs/volume tools. No prerequisites, no exclusions, no named alternative for the demography-vs-explore-vs-merged decision.

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 frames the tool purely as a data-retrieval endpoint ("will provide you with the keyword popularity data"), which conflicts with the annotations declaring readOnlyHint=false and destructiveHint=true. The only added behavioral note is the auto-inserted pricing block (usage-based billing, ~$0.0012 estimate), and no auth, rate-limit, or side-effect context is given. Description and annotations disagree on the safety profile.

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?

Two sentences, purpose front-loaded, no filler; the pricing block is boilerplate but clearly demarcated. Nothing in the prose is wasted, though the content is thin rather than tight.

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?

An output schema exists so return values need not be described, but for a POST endpoint that sets a live task with a required keywords field inside a body array, the description omits how to select the engine type, how the array is structured, and the task-setting nature implied by its own title. An agent cannot call this correctly from the description alone.

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 for the sole top-level parameter (body) is 0% and the description says nothing about the request shape — no mention of keywords, date ranges, location, or time_range presets. The nested item schema happens to document those fields, but the description itself contributes zero parameter meaning and does not compensate for the reported coverage gap.

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 names a specific verb+resource ("provide you with the keyword popularity data from DataForSEO Trends") and scopes it to three engines (Google Search, Google News, Google Shopping). It is clear on what the tool returns, but it never distinguishes itself from near-neighbours such as post_dataforseo_ai_keyword_volume_live or post_dataforseo_keywords_gads_search_volume_live, which return adjacent keyword metrics.

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?

There is no when-to-use / when-not-to-use guidance and no named alternative. The agent is told what data comes back but not in which situation this trends endpoint should be chosen over the many keyword-volume and keyword-overview siblings.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=true, so the safety profile is covered structurally. The description adds genuinely useful pricing context ($0.09 default estimate, usage-based billing) that annotations do not carry. Beyond that it says nothing about task/live execution semantics, keyword cap, or billing triggers, so it adds moderate rather than rich context.

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?

Purpose is front-loaded in the first clause and the enumeration of returned data is compact. There is minor redundancy ('keyword popularity' recurs three times) and the injected pricing block breaks the flow, but nothing is padded or wasted.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. What is missing for a tool sitting among four near-neighbour trends endpoints is the routing information — when this merged variant should be used instead of the specialized ones — which leaves the definition adequate but incomplete.

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?

Top-level schema description coverage is 0% and the description contributes no parameter meaning at all — no mention of keywords, date range, time_range presets, or the location_code/location_name tradeoff. Nested field docs in the schema do cover keywords (max 5) and date formats, which partially mitigates the gap, but the description itself compensates for nothing.

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 names a specific resource (DataForSEO Trends keyword popularity data) and enumerates the three data families it returns: popularity rate over time, location-specific popularity, and demographic breakdown per term. That is far more specific than a tautology. The gap is that it never explains what 'merged' means relative to its siblings post_dataforseo_keywords_trends_explore_live and post_dataforseo_keywords_trends_demography_live, which cover overlapping data.

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?

There is no guidance on when to choose this endpoint over the several sibling trends endpoints (explore_live, demography_live, subregion_interests_live). The description implies it is a combined call, but it never states that explicitly, nor does it mention prerequisites, keyword limits, or exclusions. Usage is left entirely to inference.

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 the safety profile (readOnlyHint=false, destructiveHint=true, non-idempotent), so the description carries a lighter burden. It adds genuinely useful cost context ('Usage-based billing; Default request estimate: $0.0024 USD'), which is not in the annotations, but it says nothing about what 'live' means here or how the endpoint behaves at call time. Note the tension between a data-retrieval description and destructiveHint=true; because the title frames this as 'Setting ... Tasks' (a non-idempotent POST), this is not treated as a hard contradiction.

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 core purpose is front-loaded in a single tight sentence, and the pricing block is compact and clearly delimited. It is appropriately sized, though the brevity comes partly from omitting necessary scope detail rather than from disciplined editing.

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?

An output schema exists, so return values need not be explained, but the description still leaves real gaps for a trends-family POST: what 'subregion interests' actually returns, how it differs from sibling trends endpoints, and any parameter guidance for the nested body object. Given the richness of the nested schema and the number of near-identical siblings, the description is under-specified.

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 for the top-level body parameter is 0% (the array property itself has no description), so the description must compensate and largely does not. Only 'location-specific' loosely gestures at location_code/location_name; nothing is said about keywords, the 5-keyword limit, date_from/date_to, or time_range presets.

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 gives a clear verb phrase ('provide you with location-specific keyword popularity data from DataForSEO Trends') and names the three surfaces (Google Search, News, Shopping). However, it never explains the tool's distinguishing scope — 'subregion interests' — and reads identically to sibling trends endpoints such as trends_explore_live, trends_demography_live, and trends_merged_data_live, so an agent cannot tell them apart from the description alone.

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?

There is no when-to-use guidance, no prerequisites, and no alternatives named. The description states only what data comes back, leaving the agent to guess whether this endpoint or one of the other trends siblings is appropriate.

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 declare readOnlyHint=false and destructiveHint=true, yet the description's 'provide you with the Keyword Difficulty metric' describes a pure read/retrieval operation, so the two conflict. The description does add a useful behavioral detail — usage-based billing with a default estimate of $0.0734 — but it never addresses auth, rate limits, or the destructive classification, so transparency is weak and partly contradictory.

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?

It is front-loaded with the core purpose and reasonably short, but the second and third sentences overlap heavily (both explain ranking in top-10 organic results), and the boilerplate billing block adds bulk without adding task-selection value.

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?

An output schema exists, so return-value explanation is unnecessary, but the description leaves the single array parameter and its required nested fields entirely uncovered and provides no usage routing. For a bulk live endpoint whose only param is a structured array, this is incomplete.

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?

Reported schema description coverage is 0% at the top level (the 'body' array itself is undocumented), so the description carries the burden of explaining parameters — and it mentions none of them. It doesn't explain the required keywords array, the max-1000 limit within the array, or the language/location code requirements.

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 names a specific resource (Keyword Difficulty metric) and a clear scope (bulk, up to 1,000 keywords in one request), and it even defines what the metric means. It does not, however, distinguish this bulk endpoint from siblings like get_semrush_keyword_difficulty or post_dataforseo_labs_google_keyword_overview_live.

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 states the 1,000-keyword bulk limit, which implies when the endpoint is appropriate, but gives no explicit when-to-use/when-not-to-use guidance and names no alternative sibling for single-keyword or cross-source lookups. An agent must infer the routing decision on its own.

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 openWorld and non-idempotent, but the destructiveHint=true / readOnlyHint=false pair is counterintuitive for an endpoint whose description says it merely 'provides' category data; the description never explains that the flag reflects usage-based billing rather than data mutation. It does add genuinely useful behavior the annotations lack: the 1,000-keyword request cap and a default cost estimate of $0.1356 USD. That pricing disclosure is real added value, but the destructive framing is left unexplained.

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 core sentence is front-loaded and the limit sentence is short and useful. The embedded pricing comment block adds a third section of boilerplate, but it is clearly delimited and only minimally interrupts the two substantive sentences.

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?

An output schema exists, so return values need not be described, and the pricing note covers the cost dimension. However, for a paid live endpoint the description omits the prerequisites (language selection) and any positioning against the several sibling keyword-category tools, leaving the destructive annotation unexplained despite it being the most surprising signal.

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 reported at 0% for the top-level body parameter, so the description carries the burden and largely fails it. The only parameter fact offered, the 1,000-keyword maximum, is already stated in the nested keywords description, and nothing is said about the tag field, language_code/language_name alternatives, or the required-inside-item quirk that the empty top-level required array obscures.

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 and resource: it returns Google product and service categories for each specified keyword. An agent can distinguish this from the nearby post_dataforseo_labs_google_categories_for_domain_live and post_dataforseo_labs_google_keywords_for_categories_live, since the input unit (keywords) is named. It stops short of explicitly routing against those siblings, so it is clear but not differentiated.

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?

There is no when-to-use guidance, no named alternative, and no prerequisite stated (the schema requires language_code or language_name on each body item, and keywords itself is marked required inside the item, while top-level required is empty). The only usage-relevant fact given is the 1,000-keyword ceiling, which is also present in the schema. An agent gets no help deciding between this and the many other keyword/category endpoints.

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 the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the bar is lower. The description adds genuinely useful context beyond the schema: historical coverage start (August 2021) and a usage-based billing estimate ($0.1356 default). It does not reconcile the destructive/readOnly annotations with what is plainly a data-retrieval endpoint, nor mention auth or rate limits.

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?

Purpose is front-loaded in the first sentence and the whole body is short. The pricing block earns its place as cost context, though the leading zero-width characters before the first sentence are noise.

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?

An output schema exists, so return values need not be explained, and the annotations cover behavior. The description covers data meaning, historical range, and cost, but omits the batch/array request mechanics and the relationship to the near-identical non-historical siblings, leaving selection ambiguity.

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?

Top-level schema description coverage is reported at 0% (the single 'body' property is undocumented), but the nested item properties carry very rich descriptions. The description compensates partially by naming keywords, location, and language, matching the request fields, though it says nothing about the array/body wrapper or the 700-keyword / 80-character limits.

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 names a specific verb and resource ('provides Google historical keyword data for specified keywords') and enumerates the returned metrics (search volume, CPC, paid-competition values, monthly searches, trends), so an agent knows exactly what it gets. The 'historical' qualifier implicitly distinguishes it from the non-historical sibling post_dataforseo_labs_google_keyword_overview_live, but no sibling is named explicitly.

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 states data coverage (since August 2021) and that availability varies by keyword/location/language, but never says when to pick this tool over alternatives such as post_dataforseo_labs_google_keyword_overview_live or post_dataforseo_keywords_trends_explore_live. No when-not guidance or prerequisite conditions are given.

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 openWorldHint, non-idempotent, and destructive/readOnly=false, so the safety profile is largely covered by structured data and nothing here contradicts it. The description adds genuinely useful cost transparency via the usage-based billing note ($0.132 default estimate), but omits other material behaviors such as the required location/language pairing and the double-charge when include_clickstream_data is enabled.

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?

Two substantive sentences plus a pricing block, front-loaded with the core purpose and free of filler. The pricing banner is boilerplate but short and informative; the leading stray character is a minor formatting blemish.

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?

An output schema exists, so return values need not be described, and the pricing note covers cost. Still missing for an agent to use it confidently are differentiation from the sibling keyword endpoints and confirmation of the location/language requirement, which the schema forces but the description never signals.

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?

Only one top-level parameter (body) exists, and the schema's nested property descriptions are extremely detailed, so the schema carries the parameter burden. The description adds just one hint ('seed keywords specified in a POST array'), which does not compensate for the reported 0% coverage at the top level nor mention the required keywords/location fields.

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 and resource: it generates search terms ('keyword ideas') relevant to the categories of the seed keywords supplied. It explains the selection algorithm (same-category matching), which separates it conceptually from siblings. However, it never names or contrasts with the very similar siblings (post_dataforseo_labs_google_keyword_suggestions_live, post_dataforseo_labs_google_related_keywords_live), so an agent must infer the difference.

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?

There is no when-to-use / when-not-to-use guidance and no mention of alternatives, despite a crowded sibling set of near-identical keyword-expansion endpoints. The description only says what the endpoint does, leaving the agent to guess which of the several keyword endpoints to select.

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 declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, yet the description neither explains that destructive framing nor notes auth/permission needs. It does add genuinely useful context not in the annotations: the ~$0.0254 default cost estimate and the doubling of price when include_clickstream_data is enabled.

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?

Two front-loaded sentences that lead with what data is returned, plus a clearly delimited pricing boilerplate block. No wasted prose, though the boilerplate is not the description's core job.

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?

An output schema exists, so return-value detail is not required, and the tool is a single-parameter live query. However, the description omits the input constraint pairs the schema enforces (language_code/language_name and location_code/location_name are each required in some combination), which an agent needs to call it successfully.

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 top-level recommended parameter 'body' has no description of its own (0% coverage per the signals), and the description adds only the include_clickstream_data behavior. The nested oneOf schema is in fact well documented, so the description neither compensates for nor detracts from the schema; a baseline 3 fits.

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?

States a specific verb ('provides') and resource ('Google keyword data for specified keywords') and enumerates the returned metrics (CPC, competition, search volume, search intent, monthly searches, SERP/backlink info). Clear enough to call, but it never distinguishes itself from sibling keyword tools such as keyword_ideas, keyword_suggestions, or google_search_intent.

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?

No when-to-use guidance, no prerequisites, and no routing against the many sibling keyword endpoints. The only conditional hint is that clickstream data can be obtained by setting include_clickstream_data, which is a parameter note rather than usage 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=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds useful behavioral context by disclosing billing (default estimate $0.1356, usage-based, not fixed), which matters for a paid live call; it says nothing about auth, rate limits, or pagination limits beyond what the schema carries.

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?

Purpose is front-loaded in a single compact sentence followed by the returned-metric list, with no filler. Minor detraction from a stray zero-width character at the start and a pricing block that reads as injected boilerplate rather than authored prose.

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?

An output schema exists, so return values need not be re-explained (the description does so anyway, mildly redundantly). For a schema this complex — one nested body object with fifteen properties and implicit required-field rules — the description is thin, leaving the agent to discover the category/language/location requirements only inside the schema.

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?

Top-level schema description coverage is 0% and the description never discusses the body payload. The phrase 'specified product categories' loosely maps to category_codes, but the required language/language_code and location/location_code pairing, pagination via offset_token, and the filter semantics are left entirely to 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 states a specific verb and resource: it returns keywords relevant to specified product categories, and enumerates the metrics returned (search volume, 12-month trend, CPC, competition). That is enough to separate it from siblings like keywords_for_app, categories_for_kw, or keyword_ideas, though no sibling is named explicitly.

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?

There is no when-to-use or when-not-to-use guidance, no mention of alternatives (e.g. keyword_ideas, related_keywords), and no prerequisites such as the language/location pairing or the 20-category cap required by the body. The agent must infer all of this from the sibling list and schema.

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 the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description's main added value is the usage-based billing estimate ($0.132 default), which is genuinely useful behavioral context for a paid API call. It does not explain why the tool is flagged destructive, nor does it repeat or contradict that flag, so it neither contradicts nor enriches the annotation set further.

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?

Purpose is front-loaded in a single tight sentence, followed by a clearly delimited pricing block. Nothing is wasted, though the brevity edges toward under-specification given the tool's numerous siblings.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What is missing is selection context: for a keyword-research endpoint sitting among roughly ten near-neighbor DataForSEO Labs tools, the agent gets no signal on when this one is preferred.

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 description adds nothing about parameters, but the reported 0% coverage reflects only the top-level 'body' property; the nested request fields (keyword, location_code, filters, order_by, include_clickstream_data, etc.) are documented in extensive detail inside the schema itself. Since the schema already carries the parameter semantics, the description adding nothing lands at the baseline rather than a penalty.

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 names a specific deliverable ('search queries that include the specified seed keyword'), which is a real verb+resource and even disambiguates it semantically from related-keyword tools. It never names a sibling tool, however, so the agent must infer the boundary with tools like post_dataforseo_labs_google_related_keywords_live or post_dataforseo_labs_google_keyword_ideas_live on its own.

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?

There is no when-to-use statement, no when-not-to-use statement, and no mention of any alternative among the many keyword-research siblings. The only usage signal is implied by the name and the one-line definition.

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 the operational profile (openWorld, destructive, non-idempotent, non-readOnly), so the bar is lower. The description usefully adds cost context (default $0.0156 estimate, usage-based billing) and enumerates the returned fields (product categories, search volume, trend, CPC, competition). It does not explain why a data-retrieval endpoint carries destructiveHint=true, leaving a mild inconsistency unaddressed.

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?

Purpose is front-loaded in the first sentence, and the bounded pricing block is clearly delimited. The orphaned fragment 'View the element.' is a leftover artifact that earns nothing, but overall the text is tight and appropriately sized.

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?

Because an output schema exists, return values need not be explained, and cost is covered. However, the description omits usage routing against sibling keyword tools and any mention of the location/language requirement, leaving gaps for an agent selecting and invoking this among ~60 siblings.

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?

Reported top-level schema coverage is 0%, but the sole top-level parameter ('body') embeds a nested schema that richly documents keyword, depth, limit, filters, and location/language fields. The description adds the 'search depth' concept and the 4680-keyword ceiling, overlapping what the nested schema already states, but does not surface the required location/language selection constraints.

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 names a specific verb+resource ('The Related Keywords endpoint provides keywords') and identifies the data source ('Searches Related to' SERP element), which separates it from sibling keyword tools like keyword_ideas or keyword_suggestions. It does not explicitly name those siblings, but the source-of-data framing makes the purpose distinguishable.

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?

There is no when-to-use guidance and no routing against the many sibling keyword endpoints (keyword_ideas, keyword_suggestions, keyword_overview). The description describes the endpoint's output but never states the condition under which an agent should prefer it over those alternatives.

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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is already carried structurally. The description adds genuinely decision-relevant context beyond that: per-request usage-based cost (~$0.0073) and variable account pricing, which matters for a billed live call. It does not, however, explain the non-idempotent/destructive annotation, leaving a mild unexplained tension with the 'provide you with data' framing.

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?

One tight sentence covering the operation, the per-keyword granularity, and the result shape, followed by a pricing block. There is a stray leading whitespace character and the billing banner is boilerplate, but the core content is front-loaded and waste is minimal.

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?

An output schema exists, so return values need not be explained, and the description does state the input ceiling and cost. What remains missing for a live, paid, non-idempotent endpoint is any routing guidance against the many sibling keyword endpoints and any note on batching or latency behavior.

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?

Top-level schema description coverage is 0% (the single body parameter is undocumented), but the nested properties for 'keywords' and 'tag' carry rich descriptions, and the description restates the meaningful constraint that up to 1,000 keywords are accepted. It adds little else — requiredness, lowercasing, and encoding come only from the schema. Baseline 3 given one parameter with schema-side detail.

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 and resource: obtain search intent data (intent + probability, plus secondary intents) for up to 1,000 keywords. This is distinguishable from sibling Labs endpoints like keyword_overview or keyword_ideas by subject matter, though the description never names or contrasts itself against those alternatives.

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?

There is no when-to-use guidance: no statement of when search-intent classification is the right choice versus keyword_volume, keyword_suggestions, or the AI keyword tools in the sibling list. The only usage-adjacent information is the 1,000-keyword input cap, which is a limit rather than a selection criterion.

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 the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description's lower burden is met partly by the added pricing context ('Default request estimate: $0.1356 USD', not a fixed price). It does not explain why the operation is flagged destructive, whether the request is billed/rate-limited beyond the estimate, or what happens on failure. Given annotation coverage, a 3 is appropriate.

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?

Two short sentences plus a pricing note; front-loaded with the endpoint identity and reasonably free of waste. The pricing block is boilerplate but compact.

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?

An output schema exists, so return-value explanation is not required, and annotations cover safety. But for a complex, paid, location-scoped keyword API the description omits what the tool conceptually returns and any usage context, leaving gaps an agent would need to close from the schema alone.

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 reported at 0% for the top-level 'body' parameter, so the description carries the burden of compensating and does not. It says nothing about the location/language requirement, filters, limit/offset, or the offset_token pagination behavior. The rich nested schema descriptions help, but the description itself adds no parameter meaning.

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 names the endpoint and says it returns keywords from the DataForSEO Keyword Database with Google Ads metrics, product categories, and SERP data. However, it never explains what 'Top Searches' actually means functionally (most popular searches for a location/language) and offers no differentiation from the many sibling keyword tools such as google_keyword_ideas_live or google_related_keywords_live. The purpose is implied but marketing-flavored rather than precise.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the dozens of sibling DataForSEO Labs endpoints. The agent is left to infer entirely from the name and the mass of siblings.

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 and destructiveHint=false, so the safety profile is covered. The description adds workflow behavior the annotations cannot: the has_full_schema flag gates a required batch_get_schema call, and the next step after search is batch_quote, not batch_use. It stops short of disclosing retrieval limits or catalog breadth that would push it to 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?

It is a dense run of imperatives rather than flowing prose, but each sentence carries a distinct rule (scope, language, workflow branch, negative cases, result interpretation) and the most important scoping guidance is front-loaded. Slightly more compression would help.

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 an output schema present, the description need not explain return values, and it correctly avoids doing so while still referencing the output fields that drive the workflow (has_full_schema, next_steps_guidance). A mutation-free, well-annotated search tool is adequately covered, though catalog scope ('AIsa-only', no external providers) could be stated more explicitly.

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%, so the structured baseline is 3. The description adds genuine meaning beyond the schema by telling the agent to write the query in English and to place tickers, URLs, providers, or identifiers in known_fields, which is non-obvious routing guidance for a nested free-form object.

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 with a specific verb+resource: 'Discover AIsa tools and Plans for external data or actions.' It also separates this discovery step from the sibling execution tools by naming batch_get_schema, batch_quote, and batch_use and stating when each follows, so an agent can place it in the workflow without opening schemas.

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 explicit when-to-use ('tasks needing external data or actions'), when-not ('tasks that only need supplied content or general knowledge'; no standalone rewriting, translation, summarization, formatting, or calculations), and named alternatives (batch_get_schema when has_full_schema=false, batch_quote rather than batch_use). It also specifies query language and atomic-query style, leaving little to inference.

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