AIsa Keyword Volume & Ads

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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 short sentences with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-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?

With annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch 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 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the 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?

The description states a clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

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 no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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. The description is consistent with these but adds no behavioral context beyond the annotations, such as rate limits, authentication needs, or output characteristics.

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 a single sentence and front-loads the outcome. The lead-in phrase 'By calling this API you will receive' is slightly verbose but does not obscure the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, read-only list tool with an output schema and full annotations, the description is largely complete because it states what will be returned. It could be improved by clarifying when to choose this tool over related audience endpoints, but no critical information 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 has zero parameters, so parameter semantics are not applicable. Per the rubric, a zero-parameter tool receives a baseline of 4 unless the description contradicts or confuses 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 outcome: it returns the list of industries with industry_id supported by the Bing Ads Audience Estimation endpoint. This clearly distinguishes it from sibling tools aimed at job functions, languages, or other audience data, though it does not explicitly name an alternative sibling.

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. The description only states what the call returns, leaving the agent to infer that it should be used when industry IDs for audience estimation are 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific return content (job functions with IDs supported by the audience endpoint), which is useful context, but does not mention auth, rate limits, or other behavioral traits beyond what the schema and annotations provide.

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 a single sentence with no redundancy. It is slightly front-loaded with the filler phrase 'By calling this API you will receive' instead of leading with the resource, but it remains appropriately concise.

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 metadata endpoint with a rich output schema and complete annotations, the description adequately conveys what the agent will get. It could be improved by linking the returned IDs to the audience estimation endpoint that consumes them, but that is a minor 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?

There are zero parameters, so the baseline is 4. The schema is empty and the description correctly implies no inputs are needed.

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) and resource (list of job functions with job_function_id) scoped to Bing Ads Audience Estimation. It distinguishes from the parallel industries sibling via the resource name 'job functions', though it does not explicitly name 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?

The description explains what the tool returns but gives no guidance on when to use it, no prerequisites, and no alternatives among the many sibling metadata endpoints. The agent must infer usage from the tool name and title alone.

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 behavior. The description adds upstream cost of 0, reference-data caching advice, and a warning that catalogues are not shared between families (including a 46 MB size observation), which goes beyond the structured annotations and provides valuable operational 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 description contains redundant repetition of 'Free: upstream cost is 0' and could be tightened into fewer sentences. While the warning and usage notes are valuable, the duplication slightly reduces clarity and 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?

This is a simple reference-data getter with no parameters and an output schema. The description covers purpose, usage, cost, and caveats, making it complete for an agent to invoke correctly without needing additional details about return values or parameters.

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 has zero parameters, so schema coverage is 100% and the baseline for zero-parameter tools is 4. The description does not need to explain parameters, and it appropriately focuses on the list's purpose and usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the languages accepted by `post_dataforseo_keywords_bing_kw_for_url_live`, and the title identifies it as a list of Bing languages. It explicitly distinguishes itself from the broader `get_dataforseo_keywords_bing_languages` sibling, so an agent can tell them apart 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?

The description names the alternative `get_dataforseo_keywords_bing_languages` and explains that this list is narrower, guiding when to use which. It also advises fetching once and reusing instead of per-request calls, and warns to check the list for the specific endpoint being called, giving practical 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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description adds only that the result is a 'full list' of supported locations/languages for a specific API family; it does not disclose pagination, authentication, or rate-limit behavior, but 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?

One sentence that states the tool's scope. The opening 'Using this endpoint you can' is slightly wordy but the sentence is front-loaded and contains no extraneous detail.

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-param metadata endpoint with a rich annotation set and an output schema, the description supplies the necessary scope: locations and languages supported by Keyword Performance. It does not need to explain return values because an output schema exists, though adding a sentence about when to call it would improve completeness.

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 empty schema is fully documented (100% coverage) and the description does not need to describe any parameters.

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 ('get') and resource ('full list of locations and languages supported in Keyword Performance endpoints of Bing Keywords Data API'). It clearly identifies the Bing Keywords Data API scope, though it does not explicitly contrast with sibling locale/language list tools such as get_dataforseo_keywords_bing_languages or volume_history_locales, so it lands at 4 rather than 5.

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 beyond the implied context that the returned locales are for Keyword Performance endpoints. It does not state when to call this versus the sibling bing_locations, bing_languages, or volume_history_locales tools, so an agent must infer the selection from the endpoint name alone.

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 fully covered externally. The description adds nothing beyond that — no note on whether the result set is stable, paginated, or cached, and no auth or rate-limit context. It restates the outcome without enriching 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?

A single compact sentence with the resource front-loaded. The 'By calling this API you will receive' framing is slightly wordy boilerplate, but nothing is padded or repeated.

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 whose output schema already documents the return shape, the minimal description is nearly adequate. What is missing is any hint of how the returned languages are meant to be consumed in the keywords workflow, which the sibling set makes relevant.

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 schema-side burden is nil; per the rubric a 0-parameter tool has a baseline of 4. The description correctly implies no input filtering is needed to enumerate the language list.

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 list of languages supported by the Bing Ads API) and makes clear the tool is a read-only enumerator, which distinguishes it from sibling lookups like _locations or _locales. It stops short of explicitly contrasting itself with those near-neighbors, so it falls just below the top tier.

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 statement of when to call this versus the many sibling lookup tools (e.g. get_dataforseo_keywords_bing_locations, get_dataforseo_keywords_bing_kw_performance_locales), nor any prerequisite or follow-on context. Usage is only implied by the phrase 'By calling this API you will receive'.

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 externally. The description adds nothing beyond that - no note on whether the list is static/cached, how large it is, or any API cost/rate behavior. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. Slight verbal padding in 'By calling this API you will receive' instead of a direct 'Returns the list of...', but it is compact and waste-free.

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-format explanation is unnecessary, and a zero-parameter reference-list endpoint needs little more. The one real gap is that the description never ties this list to the downstream calls that consume location IDs, which would help an agent chain tools.

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 per the rubric sets the baseline at 4. No parameter concepts need explaining, and the schema coverage is complete.

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 the list of locations supported by the Bing Ads API. It is clear what the tool returns, though it does not explicitly distinguish itself from adjacent lookup siblings such as get_dataforseo_keywords_bing_languages or get_dataforseo_keywords_trends_locations.

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 sibling location/language list endpoints, nor any note about prerequisites or how the result is meant to be consumed (e.g., as valid location identifiers for the Bing keyword POST endpoints). Usage is only implied by the resource 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that the call returns a supported set; it says nothing about response size, whether the list is exhaustive, or caching/rate considerations for an openWorld lookup.

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?

A single sentence with the outcome front-loaded enough to be skimmable. 'By calling this API you will receive' is mild filler that could be trimmed to 'Returns the list of...' without losing 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 an output schema present, the description need not explain return values, and with zero parameters there is no input semantics to cover. It is adequate for this simple lookup, though a note on how the returned locales feed the related volume endpoint would round it out.

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 by rule the baseline is 4. There is no parameter semantics to add beyond what the empty schema already conveys.

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) and resource (the list of locations and languages) scoped to Bing's 'Search Volume History' endpoint, which helps distinguish it from the many other locale/language list tools. It could be sharper about how it differs from siblings like bing_languages and bing_locations, which also return location/language 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 only implied: an agent can infer this is a discovery/lookup call to find valid locale values before hitting the corresponding volume endpoint, but no when-to-use, prerequisite, or alternative is stated. Several near-identical sibling list tools exist, making explicit routing guidance valuable and absent here.

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 adds no behavioral context beyond what annotations provide, e.g. response format or update frequency.

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?

A single, efficient sentence that states the purpose directly with no filler. Appropriately sized for a parameterless lookup endpoint.

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 endpoint with annotations covering the safety profile and an output schema documenting return values, the description is sufficient. It could note it is a reference/static-data call, but nothing essential 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?

Zero parameters, so baseline is 4. There is nothing for the description to 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?

Clear verb+resource: it gets a list of locations and languages for the Clickstream Data API. Distinguishable from siblings like get_dataforseo_keywords_bing_languages/locations by naming the Clickstream API, though it doesn't explicitly route to 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?

No when-to-use guidance and no mention of alternatives, though this is a reference-lookup endpoint whose use is fairly self-evident. No exclusions or context are provided.

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 only cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavioral facts: there is no additional charge at fetch, the response is wrapped in DataForSEO's envelope with results at tasks[0].result and outcome at tasks[0].status_code, and a rejected request still returns HTTP 200. It also warns that the values are projections that shift with bid and match.

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 tight sentences, front-loaded with what is returned, then cost, then envelope/error semantics. Every clause carries information an agent needs and nothing is repeated from the schema or annotations.

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 fetch with a rich output schema and safety annotations, the description covers everything else that matters — cost model, envelope location, error semantics, and the projection caveat — so an agent can call and interpret the result 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?

With one parameter at 100% schema coverage the baseline is 3, but the description adds meaning the schema lacks: the id refers to a queued task derived from a prior submit with a specific bid and match, which explains why the returned projection is tied to those inputs.

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 ('Retrieves a queued Google Ads traffic forecast by `id`') and enumerates the returned metrics (impressions, clicks, cost, average position). The next-sentence contrast with 'the volume endpoints' distinguishes it from the measurement-style 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?

Clearly establishes the workflow context: this is the fetch step for a previously queued forecast, with the charge already incurred at submit time. It does not explicitly name post_dataforseo_keywords_gads_ad_traffic_submit as the required predecessor, leaving that pairing 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: Google refreshes monthly, mid-month in particular, and the returned data lags roughly one to two months, which tells the agent how to interpret staleness.

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 well with the core capability in sentence one, but the trailing October/September/August example is long and somewhat redundant, restating the same lag concept twice. It could convey the freshness window in one tighter sentence.

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 does explain the semantic meaning of the status (monthly Google refresh cadence and lag). The only missing piece is when to invoke this relative to the data-fetching 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema is trivially complete and the description does not 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?

The first sentence states the specific capability: determining whether Google updated keyword data for the previous month. It clearly contrasts with the many sibling 'live' keyword-fetch tools by being a freshness/status check rather than a data pull. It stops short of naming a sibling alternative, but the verb+resource intent 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?

No explicit when-to-use or when-not-to-use guidance. An agent can infer that this should be called before consuming GAds keyword volume/CPC data to check freshness, but the description never states that precondition or points to which sibling to use instead when data is stale.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the payload is JSON with a tasks array, which is mild behavioral context, but with an output schema present this is largely redundant rather than value-adding.

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 compact sentences with no padding or repetition of the name. The response-format clause is somewhat redundant given the output schema but is not wasteful enough to penalize heavily.

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?

Zero parameters, full annotation coverage, and an output schema means the burden on the description is low. The description states the resource and the shape of the response, which is sufficient for an agent 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?

The tool takes zero parameters, so there is nothing for the description to clarify. The baseline of 4 applies; no parameter information is missing or misleading.

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: returns the list of categories supported by Google Trends. An agent can tell it is a lookup/enumeration endpoint. However, it does not differentiate itself from siblings like list_categories or get_dataforseo_keywords_trends_locations, which could also plausibly return category-like 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 use this tool versus alternatives, no prerequisites, and no mention of sibling category tools. The description only describes what happens on invocation, not the conditions that select it.

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 operation as read-only, idempotent, open-world, and non-destructive. The description adds the useful constraint that the minimum supported geographic scope is country level, but it does not disclose return format, pagination, authentication requirements, or other behavioral details.

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 short and front-loads the purpose, then adds two useful constraints. It contains minor filler such as 'by calling this API' and 'when setting a task', but overall it 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?

For a zero-parameter lookup endpoint that has an output schema, the description provides the essential purpose and the country-level scope constraint. It could better explain how the returned locations are intended to be used, but nothing critical is missing for invoking the 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?

The tool has zero input parameters, so the baseline is 4. The description mentions country filtering, but that appears to apply to task setup rather than this tool's own inputs, and there are no parameters for the description to 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 description clearly states the tool returns a list of DataForSEO Trends locations, naming both the verb-like outcome (receive/list) and the specific resource. It implicitly differentiates from sibling location tools by specifying the Trends product, though it does not explicitly contrast with 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?

The description gives some context by noting that locations can be filtered by country when setting a task and that country is the minimum geographic scope. However, it does not say when to use this tool versus sibling location or category tools, nor does it name 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read profile is covered by structured data. The description adds that this is a static supported-languages reference, but says nothing about auth requirements, caching, or stability of the list. Adds modest value over annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with the resource front-loaded after a minor lead-in phrase ('Using this endpoint you can') that is filler. Efficient overall, with negligible waste.

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 need not be explained, and the tool is a simple parameterless list. However, the description omits the practical context of which endpoint these language codes feed into, leaving the agent to infer the relationship to post_dataforseo_labs_google_categories_for_kw_live.

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 it is 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 (get) and resource (full list of languages supported for the Google Categories for Keywords endpoint), which is clear and distinguishable from the sibling post_dataforseo_labs_google_categories_for_kw_live. It stops short of explicitly naming that consuming sibling, so differentiation relies on the reader inferring the naming convention.

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 can infer this is a reference lookup used to discover valid language values, but there is no explicit when-to-use statement, no mention of the sibling endpoint that consumes these values, and no exclusions. Minimum viable guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

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 moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use 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?

Schema description coverage is 100%, so parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

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: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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 implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not 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 declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds crucial behavioral context beyond these: billing per returned row at $0.18, up to 20 rows, 4xx/5xx not charged, and response as semicolon-delimited text. This transparency is key for agents to manage costs and parse output.

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 two sentences, front-loaded with the primary function in the first sentence and key operational details (billing, limits, format) in the second. No filler or redundancy; every word earns its place.

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 only 2 parameters, an output schema, and annotations covering safety, the description is nearly complete. It adds billing, row limits, and response format, which are essential. Minor gap: it doesn't mention behavior on empty results, but the output schema likely covers return structure. Overall 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 covers 100% of parameters: phrase (with URL-encoding guidance) and database (with default). The description adds no extra parameter semantics beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the full burden, and the description does not enhance it.

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 a specific function: 'Broad-match and alternate keyword variants for a seed phrase, with volume and CPC.' This verb-resource-output combination distinguishes it from siblings like get_semrush_domain_organic_keywords or get_semrush_question_keywords, which target different data types.

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 implies usage when a seed phrase is available and broad-match variants are needed, but it does not explicitly name alternatives or state when not to use this tool. Sibling tools exist for domain-based, paid, or question keywords, yet no routing guidance is provided.

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, covering safety. The description adds valuable behavioral context: cost per row ($0.09), row limit (up to 20), header exclusion, error handling (4xx/5xx not charged), and response format (semicolon-delimited text). These details go beyond annotations and inform the agent about side effects and output parsing. This is a strong addition, though it doesn't mention pagination (but the limit is clear).

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 two sentences with no wasted words. It front-loads the core purpose, then adds cost and format details. Every piece of information earns its place, and the structure is logical: what, then cost, then response format. This is highly concise and well-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 that an output schema exists, return values are already structured. The description covers purpose, cost, row limit, and response format. Combined with annotations (read-only, idempotent) and the input schema, an agent has enough to call the tool correctly. The only gap is explicit sibling differentiation, but that falls under usage guidelines rather than completeness. It is quite complete for a simple retrieval 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 100%, so both parameters (domain and database) are fully documented with examples. The description adds no additional parameter semantics—it doesn't elaborate on format or constraints beyond what the schema provides. Per the rubric, when schema coverage is high, the baseline is 3, and the 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?

The description clearly states the tool returns keywords a domain ranks for in Google organic, with specific fields (position, volume, CPC, URL). This is a specific resource and action, but it doesn't explicitly contrast with siblings like get_semrush_domain_overview or get_semrush_organic_results. The purpose is evident and distinct, but lacks explicit differentiation.

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 no explicit guidance on when to use this tool versus alternatives. There is no mention of conditions or exclusions relative to sibling tools. Usage is implied by the tool's name and purpose, but the description doesn't state 'use this for X instead of Y'. Since it's a straightforward retrieval, the lack of explicit guidance is acceptable but not ideal.

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?

Discloses important behavioral details beyond the annotations: the cost model ($0.18 per row, up to 20 rows, header excluded), that 4xx/5xx responses are not billed, and the semicolon-delimited response format. These are critical operational facts that the read-only/idempotent annotations do not 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?

The description is extremely efficient: three sentences, each serving a distinct purpose—core function, billing and limits, and response format. There is zero filler and information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter read-only tool with an output schema, the description covers the essential operational aspects: what it returns, how much it costs, row limits, error billing, and output format. The only notable gap is explicit guidance on when to choose this tool over the organic-keywords sibling, which is a minor omission given the clear name and content.

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?

Both parameters (domain and database) are fully described in the schema with examples and meanings, giving 100% schema description coverage. The tool description adds no parameter-level detail, but it does not need to because the schema already carries that weight, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns keywords a domain bids on in Google Ads, listing the specific data fields (position, volume, CPC, URL). This unambiguously distinguishes it from the sibling get_semrush_domain_organic_keywords, which covers organic rather than paid 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?

The description implies the tool is for paid Google Ads keywords, but it does not explicitly name alternatives or state when not to use it. The sibling get_semrush_domain_organic_keywords exists, yet differentiation is left to inference from the name and the word 'paid' rather than direct 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 mark the tool as read-only, open-world, and idempotent, so the additional value comes from the per-row billing, 20-row cap, 4xx/5xx non-charge disclosure, and semicolon-delimited-text response format. It adds real operational behavior without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three compact sentences: purpose first, then billing, then response format. Each sentence earns its place and there is no filler or duplicated schema content, though the cost sentence is dense and could stand out more.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the parameter set is simple, the description covers the core purpose, cost, limits, and response format, which are the main contextual gaps. It does not address when to choose Semrush over DataForSEO alternatives, but the tool's unique resource-specific behavior is sufficiently captured.

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 schema already documents the semicolon separator, 20-keyword limit, and database default. The description contributes the connection between row billing and returned data rows, but no additional parameter-level semantics beyond what the schema already conveys.

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 first sentence clearly identifies the tool as returning Semrush's keyword difficulty index, with an explicit metric scale and batch capability. It distinguishes from domain-level or competitor tools because of the specific metric and name, though it doesn't name alternative tools such as the DataForSEO bulk keyword difficulty sibling.

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 no scenario-based guidance such as when to choose this tool versus a sibling like post_dataforseo_labs_google_bulk_keyword_difficulty_live or get_semrush_keyword_overview. The dollar cost per row and error charging are operational context, 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 readOnly/openWorld/idempotent/not-destructive, and the description adds valuable context beyond them: the per-call billing cost ($0.09, with 4xx/5xx not charged) and the semicolon-delimited response format. No contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with zero filler. Purpose is front-loaded first, followed by billing disclosure and response format — each sentence earns its place and 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 simple 2-parameter read-only tool with a full output schema and comprehensive annotations, the description covers purpose, cost, and format. The only thing missing is routing guidance to related siblings, but the tool's simplicity and structured fields carry the rest.

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 schema already documents both phrase and database parameters with examples. The description only reinforces this with 'keyword phrase in a given regional database', adding marginal value beyond the schema baseline of 3.

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 (Return) + resource (search metrics for a keyword phrase) + scope (regional database), and enumerates the exact metrics returned (volume, CPC, competition, results). This distinguishes it from siblings like get_semrush_backlinks_overview and get_semrush_domain_overview without needing to open their 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?

Provides no guidance on when to choose this tool over alternatives. Siblings get_semrush_organic_competitors, get_similarweb_keywords, and get_similarweb_keyword_competitors overlap in keyword topics, yet the description never tells an agent which to prefer or under what conditions. This is a clear 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details: per-row billing at $0.36 (up to 20 rows), no charge for 4xx/5xx, and a semicolon-delimited text response. This goes beyond annotations without 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?

Two sentences with zero waste: the first sentence states the core purpose, the second covers billing and response format. Information is front-loaded and each clause earns its place.

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 simple read-only tool with only 2 parameters and an existing output schema, the description covers purpose, billing constraints, and response format. Nothing essential is missing for an agent to invoke 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?

Schema description coverage is 100%, so both parameters (phrase and database) are documented in the schema. The description does not add additional parameter semantics beyond what the schema provides; the baseline of 3 applies.

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: 'Question-form keyword variations for a seed phrase, with volume and CPC.' This clearly distinguishes it from sibling tools like get_semrush_broad_match_keywords or get_semrush_keyword_overview, which return different types of keyword 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?

The description implies usage context by mentioning 'Question-form keyword variations' — an agent can infer this is for question-based queries. However, it does not explicitly contrast with siblings or state when not to use it, so guidance is implied rather than explicit.

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?

Adds significant behavioral detail beyond annotations: billing per row, 20-row cap, header excluded, no charge on 4xx/5xx, and semicolon-delimited text response. These are actionable and non-obvious.

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 dense sentences cover purpose, cost, and response format with no fillers. Each sentence earns its place.

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 high schema coverage, annotations, and an output schema, the description covers the essential operational details: what the tool returns, what it costs, and how the response is formatted.

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 input schema already documents url and database with 100% coverage, so the description only reinforces that url means the target landing page. It adds no new parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb-and-resource outcome: 'Keywords a specific URL ranks for in Google organic.' This clearly differentiates it from domain-level, paid, or broad-match keyword 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?

The description gives clear context for when to use the tool: when a specific URL's organic Google rankings are needed. It does not name alternatives explicitly, but the 'specific URL' phrasing distinguishes it from domain-level sibling 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 the operation read-only and idempotent, and the description adds a surprising array-of-arrays response grouping, a 1–3 monthly-bucket date restriction, and a billing rule that counts rows across all groups. These are exactly the kind of non-obvious behaviors an agent needs before invoking.

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 two substantive sentences are dense and valuable, but the opening 'Website Keywords' is a tautological filler that occupies the front-loaded position. It should have been replaced with an actual action 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?

Given the 100% schema coverage, an output schema, and safety-focused annotations, the description covers the remaining non-obvious contract details: date-range span, response grouping, and billing. Nothing needed to call the tool correctly appears missing, though the absent purpose statement lowers the overall completeness.

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?

With 100% schema description coverage, the baseline is met. The description goes beyond the schema by constraining the start_date/end_date span to 1–3 monthly buckets, which cannot be inferred from any individual parameter 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 opening phrase 'Website Keywords' simply restates the title and implies an action only through the tool name. The rest of the description covers response shape and date constraints, not what the tool actually retrieves. It also does not differentiate it from the sibling get_similarweb_keyword_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 guidance is given about when to choose this tool over alternatives such as get_similarweb_keyword_competitors or other SimilarWeb siblings. The date constraint is a precondition for a valid call, not a usage rule.

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, covering the safety profile. The description adds one behavioral detail: the response follows the SimilarWeb v5 envelope (meta + data). This is useful context beyond the annotations, but it does not disclose rate limits, auth, or other operational traits. Given the strong 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?

The description is very short (two sentences), so it is concise, but the first sentence 'Landing Pages' is redundant with the title and adds no value. The second sentence about the envelope is the only useful content. It is front-loaded but under-specified; it is not bloated, but it also doesn't earn all its space.

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 10 parameters, 3 enums, and a clear need to know what data is returned, the description is grossly incomplete. It fails to state the tool's purpose, which is fundamental. Even though an output schema exists, the agent cannot correctly select this tool because it doesn't know what it does. The description is inadequate for a tool of this complexity.

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 every parameter already has a description in the schema. The tool description adds no extra meaning about parameters – it doesn't mention any of them or clarify their semantics beyond what the schema provides. Baseline 3 is correct.

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 simply repeats the title 'Landing Pages' without stating the function. It does not specify that the tool returns landing page data for a domain, and the only additional detail is about the response envelope, which is about format, not purpose. This is a tautology that gives an agent no clue what the tool actually does.

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 alternatives like get_similarweb_popular_pages or other SimilarWeb endpoints. No context is given about use cases, prerequisites, or why an agent would choose this over siblings. The description provides zero directional 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 readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

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 moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap for an agent 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?

The tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics 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 clearly states what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling 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 already declare destructiveHint=true, openWorldHint=true and idempotentHint=false. The description frames the tool purely as a data-returning endpoint ('provides', 'returns'), creating tension with the destructiveHint rather than explaining it, and says nothing about the POST/task-setting nature implied by the title or about side effects.

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, front-loaded with the core purpose, no filler. Slight redundancy in repeating 'for an ad campaign' and 'estimated' twice, but the structure 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 values need no elaboration, yet the description omits what an agent actually needs: the required nested body array, the location_name/location_code/location_coordinate requirement, and how to obtain valid targeting IDs. For a tool with a complex required body and no top-level parameter documentation, 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?

Context reports 0% schema description coverage at the parameter level and the description adds no parameter detail beyond the vague phrase 'based on specified targeting criteria.' It never mentions the required location variant, the array-of-objects body shape, or any of the targeting fields (age, gender, bid, daily_budget, industry, job_function), so it fails to 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 description states a specific verb+resource: it estimates audience size for an ad campaign from targeting criteria, which matches the Bing audience-estimation tool name. It is clear on its own, but it never distinguishes itself from the many sibling audience/keyword endpoints (industries, job_functions, locations) that supply the inputs it needs.

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, and no reference to alternatives. An agent cannot tell from the description that sibling endpoints like get_dataforseo_keywords_bing_audience_industries or ..._locations must be called first to obtain valid industry/job_function/location values.

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 structurally. The description adds useful quantitative bounds (200 keywords in, 3000 suggestions out) but says nothing about task/live semantics, billing, or why a keyword-suggestion call is flagged destructive.

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 short sentences, front-loaded with the action and followed by the input/output bounds. No filler or repetition, though the tense/voice ('This endpoint will select') is slightly verbose.

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 elaboration, and limits are stated. However, for a POST endpoint annotated as destructive and non-idempotent, the description omits any operational context (task setup behavior, cost, credentials), leaving an agent vaguely informed about side effects.

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' parameter is undocumented), but the nested item properties carry very rich inline descriptions for location, language, dates, and device. The description only restates the 200-keyword limit already documented in the schema, adding no new 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?

States a specific verb and resource: selects relevant keywords for supplied ones via Bing Ads suggestions, with concrete limits (200 input keywords, 3000 suggestions). This is enough to distinguish it from siblings like kw_for_url or kw_for_site, though the description never names a sibling to sharpen the contrast.

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. The description explains what the endpoint returns but never says in which scenario an agent should pick this over post_dataforseo_keywords_gads_kw_for_keywords_live or post_dataforseo_labs_google_keyword_suggestions_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 readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds only the 3000-keyword cap and the return content (which the output schema already covers); it says nothing about cost, whether this consumes API credits, error behavior, or the fact that this is a POST that submits work despite the read-like phrasing.

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?

A single front-loaded sentence enumerating what is returned, with the 3000-keyword limit as a tight closing clause. No wasted words, though the entire sentence is spent on output content that the output schema already provides.

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 already exists, so describing return fields is redundant, yet that is all the description does. For a non-idempotent, destructive, open-world POST that requires a body with target plus a location and language specifier, the description omits body construction, async/live semantics, and any cost or failure 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?

The only top-level parameter (body) carries no description of its own, but its nested fields (target, location_*, language_*, date range, sort_by, negatives, etc.) are thoroughly documented inside the schema. The description only hints at 'the specified URL', adding essentially nothing beyond the structured field docs, so the baseline 3 for schema-driven parameter documentation applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: it returns keywords relevant to a given URL with volume, trend, CPC and competition data, and caps the result at 3000 keywords. However, it never distinguishes this from the many near-identical siblings such as post_dataforseo_keywords_bing_kw_for_url_live, post_dataforseo_keywords_gads_kw_for_site_live, or post_dataforseo_keywords_bing_kw_for_keywords_live, so an agent cannot route confidently 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 mention of alternatives, and no prerequisites (credentials, credit consumption, task vs. live behavior). The agent must infer usage purely from the name and the sibling list.

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 discloses crucial behavior beyond the provided annotations: the DataForSEO envelope structure, the fact that a rejected request still returns HTTP 200, and that the tool reads the page itself. These details are essential for correct response handling and are not present in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise yet information-dense, front-loaded with purpose, then covering parameters, response envelope, usage guidance, and async alternatives. Every sentence serves a distinct function, and there is no redundant fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (array body, response envelope, unusual HTTP status behavior) and the presence of an output schema, the description covers all essential aspects: purpose, key parameters, response format, error handling, and sibling alternatives. It is complete enough for an agent to call the tool 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?

The description adds some meaning to `target`, `exclude_brands`, and `language_code` (e.g., 'drops brand terms', 'scopes it'), but it does not explicitly describe the array structure of `body` or mention `language_name`. Since the top-level `body` parameter has no schema description and schema coverage is 0%, the description 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?

The description explicitly states the tool suggests Bing keywords for a single URL by reading the page content, contrasting it with seed-list-based approaches. It names the sibling `post_dataforseo_keywords_bing_kw_for_keywords_live` and explains the distinction, so an agent can easily tell endpoints 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?

It gives explicit when-to-use guidance ('Use it when you have a URL and no keyword list yet') and directs to the keyword-seed sibling when seeds are available. It also explains async submit/fetch twins for large batches, giving a complete decision 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?

The annotations declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, but the description frames the tool purely as receiving stats, implying a safe read operation. This directly contradicts the destructive annotation, and the description does not disclose task creation, costs, authentication, 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?

Two sentences are used efficiently to describe the output metrics and aggregation period, with no obvious filler. It could be more front-loaded with the action (setting a task) rather than the outcome.

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 POST-based live endpoint that annotations mark as destructive and non-idempotent, the description omits critical context: that it sets a live task, how the body array should be structured, and any operational constraints. The output schema exists, so return value details are not needed, but the input and behavioral context are insufficient.

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 0% schema description coverage, so the description should compensate by explaining the required array structure and required fields. It only vaguely references match type, location, and language parameters, adding little beyond the nested field descriptions already present 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?

The description states a specific verb ('receive') and resource ('keyword performance stats for a group of keywords'), and specifies the aggregation scope and device types. It does not differentiate this tool from sibling keyword tools that also return keyword metrics (e.g., search volume or keyword ideas), so it falls short of a 5.

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 the tool returns but gives no guidance on when to use it versus alternatives, no prerequisites, and no exclusions. An agent must infer usage from the output description alone.

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 mark this as readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description reads like a simple data retrieval and omits task-setting behavior, side effects, or billing/auth context. It adds no behavioral context beyond the metric list, and does not contradict the annotations directly.

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 a single focused sentence with little waste, and it front-loads the main output. The parenthetical explanation of trend dynamics is slightly redundant, but overall it is concise and readable.

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 with an output schema available, the description remains incomplete for a POST endpoint with destructive/open-world annotations and a structured body parameter. It explains returned metrics but not invocation context, task-setting semantics, or parameter requirements.

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 reported at 0%, and the description supplies no parameter meaning, required structure, or input format. It does not compensate for the undocumented body array or explain how to specify locations, languages, keywords, or date ranges.

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 returned data: last-month search volume, up to 24 months of trend, CPC, and competition. However, it never names Bing as the source, so it does not distinguish itself from sibling search-volume tools such as 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?

The description provides no when-to-use guidance, prerequisites, or alternative tools. It only describes what data is returned, leaving the agent to infer when this endpoint is appropriate versus other search-volume 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 readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false, so the description carries a reduced burden, yet it adds nothing about authentication, rate/cost limits, or the fact that a POST to a 'Live' endpoint is synchronous. There is also an unaddressed tension: the prose frames the tool as pure data retrieval ('designed to provide ... data') while annotations mark it destructive.

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, front-loaded with the endpoint purpose and capacity limit, no wasted preamble. Slight marketing filler ('What's more') but overall 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 multi-sibling API surface the definition lacks sibling routing, prerequisite guidance, and any behavioral caveats beyond the annotations. Adequate minimum viable, 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 single 'body' parameter wraps a rich nested schema whose field-level descriptions cover keywords limits, tag, and the location_name/location_code either-or requirement. The description only adds the 12-month historical-depth note, which is genuinely beyond the schema, but says nothing about the location requirement or keyword constraints in the 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?

The description names a specific verb/resource ('Bulk Clickstream Search Volume endpoint ... provide clickstream-based search volume data') and states scope limits (up to 1000 keywords in a single Live request). It implicitly separates itself from non-bulk siblings like post_dataforseo_keywords_clickstream_search_volume_live, though it never names an alternative 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?

No when-to-use or when-not-to-use guidance, no mention of prerequisites (auth/credentials), and no routing against the many sibling clickstream/Gads/Trends volume tools. The agent is left to infer selection purely 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 flag non-readOnly, openWorld, non-idempotent and destructive, so the safety profile is carried structurally. The description adds the 1000-keyword request cap and the 'Live' (immediate) behavior, but omits cost/credit consumption, rate limits, and any caveats about what happens on malformed keyword arrays — meaningful gaps for a paid API POST.

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, front-loaded with the endpoint identity and the primary capability. Minor marketing filler ('What's more') costs it a point but the content is dense and non-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?

With an output schema present, return values need not be described, and annotations cover the safety profile. Still missing: differentiation from the two sibling clickstream tools and any mention of cost or the absence of location parameters (implied by 'all available locations'). Adequate but with clear gaps for a tool in a crowded 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?

Schema description coverage is reported as 0% at the top level, so the description should compensate; it only restates the 1000-keyword limit that already appears in the schema. It adds no semantics for the body array shape or the 'tag' correlation field, leaving the nested structure to the schema alone.

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 resource (Clickstream Global Search Volume endpoint) and what it returns (clickstream-based search volume for up to 1000 keywords plus geographic distribution). However, it never distinguishes itself from the closely named siblings post_dataforseo_keywords_clickstream_search_volume_live and post_dataforseo_keywords_clickstream_bulk_volume_live, and the ambiguous 'global' in the name is left unexplained.

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 conditions, and no mention of the competing clickstream siblings. An agent cannot tell from this text whether to pick this tool, the bulk variant, or the search-volume variant for a given request.

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?

Beyond annotations, the description discloses the DataForSEO response envelope (data in tasks[0].result, status in tasks[0].status_code), the fact that rejected requests still return HTTP 200, the cost gap (0.18 vs 0.012), and the batch-call pattern. It does not address the destructiveHint annotation, but it does not contradict it either; the description adds valuable behavioral context without repeating annotation flags.

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 front-loaded with the core purpose, then details returns, size, cost, usage pattern, and envelope. Each sentence adds information, and the structure is logical. The cost warning is somewhat tangential but provides important operational context. It is not overly verbose given the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the schema contains descriptions for most sub-parameters, the description covers the essential aspects: purpose, return fields, response envelope, error behavior, batch usage, and sibling comparison. The main gap is the missing location/language parameter guidance, but the schema partially covers that. Overall, it is nearly complete for an agent to correctly invoke the 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%, so the description must compensate for missing parameter explanations. It explicitly explains 'keywords' and 'use_clickstream', but does not mention the location_name/location_code and language_name/language_code parameters, which are conditionally required. The agent would not learn about the location/language requirement from the description, leaving a significant gap in parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches search volume derived from clickstream panels for a list of keywords, explicitly differentiating it from the gads sibling that measures advertiser-shown volume. It names the specific resource (keywords clickstream search volume) and the verb (post live tasks), leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it contrasts with post_dataforseo_keywords_gads_search_volume_live, explains that one measures clicks while the other measures advertiser exposure, and advises 'one call for many keywords, never one per keyword'. It does not explicitly state when not to use it, but the comparison gives sufficient routing guidance for an agent.

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=false, openWorld=true, idempotent=false, and destructive=true, but the description adds substantial context beyond them: the measured upstream cost versus billed price, the batching cost behavior, the DataForSEO envelope structure, and the fact that rejected requests still return HTTP 200. This is exactly the kind of operational and failure-mode detail an agent needs for a costly queued task.

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 front-loaded with purpose, then cost warning, envelope behavior, and retrieval endpoint. Every sentence adds a distinct operational fact, and the dense structure keeps the agent from missing the key routing and cost constraints.

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 existing output schema and rich annotations, the description is complete enough for correct invocation: it covers purpose, required inputs, cost behavior, response envelope, failure mode, and retrieval path. An agent does not need return-value details in the description because the output schema exists.

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 names the core required fields (keywords, bid, match) and explains that search_partners includes Google's partner network, which matches the schema. It also adds useful batching guidance for the keywords array, but does not compensate for the many optional nested parameters such as date ranges, location, language, and pingback settings that remain documented only 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?

The description states a precise verb and resource: it queues an ad-traffic forecast for keywords at a given bid and match type and returns a task id. It also distinguishes this tool from the live-forecast siblings by noting that this is the only Google Ads endpoint here with no live variant, so an agent can identify it unambiguously.

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 clear usage conditions: send the whole keyword batch in one call because the price does not fall with fewer keywords, and retrieve results with get_dataforseo_keywords_gads_ad_traffic_fetch. It also explains that forecasting always queues here, which is the key routing distinction from live 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 declare openWorldHint=true, destructiveHint=true, idempotentHint=false, and readOnlyHint=false, yet the description adds nothing about cost, latency, authentication, or what a 'live' call actually mutates or consumes. Since the provider claims a destructive, non-idempotent profile for what reads like a data-retrieval operation, the description needed to clarify the side effects and does not — an agent gets no insight into the payoff or risk of calling 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?

Two full sentences are devoted to a legacy AdWords-to-Google-Ads migration notice, which is relevant to API users but pushes the actual purpose into the middle of the paragraph. The description is not bloated overall, but it is not front-loaded with the tool's 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 explained, and the input schema covers the nested fields well. What is missing for a live POST endpoint with a destructive annotation is any note about it being a synchronous, credit-consuming call and what it affects, leaving the behavioral picture 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 single top-level parameter (body) has no schema description, so the description must compensate and does so minimally by stating 'Set up to 20 keywords in the keywords array.' The nested fields are in fact richly documented inside the schema (date ranges, sort_by, location, language), so beyond the keyword-count hint the description adds little the schema does not already carry.

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: 'This endpoint will provide relevant keywords for the specified terms' and 'get keyword suggestions from Google Ads.' That is enough for an agent to know it retrieves keyword suggestions, not volumes or locations. It does not, however, distinguish itself from near-identical siblings such as gads_kw_for_site_live or bing_kw_for_keywords_live, so differentiation is absent.

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 many sibling keyword endpoints, nor any exclusion or prerequisite. The only operational advice ('set up to 20 keywords in the keywords array') restates an input constraint rather than a usage condition, leaving the agent to infer selection criteria from the tool name alone.

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 call as a pure data retrieval ('will provide you with a list of keywords'), while the annotations declare readOnlyHint=false and destructiveHint=true. That is a direct tension between the described read semantics and the declared mutation/destructive profile, so the description actively misleads about the tool's effect.

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 of the three sentences are migration boilerplate about Google AdWords vs Google Ads API that earns no place in a tool definition. The actual purpose is buried last, so the description is neither front-loaded nor waste-free.

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 and annotations exist, and the return data is nicely summarized, but for a tool sitting among dozens of near-identical keyword endpoints the definition omits the differentiation and prerequisite information an agent needs. The migration note consumes the space that should have gone to usage and parameter 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 reported at 0% and the description never mentions a single input (target, target_type, date_from/date_to, location_code, language_code, etc.). The body is an array-of-objects with a required 'target', so the description should compensate for the coverage gap but adds nothing about parameter meaning or required/optional structure.

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 third sentence states a specific verb and resource: it 'will provide you with a list of keywords relevant to the specified domain along with their bids, search volumes ... and competition levels.' That is enough for an agent to know it retrieves site-level keyword data, but it never names the adjacent siblings (gads_kw_for_keywords_live, bing_kw_for_site_live) to draw the boundary 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 / when-not-to-use guidance and no routing against the many sibling keyword endpoints. The only 'guidance' is a migration note about upgrading from Google AdWords to Google Ads API, which does not help an agent decide whether to call this tool.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, yet the description discloses nothing about the write/submit nature, credit consumption, task lifecycle, or what 'destructive' means here. It adds no behavioral context beyond what the annotations already state.

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?

Brief and front-loaded, but every sentence is off-topic; the content is a deprecation notice rather than functional documentation, so nothing earns its place for an agent trying to invoke 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?

For a non-idempotent, destructive task-submission tool with an undocumented body parameter, the description omits everything an agent needs to call it correctly. An output schema exists, so return values need not be explained, but the omission of purpose and behavior is severe.

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 single top-level 'body' parameter is undocumented in the schema (0% coverage), and the description provides no compensating detail about its structure or required 'keywords' array. The nested item fields are well described in the schema itself, which mitigates slightly, but the description contributes 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 never states what the tool does. It is entirely a migration note about the Google Ads API replacing the AdWords API, with no verb, resource, or scope describing the actual operation (setting a Google Ads search-volume task). Only the name/title hint at 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 the many sibling keyword-volume tools (e.g., gads_kw_for_keywords_live, bing_search_volume_live, clickstream variants). The only instruction is an unrelated admonition to upgrade from AdWords.

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 destructiveHint=true, readOnlyHint=false and non-idempotency despite the POST-live naming, but the description never mentions that it creates/charges a task, is non-reversible, or requires billing/auth. It reads like a benign read ('will provide you with'), adding no behavioral context beyond what the annotations already carry.

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, front-loaded with the core capability and the supported engines. No filler, though it is very short relative to the tool's complexity.

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 task-creating POST with mutation annotations the description omits usage context, limits, and behavioral caveats an agent needs before invoking it.

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 mentions nothing about parameters, and only the keyword concept is implied. The nested body schema is itself well documented (dates, location, time_range, tag), so the description neither compensates nor harms; baseline 3 applies.

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 and outcome: a demographic breakdown (age and gender) of keyword popularity per term from DataForSEO Trends, with supported engines named. It is clear, though it does not differentiate itself from closely named siblings such as trends_subregion_interests_live or trends_explore_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 choose this tool over the many sibling trends/keywords endpoints, no prerequisites, and no note on the per-request keyword limit (5) that affects how it is called. The agent must infer usage entirely from the 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 supply the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), and the description adds essentially nothing beyond supported platforms. As a POST/live task-setting endpoint it omits cost-per-request, auth/credential requirements, rate limits, and the fact that it carries destructive semantics per the annotation. The description's 'provides you with data' framing also sits awkwardly beside the destructive annotation, though it is not a direct claim to the contrary.

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, front-loaded with the purpose and zero filler. It is efficient, though arguably too terse for the endpoint's complexity rather than 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 POST live task endpoint with an output schema (so returns need not be described), the description still leaves major gaps: how the body must be structured, cost behaviour, and how it differs from the numerous sibling trends endpoints. It is under-specified relative to the tool's complexity.

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%, so the description is expected to compensate for the single top-level 'body' parameter, and it does not — no explanation of the body array shape, the required 'keywords' field, or the mutually exclusive location_code/location_name and date_from/date_to/time_range options. The nested schema is detailed, 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 states a clear verb+resource: it returns 'keyword popularity data' / 'keyword trends' from DataForSEO Trends. It even names the supported surfaces (Google Search, Google News, Google Shopping). It does not, however, distinguish this 'explore' endpoint from sibling trends tools like post_dataforseo_keywords_trends_merged_data_live or trends_demography_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 choose this tool over its many siblings, nor any prerequisites or exclusions. The only usage-adjacent content is the mention of which Google properties are supported, which is closer to scope than to when-to-use direction.

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; the description adds none of the associated context (that this is a billable live POST, whether it sets a task, cost/rate limits, or auth needs). It spends its text restating return content that the output schema already covers, so it contributes almost nothing behavioral beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler and the core data description front-loaded. It is appropriately sized, but the space is spent on output content the output schema already documents rather than on selection or argument 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?

For a live POST with a required nested body array, a destructive/non-idempotent annotation profile, and dozens of near-identical trends siblings, the definition should at minimum route between them and clarify the request payload. Because an output schema exists, its return-value recitation is redundant, leaving the genuinely needed pieces (selection, prerequisites, body structure) uncovered.

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 single top-level parameter (body, a required array of task objects) has no description in the schema, and per the coverage signal the description does not compensate: it never explains the body array structure, the required keywords field, the 5-keyword cap, or the date_from/date_to/time_range precedence. Vague phrases like 'given time range' and 'each specified term' do not substitute for parameter guidance.

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 popularity data from DataForSEO Trends') and enumerates the three result categories returned (popularity rate over time, location-specific popularity, demographic breakdown). That is more specific than a tautology, but it never identifies this as the 'merged' endpoint relative to nearby siblings like post_dataforseo_keywords_trends_demography_live or post_dataforseo_keywords_trends_subregion_interests_live, so an agent cannot easily tell which trends endpoint 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives, despite roughly a dozen trends/keywords POST siblings that overlap. The description only says what data comes back, leaving tool selection 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 declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, but the description only says the endpoint 'will provide you with data', which reads like a harmless retrieval. It does not disclose that this creates a live task, whether the call consumes credits, whether it is billable/idempotent, or what side effects the destructive hint implies. The tension between 'provides data' and destructiveHint=true 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?

Two short sentences, front-loaded and free of padding, which is good. But the brevity comes from under-specification rather than economy: the space saved is not spent on the constraints an agent actually 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?

An output schema exists, so return values need not be explained. Still, for a live-task POST with destructiveHint=true and 0% schema coverage, the description omits the task/async nature, credit or auth implications, and the subregion-interest scope that makes this endpoint distinct. What remains is too thin to call it correctly against ~40 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%: the required 'body' array has no description at all. The description adds no parameter meaning beyond indirectly hinting at the 'type' values (Google Search / News / Shopping) without saying they map to a field, and says nothing about keywords, date ranges, location_code/location_name, or the 5-keyword limit.

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 ('location-specific keyword popularity data from DataForSEO Trends') and the three surfaces (Google Search, News, Shopping). However, it never mentions 'subregion interests', the distinguishing feature in the tool name, and reads nearly identically to siblings like post_dataforseo_keywords_trends_explore_live, _demography_live, and _merged_data_live. An agent cannot tell from the text why it would pick this endpoint over those.

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 when to prefer live/subregion interests over the other trends endpoints, and no note of the task-creation semantics implied by the 'post'/'Setting Live Tasks' framing. Usage must be inferred entirely from the 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?

The annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds no behavioral context beyond that: it does not mention credit consumption, rate limits, authentication requirements, or why a read-like metric call is flagged as destructive. The explanation of the metric scale is domain semantics, not operational 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 description is front-loaded with the core capability and then defines the metric in a compact paragraph. It is appropriately sized for an API endpoint and contains little filler, though the second sentence explaining keyword difficulty is somewhat verbose relative to its value for selecting 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?

Given the nested array schema, required location/language pairs, live billing implications, and the presence of sibling tools, the description is incomplete. It omits usage routing, cost/auth context, and any mention of required parameters. Output schema existence means return values need not be explained, but the remaining gaps are substantial for a live, mutating-priced endpoint.

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 as 0% at the parameter level, and the top-level body parameter has no description at all. The description does not compensate: it never mentions the body array, the required location_name/location_code and language_name/language_code combinations, or the keywords field. The only numeric detail (1,000 keyword maximum) is already present in the nested schema 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 states a specific verb and resource: it provides the Keyword Difficulty metric for up to 1,000 keywords in one API request. It clearly explains what the metric represents (relative difficulty of ranking in top-10 organic results on a 0–100 logarithmic scale). However, it does not distinguish this tool from any sibling, such as get_semrush_keyword_difficulty or the numerous other DataForSEO keyword endpoints.

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 contains no when-to-use guidance, no prerequisites, and no mention of alternatives. It never says when an agent should call this bulk endpoint versus a single-keyword tool or the Semrush keyword difficulty endpoint. Usage is left entirely to inference from the 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?

The description frames this as a pure data-retrieval endpoint ('will provide you with ... categories'), while annotations declare readOnlyHint=false and destructiveHint=true. That is a direct conflict about the tool's side-effect profile, leaving the agent unable to trust either signal.

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, no padding, with the core purpose front-loaded. It could be tightened further but is well within acceptable size.

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 function of the tool is conveyed. However, given the annotation conflict and the absence of any routing guidance against the inverse sibling, the definition is not fully complete for confident 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?

There is one parameter (the body array), and the nested schema already documents keywords, language_code, language_name, and tag thoroughly. The description adds the 1,000-keyword request cap, which is marginally useful, but otherwise repeats schema content — adequate, not rich.

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 Google product/service categories for each specified keyword. The purpose is clear, but it does not distinguish itself from the sibling post_dataforseo_labs_google_keywords_for_categories_live, which performs the inverse mapping (keywords for a category) — an easy confusion for an agent scanning sibling names.

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 the inverse sibling, and no prerequisites. The only operational constraint given is the 1,000-keyword limit, which is usage hygiene rather than 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?

The description adds real behavioral context the annotations do not: data coverage starts August 2021 and results depend on the location/language combination. However, it says nothing about cost/credits or rate limits, and the annotations (destructiveHint=true, idempotentHint=false) sit uneasily with a read-style data retrieval description without explanation.

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 metric list is front-loaded and the description is short and readable. The closing sentence 'You can find the list of supported locations and languages here' is a dangling reference that adds little value, slightly reducing the score.

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 the description covers scope (since August 2021) plus the metrics returned. The main missing element is routing guidance relative to the many sibling keyword endpoints, which is handled under usage guidelines.

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?

With reported schema description coverage at 0% and a single body-array parameter, the description only partially compensates by noting that location and language combinations are inputs and that a keyword list is required. It adds no syntax, format, or cardinality detail (e.g., the 700-keyword cap) beyond what the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource combination (historical Google keyword data per keyword) and enumerates the returned metrics (search volume, CPC, competition, monthly searches, trends). It implicitly distinguishes itself from the current-state siblings like keyword_overview and keyword_ideas by emphasizing 'historical', though it never names 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 explicit when-to-use guidance. Given numerous sibling keyword tools (keyword_overview, keyword_ideas, trends_explore, related_keywords), the agent is left to infer that this one is for historical/time-series data. No conditions, prerequisites, or exclusions 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 (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false) carry the behavioral profile, and the description adds nothing beyond them. It doesn't disclose that this is a costed/paid POST endpoint, that pagination uses offset_token, or why a keyword-lookup carries a destructive/cost implication. The schema mentions the double-charge for clickstream data, but that is not in the description.

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 with no filler, front-loaded with what the endpoint returns and followed by the selection rationale. Efficient, though the second sentence is more about the vendor's algorithm than about helping an agent invoke 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?

For a complex, multi-parameter paid endpoint (location requirement, filters, order_by, pagination token, costed flags), the description is far too thin. Output schema exists so return values needn't be explained, but the operational context -- cost, location requirement, pagination -- is entirely 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?

Reported schema description coverage for the top-level 'body' parameter is 0%, so the description is expected to compensate, and it only says keywords are 'specified in a POST array.' It adds no meaning about required location_name/location_code, keyword limits, or filter/sort options that an agent needs before constructing the request.

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 ('search terms relevant to the product or service categories') and explains the selection algorithm (categorizing seed keywords), which is clearer than a tautology. However, it never distinguishes itself from close siblings like post_dataforseo_labs_google_keyword_suggestions_live or post_dataforseo_labs_google_related_keywords_live, so an agent can't tell which to pick 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, when-not-to-use, or alternative-tool guidance. The description explains the internal algorithm but gives no signal about when an agent should choose Keyword Ideas over Keyword Suggestions or Related Keywords. This is simply absent.

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). The description adds the return-field inventory and notes that include_clickstream_data bills at double price — useful, cost-bearing context — but it never addresses the non-readonly/destructive hint or auth/side-effect implications, leaving a gap between what it says (data retrieval) and what the annotations imply.

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, front-loaded with purpose and free of padding, but the second sentence is largely a metric enumeration that duplicates the output schema's job rather than earning its place.

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, yet the description still recites them. Against a 1-body-param tool with annotations and a sibling set of competing keyword tools, the missing usage routing and the un-noted read-vs-destructive tension leave it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The top-level 'body' parameter has no schema description (0% coverage at that level), though the nested properties are richly documented in the schema. The description adds meaning only for include_clickstream_data; it says nothing about the keyword/location/language requirements, so it neither compensates for nor exceeds 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+resource ('provides Google keyword data for specified keywords') and enumerates the metric categories returned, so the resource is unambiguous. However, it never distinguishes this from the many sibling keyword tools (keyword_ideas, keyword_suggestions, related_keywords, bulk_keyword_difficulty, historical_keyword_data), which an agent must choose among.

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 'for specified keywords' weakly implies usage, but there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives despite a dense keyword-tool sibling set. Comparable to the MID calibration where no prerequisites or alternatives 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 readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is carried by structured data. The description adds which metrics come back, but omits commercially important behavior disclosed only in the schema (double billing with clickstream) and any pagination/limit caveats. There is a mild tension between the read-flavored wording ('provide you with a list') and destructiveHint=true, though the annotation is plausibly a conservative POST/quota convention rather than an outright conflict.

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, front-loaded with the core purpose and then the return payload; no filler or repetition. It could have used the same space to add a routing hint, but nothing written is 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?

For a paid, credit-consuming endpoint with required location/language pairs, a 20-category cap, and a 10,000-result pagination boundary, the description covers none of these operational facts. The output schema exists, so return-shape explanation is not required, but the invocation-critical context 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 description mentions only 'specified product categories' and says nothing about the required location_name/location_code and language_name/language_code constraints, filters, or offset_token. Schema description coverage is reported at 0% for the single top-level body parameter, but the nested property descriptions in the schema are unusually thorough, so the practical documentation burden is largely already met.

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 (provide) and resource (keywords relevant to the specified product categories) and even enumerates the returned metrics (search volume, 12-month trend, CPC, competition). It is clearly distinguishable from the reverse-direction sibling categories_for_kw. However, it never explicitly contrasts itself with near-neighbors such as keyword_ideas or keyword_suggestions, which also return keyword 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?

There is no when-to-use guidance, no statement of prerequisites (e.g. that category codes must be obtained separately), and no mention of the alternatives in the sibling set. The agent must infer all selection context from the endpoint name alone.

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 are present but terse (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), and the description adds nothing behavioral on top of them. For a 'live' task-based endpoint that consumes API credits and can charge double when include_clickstream_data is enabled, cost/async/permission context would be valuable and is entirely absent.

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 clean, front-loaded sentence with no filler or repetition of the schema. It is efficient, though its brevity borders on under-specification rather than true economy.

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?

Placeholder — see corrected value below.

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 coverage is 0%, so in principle the description must carry parameter meaning, and it adds none. In practice the nested body-item schema documents keyword, limit/offset, offset_token, filters, order_by, language/location and the include_* flags in detail, so the agent is not left blind here — but the prose itself contributes zero parameter guidance.

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?

It states a concrete verb and resource: the endpoint returns search queries containing a specified seed keyword. That is more specific than a tautology and implies the seed-keyword expansion behavior. It does not, however, distinguish itself from close siblings such as keyword_ideas or related_keywords, which an agent would need to choose between.

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-tool guidance. Nothing tells the agent whether this is preferable to google_keyword_ideas or google_related_keywords, nor when a caller should reach for this endpoint at all.

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 as a data retrieval endpoint ('provides keywords', 'You can get up to 4680 keyword ideas'), but the annotations declare destructiveHint=true and readOnlyHint=false. This is a direct mismatch that can mislead an agent about the operation's 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?

The description is reasonably front-loaded with purpose first, followed by depth and output details. However, the sentence 'View the element.' is extraneous and confusing, and it does not clearly earn its place.

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 complex endpoint with a contradictory annotation set and an opaque top-level parameter, the description is incomplete. It does not clarify prerequisites, usage conditions, or the destructive annotation, and it redundantly explains return fields despite an output schema being present.

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 sole 'body' parameter. The description mentions search depth and max results, but it does not compensate for the missing top-level documentation of required keyword/location/language fields or the array/task structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: it provides keywords from the 'Searches Related to' SERP element, with a max of 4680 ideas via search depth. It is clear what the endpoint does, but it does not distinguish this tool from sibling keyword_ideas_live or keyword_suggestions_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 when-not-to-use guidance, and no named alternatives. The description only summarizes what the endpoint returns, leaving the agent to infer appropriate 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 carry the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds the meaningful output behaviour (primary intent plus secondary intents with probabilities), but says nothing about billing/credit consumption, auth requirements, or why a data-returning endpoint is flagged destructive, 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?

Three sentences, reasonably front-loaded, but the second and third largely duplicate what the output schema already conveys about returned intent probabilities. 'For each keyword that you specify when setting a task' is also inaccurate for a live endpoint and adds 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 the description need not explain return values, yet it spends most of its length doing exactly that. For a paid, open-world POST endpoint with a body-only parameter contract, the description omits the practically important context: required language specification, credit cost, and any batching limits.

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 single top-level parameter (body) has no description at all, though its nested properties are richly documented in the schema (tag, keywords, language_code, language_name). The description only restates the 1,000-keyword cap already stated in the schema and adds no new detail about the language requirement or payload shape, so it neither compensates for the top-level gap nor adds value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns search intent and intent probability for a specified set of keywords. That is unambiguous and more specific than most siblings (e.g. keyword_overview, keyword_ideas). It does not, however, draw any contrast against the many other Labs keyword endpoints that an agent must choose between.

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 is returned but never when to prefer this endpoint over siblings such as google_keyword_overview or google_historical_keyword_data, nor does it state exclusions or prerequisites. The phrase 'when setting a task' is the only usage hint and it is ambiguous for a 'live' endpoint.

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 supply a safety profile (though destructiveHint=true is odd for a read query), so the bar is lower. The description adds what data is returned but omits the operationally critical behavior: the 1000-result cap, pagination via offset_token, and that requesting >10,000 results requires it. It never contradicts the annotations, but it leaves the pagination model undisclosed.

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, front-loaded with the endpoint name, but the 'over 7 billion keywords' figure is promotional padding that consumes space without helping an agent call 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-shape explanation is unnecessary, but the description omits usage context, scope selection, and pagination constraints for a live data endpoint that can be called in several ways. Given the complexity of the body schema, 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?

Top-level schema description coverage is 0% and the description offers no parameter guidance at all — not location/language requirements, not limit/offset behavior, not the offset_token precedence rule. Although the nested body schema is detailed, the description fails to compensate for the undocumented top-level parameter.

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 identifies the endpoint and that it returns keywords with Google Ads metrics, product categories, and SERP data, but it is phrased as marketing copy ('can provide you with over 7 billion keywords') and never states what a 'top search' actually is or how scope (location/language) defines the result. It is distinguishable from Bing/GAds siblings only by the DataForSEO Labs branding, not by an explicit contrast.

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 alternatives named, despite many sibling keyword tools (keyword_ideas, keyword_suggestions, related_keywords, gads_kw_for_keywords). The agent gets no signal for choosing this endpoint over a near-identical sibling.

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 discloses meaningful behavior beyond annotations: search spans the entire AIsa catalogue, candidates may belong to modules other than the current one, multiple providers for the same metric are surfaced, and no API key is required. This gives the agent a clear picture of scope and output 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 description is front-loaded with the core purpose and is dense with useful information: scope, no-auth requirement, response shape, and relationship to the catalogue. Each sentence adds operational value, and the structure makes the tool's behavior predictable.

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 complex discovery tool with output schema, the description is unusually complete: it explains the response modalities, candidate fields, direct pass-through to `use`, full-catalogue search behavior, and cross-provider visibility. An agent has enough context to invoke and interpret the tool 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining that the category parameter is not a hard boundary—search spans the full catalogue—and that queries are plain-language task descriptions, which clarifies how to use the tool effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds AIsa data operations across many categories via a plain-language query. It distinguishes itself from siblings like get_details and use by emphasizing that search covers the full catalogue, not just the pinned category.

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 conveys when to use search: when you need to discover operations across the full catalogue, even those not in the current tools/list. It also implicitly contrasts with get_details by noting that returned candidates already include input_schema, so they can be passed directly to `use` without an extra call.

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

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

Annotations already provide readOnly=false, openWorldHint=true, and destructiveHint=true. The description adds valuable behavior beyond that: billing per call, the BatchCallResult response shape, and the error structure with retryable status. It does not spell out side effects, but the destructive flag is already carried by annotations, so the additional context is sufficient.

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 short sentences, each earning its place: purpose, cost, response shape, and routing guidance. Key behavioral facts are front-loaded, and nothing is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists and all parameters have descriptions, the tool description is complete enough for correct invocation. It covers cost, return/error contracts, and how routing to this tool differs from calling pinned tools directly, leaving no practical 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?

Schema description coverage is 100%, and each parameter is already clearly documented: operation_id as returned by search, search_id provenance, arguments matching input_schema, and max_price_usd as a spend guard. The description does not need to add parameter detail, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Execute one AIsa operation,' a specific verb+resource statement. The word 'one' distinguishes it from the sibling batch_use, and the closing note distinguishes it from calling pinned tools directly. An agent can tell what this tool is for immediately.

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 explicitly states when to use the tool: 'this is the way to call anything found through search.' It also gives the alternative: 'Pinned tools in tools/list can also be called directly.' This is clear when-versus-alternative guidance with no ambiguity.

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