AIsa Domain & Keyword Research

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context by disclosing the $0.02 per-call billing and that 4xx/5xx responses are not charged.

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

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

Two tight sentences deliver the core behavior and the billing caveat with no filler. The main purpose is front-loaded and every clause adds information.

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

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

For a simple read-only tool with only two required parameters, an output schema, and rich annotations, the description is complete: it states the returned metrics, target/date scope, and cost behavior. 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 'target' and 'date' are already fully documented in the schema. The description restates these concepts without adding new format, default, or edge-case details, so 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 names a specific verb ('Return'), a specific resource (Ahrefs Domain Rating and Ahrefs Rank), and the exact scope (target domain, given date). It clearly differentiates from siblings like get_semrush_domain_overview and get_similarweb_ranking by calling out the Ahrefs-specific metric.

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 choose this tool over the many sibling SEO/metric tools, nor does it mention exclusions or alternatives. The use case is only implied by the Ahrefs-specific naming.

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, openWorldHint, idempotentHint, and destructiveHint false, so the description's burden is lighter. It adds meaningful behavioral context: the $0.18 per successful call charge and that 4xx/5xx errors are not billed, which informs cost-aware invocation beyond what 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?

Two tight sentences with no filler. The first sentence leads with the action and enumerates the returned metrics; the second adds the billing caveat. Every 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, two-parameter lookup with an output schema, the description covers the essentials: the action, parameters, and cost behavior. The 4xx/5xx note partially addresses error responses, though a brief mention of invalid-target behavior would make it fully complete.

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

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

Schema description coverage is 100%, and both required parameters (target, date) are already documented with formats and examples. The description restates 'target domain' and 'given date' but adds no new semantic detail beyond the schema.

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

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

The description clearly states 'Return core Site Explorer metrics' for a target domain and enumerates the exact metrics (organic/paid keyword counts, top-3 keyword count, organic traffic, traffic value), making the resource and scope precise. However, it does not explicitly contrast with sibling tools like get_ahrefs_domain_rating, 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?

No guidance is given about when to choose this tool over alternatives; it doesn't mention any sibling, exclusion criterion, or prerequisite. The only extra context is billing, which is not usage direction, leaving selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and an output schema exists, so safety and return shape are covered elsewhere. The description adds no behavioral detail beyond that — no note on scope (per-endpoint vs global filter set), caching, or stability.

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 short sentence, so there is no bloat, but 'all the necessary information about' is filler that could be replaced with a concrete statement of what is returned. Structure is fine, content is thin.

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

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

With no parameters, full annotation coverage, and an output schema, the minimum needed is a clear statement of what the tool yields. The description conveys that it returns available filters, but doesn't say whether they are global or keyed by endpoint, leaving a small gap for a discovery 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 takes zero parameters, so the schema carries no semantic burden; baseline 4 applies. Nothing in the description needs to compensate.

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

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

States the resource precisely: available filters usable with DataForSEO Labs endpoints. The verb is implied rather than explicit ('Here you will find'), and the phrasing is padded with 'all the necessary information,' but an agent can tell this is a lookup of supported filter definitions and it doesn't collide with any 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?

Usage is only implied: an agent should infer this is called before building a filtered DataForSEO Labs query to learn valid filter fields/operators. No explicit when-to-use, prerequisites, or mention of which endpoints the filters apply to.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, but the description adds no behavioral context at all: no rate limits, no indication of result size, no mention of whether the list is stable or API-specific.

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 no padding, and the purpose is front-loaded. Minor redundancy/awkwardness in 'you will find obtain' costs a point.

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 with an output schema present, the description need not explain return values. It correctly ties the result to the date fields it feeds, leaving only minor gaps about calling frequency.

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 4 applies; there is nothing for the description to clarify 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: returns the list of dates usable in the first_date/second_date fields of the Domain Metrics by Categories endpoint. This distinguishes it from most siblings, though the wording is clunky ('you will find obtain').

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 implies when to call it by naming the consumer endpoint (Domain Metrics by Categories), but gives no explicit when-to-use/when-not guidance and names no alternative among the many sibling tools for the same purpose.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds that the response yields per-provider (Google/Bing/Amazon) update dates, but since an output schema exists, that detail is somewhat duplicative. No extra behavioral context such as auth or rate limits.

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

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

Two short sentences, front-loaded with the outcome. The lead-in 'By calling this endpoint' is slightly redundant filler but overall the description is tight.

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

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

For a zero-parameter status endpoint with full annotation coverage, an output schema, and a clear description of the returned data, the definition is essentially complete. Minor absence of explicit usage guidance keeps it just short of a 5.

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 clarify 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?

States a specific verb+resource: retrieving the last-updated date for DataForSEO Labs data, with scope narrowed to Google, Bing, and Amazon endpoints. It is clearly distinct from the many post_dataforseo_labs_* query tools, though it does not name them explicitly.

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

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

Usage is implied ('By calling this endpoint, you will find out...') but there is no explicit when-to-use, when-not-to-use, or alternative routing guidance. The context is inferable from the tool's nature but 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 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 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?

Annotations already mark the tool as readOnly, idempotent, and non-destructive, and the description adds genuinely useful behavioral context: it is billed $0.09 per successful call, 4xx/5xx responses are not charged, and the response is semicolon-delimited text. These are non-obvious facts an agent needs before calling.

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 no filler: the core purpose is front-loaded, followed by billing terms and response format. Every 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?

With a rich output schema, strong annotations, and an output schema present, the description covers the remaining operational context: cost, error billing behavior, and response format. Nothing required to safely call the tool correctly is missing.

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

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

Schema description coverage is 100%, with domain and database already documented with examples and a default. The description restates the regional-database idea but does not add parameter-level meaning or constraints beyond what the schema provides, so the 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 uses a specific verb ('Return'), a clear resource ('organic search overview for a domain'), and enumerates the exact metrics returned. This lets an agent distinguish it from sibling tools like get_semrush_backlinks_overview or get_semrush_keyword_overview.

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

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

The intended use case is implied: retrieving domain-level organic search metrics for a given regional database. However, there is no explicit when-to-use guidance or exclusions compared to sibling SEMrush or Ahrefs tools, so the agent must infer routing.

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?

Beyond the annotations, which already mark the call as read-only and nondestructive, the description discloses important behavioral traits: per-row billing at $0.09, a 20-row cap with header row excluded, that 4xx/5xx are not charged, and that the response is semicolon-delimited text. This is unusually transparent about cost and response format.

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, each earning its place: the first states the core function, the second covers the critical billing behavior, and the third discloses the response format. The most differentiating information is front-loaded and there is no filler.

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

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

Given the annotations already establish safety and idempotency, an output schema exists for return values, and the parameter schema covers the required inputs, the description fills the remaining gaps: pricing, row limits, error-charge behavior, and text delimiter format. Nothing needed to call this tool correctly is missing.

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

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

The schema already documents both parameters (domain and database) with examples, so schema_description_coverage is 100%. The description adds no additional semantics about how domain or database values should be formatted beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific deliverable — 'Historical rank, organic traffic and keyword-count trajectory for a domain' — with a clear resource and scope. This differentiates it from siblings like get_semrush_domain_overview and get_semrush_domain_organic_keywords, which are not historical trajectory tools.

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

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

The 'Historical ... trajectory' phrasing implies this is for time-series domain metrics rather than current overviews or keyword lists, but the description never explicitly says when to use this tool versus the many Semrush/DataForSEO siblings. There are no exclusions or alternative tool mentions, so usage guidance is only implied.

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 context beyond annotations: billing per returned data row at $0.72, a 20-row cap, that 4xx/5xx responses are not charged, and that the response is semicolon-delimited text. This is exactly the kind of cost and format disclosure that helps an agent anticipate consequences.

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. The core purpose is front-loaded, followed by the most decision-relevant operational details (billing, row cap, error charging, response format). Every 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?

The tool has an output schema, so return values need not be described. The description covers purpose, cost, row limit, error billing, and response format. The only minor gap is that it doesn't explain the 'domains' comparison spec syntax, but the schema already does that with a clear example. For a read-only, idempotent tool with full schema coverage, this is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add parameter-level detail beyond the schema, but it does clarify the output is semicolon-delimited text, which indirectly helps interpret the 'domains' parameter. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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: 'Cross-domain keyword position comparison across up to 5 domains.' This clearly distinguishes it from sibling tools like get_semrush_domain_organic_keywords (single-domain keyword lists) and get_semrush_organic_competitors (competitor discovery). It doesn't explicitly name a sibling, but the scope is clear enough.

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 for comparing keyword positions across domains, but it does not explicitly state when to use this tool versus alternatives like get_semrush_domain_organic_keywords or get_semrush_organic_competitors. The billing note gives a practical constraint (cost per row), which helps an agent decide whether to call it, but there is no explicit when/when-not 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 substantial behavioral context beyond the annotations: per-row billing, a 20-row cap, no charges for 4xx/5xx responses, and semicolon-delimited text output. These details are not present in any structured field and are critical for cost-aware invocation.

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/limits, and response format. It is front-loaded with the core purpose and contains no filler or repetition.

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

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

For a low-complexity tool with two primitive required parameters and an output schema, the description covers everything an agent needs: what it returns, cost constraints, row limits, and response formatting. 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?

Schema coverage is 100%, with both `domain` and `database` having descriptions and examples. The description does not add parameter-level meaning beyond the schema, so 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 clearly identifies the resource ('domains competing with a target') and the context ('Google organic search'), which distinguishes it from SEMrush backlinks, domain overview, and Similarweb tools. However, it lacks an explicit verb like 'Returns' or 'Lists,' so it falls just 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 intended use case is implied: use this when you need domains competing with a target in Google organic search. But the description never explicitly states when to prefer this over sibling tools such as get_similarweb_keyword_competitors or get_semrush_domain_overview, and gives no exclusion criteria.

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 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?

The description frames the endpoint as returning search volume values, a read-style data retrieval, while annotations declare readOnlyHint=false and destructiveHint=true. That mismatch is a serious inconsistency, so behavioral transparency is low despite annotations otherwise being present.

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 tightly written sentences: purpose first, search-volume definition second, parameter scoping third. No filler or repetition.

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

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

The description covers purpose, return-value nature, and limits, and an output schema exists so return format need not be explained. However, it does not address the destructive annotation or provide routing guidance among siblings, leaving gaps for an agent choosing this 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 description mentions the key dimensions (keywords, location, language) and the 1,000-keyword cap, but adds no syntax or format detail beyond the nested schema. With top-level schema coverage reported at 0%, it partially compensates but leaves field-level specifics to the schema.

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

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

The description names the specific operation (provide search volume values), the resource (keywords on Amazon), and the scope (maximum 1,000 keywords per request). It does not explicitly differentiate from the many Amazon-related sibling tools, but the bulk-volume purpose is clear.

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

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

No when-to-use guidance, no alternatives among the many sibling endpoints, and no prerequisites. The description only describes the operation, leaving the agent to infer that it is for bulk Amazon keyword search volume.

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 describes a pure data retrieval ('provide you with a list'), which sits in tension with annotations declaring readOnlyHint=false and destructiveHint=true; an agent relying on either signal alone would get the wrong safety picture. Beyond that conflict it adds only that results are scoped to asin/location/language, with no auth, rate-limit, or pagination 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?

Three short sentences, front-loaded with the core action, no filler. The third sentence is mildly redundant with the second but does carry the scoping qualifier.

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

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

An output schema exists, so return values need not be explained, and the description covers the core purpose and key inputs. However, for a live filtering/sorting endpoint with a wrapped array 'body' parameter, the absence of auth, cost, or pagination guidance leaves 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 description names the operative inputs (asin, location, language, and that they are sent in a POST request body), which is useful given the schema's literally 0% top-level description coverage on 'body'. It says nothing about limit/offset/filters/order_by/tag, so it only partially compensates 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?

States a specific verb and resource: it returns 'a list of products that intersect with a target asin in Amazon SERPs', which lets an agent distinguish it from Amazon siblings like rank_overview, kw_overlap, and ranked_keywords. It does not explicitly contrast itself with those siblings, so it stops 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 line 'can help you identify product competitors for any listing published on Amazon' implies the use case (competitor discovery for an ASIN), but there is no explicit when-to-use/when-not guidance, prerequisites, or naming of an alternative endpoint. Usage is only implied.

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 thin in usefulness (readOnlyHint=false, destructiveHint=true, openWorldHint=true) and read like generic POST-wrapper defaults rather than meaningful disclosure. The description does nothing to elaborate on behavior: no mention of the location restrictions (US, Egypt, Saudi Arabia, UAE only), rate limits, cost, or that this is a live call against an external API. It adds only the fact that results are keyed to the submitted ASINs.

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 the purpose front-loaded and no redundant filler about return format. The closing 'Learn more about ASIN in this help center article' is low-value boilerplate that could be cut, slightly reducing efficiency.

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 the schema covers parameters. However, for a live external-API call with meaningful behavioral caveats (supported locations, live vs cached, potential charges), the description omits context an agent would want. It is adequate but not complete for this endpoint'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?

The exposed parameter surface is the single 'body' array, and the description only signals the ASIN concept ('products', 'asins'). It says nothing about the nested controls (limit, offset, filters, order_by, location, language, intersection_mode) that the schema itself documents reasonably well. As a result the description adds marginal semantic value beyond the structured fields, matching a baseline 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?

The description gives a specific verb and resource: it returns keywords on which the target Amazon products intersect in SERP, scoped to the supplied ASINs. This is clearer than a bare restatement of the title and distinguishes it from the Apple/Google intersection siblings by naming Amazon and products. It stops short of naming any specific alternative tool or clarifying how it differs from amazon_product_competitors_live or amazon_ranked_keywords_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 prerequisites, and no mention of alternatives despite many closely named amazon_* siblings. The only usage hint is that results are tied to the ASINs in the POST body, which is inferred from the schema rather than stated as guidance. An agent is left to guess why it would pick this over the competitor or ranked-keywords 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 readOnly=false, destructive=true, openWorld=true, idempotent=false, which is a suspicious profile for a live data-retrieval endpoint, and the description neither confirms nor clarifies it. Beyond that, it adds no behavioral context such as per-request cost, rate limits, or that this is a synchronous live call rather than a 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?

Purpose is front-loaded in the first sentence, which is good, but the second sentence restates the obvious (results depend on the POSTed asins) and the third is a link-only filler that spends space without informing invocation.

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 schema documents the nested request fields well. However, with dozens of near-identically named Amazon Labs siblings, the description is too thin on routing and on the surprising destructive annotation to be fully 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 description reinforces that results are keyed to the asins array supplied in a POST body, but adds no syntax or constraints beyond the schema (uppercase ASIN format, 1000-item cap, location/language requirements all live in the schema's nested field descriptions). Top-level body has no description, so compensation is limited.

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: provides ranking data from organic and paid Amazon SERPs for target products, scoped to asins. Clear on what it returns, but gives no differentiation from similarly named siblings such as post_dataforseo_labs_amazon_ranked_keywords_live or post_dataforseo_labs_amazon_product_competitors_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?

No guidance on when to use this endpoint versus the many Amazon Labs siblings (competitors, kw overlap, ranked keywords, bulk volume). No prerequisites, cost, or freshness notes are given; the agent must infer selection from the 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 declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, idempotentHint=false, so the description should explain cost/auth/side-effects of this live billable call; instead it only says 'will provide you with a list'. A live ranking call needs notes about rate limits, pricing, or supported locations, none of which appear here.

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 with the purpose, but the trailing 'Learn more about ASIN in this help center article' is filler that neither routes the agent nor adds invocation 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 live, destructive, open-world POST endpoint with a rich nested body schema and required location/language constraints, the description leaves out geography limitations, cost implications, and how to enable the required fields. An output schema exists so return-value description is not expected, but the input side remains under-explained.

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

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

The schema itself carries detailed descriptions for every field (0% 'schema coverage' reflects a schema that nonetheless documents all properties inline). The tool description contributes nothing beyond 'asin', and even omits the required location_name/location_code and language_name/language_code constraints, so it fails to compensate for what an agent needs 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+resource: returns keywords a target product ranks for on Amazon, scoped to the ASIN in the POST body. It is distinguishable from the sibling product_competitors or related_keywords by the 'ranked keywords for this product' framing, though it never names those siblings.

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

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

No when-to-use or when-not-to-use guidance, no exclusions, and no reference to alternatives like post_dataforseo_labs_amazon_related_keywords_live or product_competitors_live. The description merely asserts what the endpoint returns.

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 presents a read-only data retrieval ('provides keywords'), but annotations declare destructiveHint=true and readOnlyHint=false. This directly conflicts with the implied read-only nature of the operation and leaves the agent with no additional behavioral context.

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

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

A single, front-loaded sentence with no filler or redundancy. It is appropriately sized for a concise purpose statement, even if other dimensions need more content.

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 complex nested schema and required location/language constraints, the one-sentence description is far too sparse. It omits required-input guidance and supported locations, though an output schema exists so return values need not be explained.

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% for the sole top-level parameter (body), and the description adds no parameter semantics at all. While nested item properties carry detailed schema descriptions, the definition fails to compensate for the missing body documentation or explain required location/language/keyword 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 resource (keywords appearing in Amazon's Related Searches) and distinguishes itself from the sibling Google related-keywords tool by naming Amazon. It is clear but does not clarify that input is a seed keyword or mention any filtering dimensions.

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

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

No when-to-use guidance, no alternatives, and no exclusion criteria are provided. An agent cannot tell from this description whether to choose it over post_dataforseo_labs_google_related_keywords_live or other Amazon keyword tools.

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

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

The description frames this as a pure information retrieval endpoint ('will provide you with a list', 'you will obtain the IDs'), yet the annotations declare readOnlyHint=false and destructiveHint=true. This is a direct conflict between the stated read-only behavior and the structured safety profile, with no reconciliation or warning 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 tight sentences, front-loaded with the core purpose and followed by the output summary. No filler, no repetition of the title.

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

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

An output schema exists, so return values need not be re-explained, and the description already sketches the payload. However, for a live endpoint with a required body object and singleton English/US constraints (documented only in the schema), the description omits prerequisites, pagination defaults, and the destructive/read-only ambiguity, leaving it only minimally sufficient.

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 no parameter guidance at all; it only paraphrases the returned fields. The nested request-body properties (app_id, location/language pairs, filters, order_by) are actually well documented inside the schema, so an agent can still build a call, but the prose itself contributes nothing to parameter meaning or defaults.

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 a list of mobile apps that intersect with the target app for its App Store ranking keywords, plus competitor IDs, search volume and ranking data. That is enough to distinguish it from generic siblings, though it never names the closest alternatives (apple_app_intersection_live, keywords_for_app_live, google_app_competitors_live) to sharpen the boundary.

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 prerequisite note (e.g. that the target app must first be resolved to an app_id), and no comparison against the sibling competitor/intersection/keywords tools. The agent must infer usage entirely from the name and purpose statement.

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 (destructiveHint=true, readOnlyHint=false, non-idempotent, open world), so the safety profile is roughly covered, but the description adds nothing beyond purpose. It omits that this is a live-payable request, that app_ids is required with a max of 20 IDs, and the US/English-only restriction noted in the schema.

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 clean sentence with no filler, front-loaded on the outcome. It is efficient, though it is under-specified rather than over-long.

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?

Return values are covered by the output schema, but for a live POST endpoint whose single body parameter carries many nested fields, the description is too thin: no usage context, no constraints, and no differentiation from the many sibling labs endpoints.

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 only one top-level parameter (body) and reported schema description coverage of 0%, the description should carry the load, yet it mentions only the app_ids object and ignores filters, order_by, limit/offset, and the location/language constraints that live inside the nested body 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: returns keywords for which the specified apps rank in the same App Store SERP. It is clear what the tool produces, but it never distinguishes itself from sibling labs tools like post_dataforseo_labs_apple_keywords_for_app_live or post_dataforseo_labs_apple_app_competitors_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?

No guidance on when to use this intersection endpoint versus keywords_for_app, competitors, or bulk_app_metrics. The description gives a purpose but no context, prerequisites, or exclusions.

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, openWorldHint=true. The description adds no behavioral context beyond those flags — no mention of live vs queued execution, cost/rate limits, or that the response is returned synchronously. The 1000-item limit it cites is already stated in the app_ids schema 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?

A single front-loaded sentence with no filler, which is structurally sound. However it is terse to the point of under-specification for a bulk POST endpoint rather than genuinely 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?

An output schema exists, so return values need not be explained, but nothing else is covered: no usage routing, no request-shape guidance, no behavioral detail beyond the annotations for a destructive-flagged POST endpoint. The description is too thin for 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?

Top-level schema description coverage is reported as 0% (the single 'body' parameter carries no description), and the description does nothing to compensate — it never explains that body is an array of per-app-request objects requiring app_ids plus location and language identifiers. The nested property docs exist, but the description leaves the report structure and required pairing rules (location_name OR location_code; English/US only) to be inferred.

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 concrete verb+resource: it returns ranking metrics for up to 1000 App Store applications. That is clearly distinguishable from the Google counterpart and from the single-app tools, but it never names or contrasts those siblings, and 'ranking metrics' is left undefined, so it stops 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?

There is no when-to-use, when-not-to-use, or alternative guidance at all. An agent cannot tell from the description when to pick this bulk endpoint over post_dataforseo_labs_apple_keywords_for_app_live, apple_app_competitors_live, or the Google bulk variant.

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 do cover the safety profile (openWorldHint, destructiveHint, idempotentHint), lowering the bar, yet the description adds nothing behavioral: no auth requirements, no rate limits, no note about the English/US-only restriction that actually constrains this endpoint, and no mention of pagination despite limit/offset fields in the schema.

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, purpose front-loaded, no filler or repetition. Appropriately sized for a single-endpoint description, though it is under-informative rather than over-long.

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 endpoint takes a nested array body with many optional fields and enforces English/US-only and location/language pairing, none of which the description surfaces. Output schema exists so return values needn't be explained, but the routing and constraint gaps leave the definition materially 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?

Schema description coverage is reported at 0% for the top-level 'body' array parameter, and the description supplies no compensating detail about its structure, the app_id requirement, or the location/language pair constraints. It contributes no meaning beyond the inner property descriptions.

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 a list of keywords an app ranks for on the App Store, plus the app's ranking position per keyword. The phrase 'App Store' implicitly distinguishes it from the sibling post_dataforseo_labs_google_keywords_for_app_live (Play Store), but no sibling is named explicitly.

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

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

The description only narrates the output; it gives no when-to-use guidance, no prerequisites (e.g. that location/language are effectively fixed to US/English), and never names an alternative endpoint such as the Google equivalent.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true — an unusual profile for what the description frames as a data-retrieval endpoint, and the description never reconciles that. It also omits that a live POST endpoint is billed per request, that it is rate-limited, or that auth is required. No annotation contradiction in the strict sense, but the description adds essentially no behavioral context over the annotations and leaves the read/write mismatch 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 sentences, front-loaded with the core capability and second sentence enumerating the returned fields. No padding or filler. Slightly under-structured for an endpoint with this much request-shape complexity, but no wasted text.

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

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

An output schema exists, so return-value explanation is not required, but the description still omits usage routing, constraints (US-only location, English-only language, documented in the schema but never surfaced), and the batch-array request semantics. For a nested-body live endpoint in a crowded sibling set, this leaves real gaps.

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

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

Schema description coverage is reported as 0%, meaning the top-level `body` parameter is undocumented in the description, which says nothing about the array-of-task-objects structure or the required app_id/location/language fields. The description only names output concepts (IDs, search volume, ranking data), which the output schema already covers. It provides no compensating semantics for the request body.

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

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

The description names a specific verb+resource: it returns a list of Google Play mobile apps that intersect with a target app on ranking keywords, with competitor IDs, search volume, and ranking data. That is materially clearer than the title alone. It does not, however, distinguish itself from the near-identical sibling post_dataforseo_labs_google_app_intersection_live or the Apple counterpart, so sibling differentiation is left to inference.

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

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

No when-to-use guidance is given. With a sibling literally named google_app_intersection_live plus google_keywords_for_app_live and google_bulk_app_metrics_live in the same family, the agent is given no rule for choosing among them. No prerequisites, no cost/live-vs-task distinction.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, yet the description frames this purely as a retrieval that 'provides you with a list of keywords'. Nothing in the text suggests any destructive or write-like side effect, so the description and the annotations conflict rather than complement each other.

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 tight sentence with the result subject front-loaded and no filler. Efficient, though its brevity comes at the cost of substance rather than being concisely complete.

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 request whose body requires location and language selection plus up to 20 app IDs, the description is silent on almost all of that structure. The existence of an output schema excuses it from explaining return values, but not from the input-side context it omits.

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

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

Reported schema description coverage is 0% (the top-level body has no description), so the description carries the burden — but it only alludes to the app_ids object. Location/language requirements, limit/offset, filters, and order_by are not addressed at all, leaving the caller with no semantic guidance beyond one nested field.

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?

Names a concrete verb and resource: returning the list of keywords on which the given apps rank in the same Google Play SERP. The 'intersection' semantics distinguish it in spirit from single-app tools like google_keywords_for_app_live, but no sibling is named explicitly.

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

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

There is no guidance on when to choose this over the many nearby siblings (apple_app_intersection_live, google_app_competitors_live, keywords_for_app_live). The reader must infer the use case entirely from the one-line output description.

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, idempotentHint=false, openWorldHint=true) carry the safety profile, so the bar is lower, but the description adds nothing about cost, latency, rate limits, or what a live call consumes. It also implies a passive data retrieval ('provide you with ranking metrics') while annotations declare destructiveHint=true, a tension the description never resolves.

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, so nothing needs trimming. It is efficient but borders on under-specification rather than true conciseness, which keeps it below a 5.

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. However, for a bulk endpoint taking an array of up to 1000 app IDs with mandatory location and language selection, the description omits the input contract entirely and offers no behavioral context, leaving the definition thin for 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?

Top-level schema description coverage is 0% and the description adds no parameter detail; the only overlap is 'up to 1000' echoing the app_ids limit. The nested item properties (app_ids, location_name/code, language_name/code, tag) are documented inside the schema, which mitigates the gap, but the description itself does not compensate for the uncovered body parameter or the required location/language pairing.

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

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

The description states a concrete outcome (ranking metrics), the resource (Google Play applications) and a scope bound (up to 1000), which lets an agent separate it from siblings like google_keywords_for_app_live or google_app_competitors_live. It stops short of naming the closest sibling (apple_bulk_app_metrics_live) or explaining how 'ranking metrics' differ from competitor/intersection endpoints, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance, no mention of when to prefer this bulk endpoint over the per-app or competitor endpoints, and no prerequisites such as account/credits. The agent is left to infer usage purely 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false. The description adds no behavioral context such as auth needs, cost, rate limits, or mutation semantics, and its 'provide you with estimated' framing does not address the destructive annotation; there is no explicit contradiction, but also no added transparency.

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 return components. There is no filler or repetition.

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

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

An output schema exists, so return values need not be explained. However, for a complex bulk endpoint with a nested body object, the description omits required body structure and usage context; it is adequate for recognition but not fully complete.

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

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

Schema description coverage is 0% for the single top-level body parameter, so the description must compensate. It mentions the target limit (1,000) and output item types, which loosely map to targets and item_types, but it does not explain the required body array-of-objects structure or the optional language, location, tag, and ignore_synonyms fields.

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

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

States a specific verb and resource: provides estimated monthly traffic volumes for up to 1,000 domains, subdomains, or webpages, and enumerates the organic, paid, featured snippet, and local pack estimates. Clear enough to identify the tool, but it does not explicitly differentiate from sibling DataForSEO Labs bulk endpoints such as bulk keyword difficulty.

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 guidance is given. The bulk/1,000-target limit implies a bulk-estimation context, but the description does not name alternatives, prerequisites, or exclusions, so an agent must infer usage entirely.

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 endpoint purely as a data retrieval ('provide you with... you will obtain'), while annotations declare destructiveHint=true and readOnlyHint=false for a synchronous 'live' query endpoint. That is a conflicting safety signal an agent must reconcile, and the description adds nothing about cost, rate limits, or auth. No disclosure beyond what annotations (mis)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?

Two sentences, no padding, front-loaded with what the endpoint returns and then the supplementary ranking/traffic data. Slightly generic opener ('This endpoint will provide you with') but acceptable and wastes no 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?

An output schema exists, so return values need not be described, and the input schema documents the nested params well. However, for a POST endpoint whose body requires location/language and supports filters/ordering, the description omits the required-domain format, the location/language prerequisite, and the double-charge clickstream option, leaving gaps an agent must fill from the schema alone.

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

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

The description adds no parameter meaning whatsoever, but the nested item properties in the schema (target, location_name/code, language_name/code, filters, order_by, item_types, historical_serp_mode, include_clickstream_data) are thoroughly documented there. The schema carries the load; the description is neutral rather than helpful.

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 Google product/service categories containing keywords the target domain ranks for, plus rankings and traffic data. That is enough to distinguish it from post_dataforseo_labs_google_categories_for_kw_live (keyword-anchored) and post_dataforseo_labs_google_keywords_for_categories_live (the inverse mapping), though the description never names those siblings 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 guidance, no statement of prerequisites (target domain format, location/language requirement, live vs historical alternatives), and no routing to any sibling. An agent is left to infer context 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 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 frames the tool as passive data retrieval ('provide you with ranking and traffic data', 'review the domain ranking distribution'), implying a read-only operation, while annotations declare readOnlyHint=false and destructiveHint=true. This conflict directly contradicts the impression the text creates, leaving the agent unsure whether the call has 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 endpoint's function and returning to what the caller can inspect. Some marketing phrasing ('You will be able to review...') is slightly padded, but nothing distracts and the size is appropriate.

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 needn't enumerate return fields, and its brief coverage of returning ranking and traffic data is adequate. However, for a live endpoint with a single required body parameter it omits prerequisites, the domain-format requirement, and any usage guidance, and leaves the annotation conflict unresolved.

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

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

Reported schema description coverage is 0% at the top level (only the nested body items are documented), and the description adds no parameter meaning beyond the phrase 'the specified domain'. It does not mention required vs optional fields, the domain-format constraint, or the language/location alternates, 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?

States a specific resource and scope: ranking and traffic data from organic and paid search for a specified domain, including SERP ranking distribution and estimated monthly traffic. This is clear enough to distinguish it from unrelated siblings, but it never explicitly contrasts with the closest sibling (post_dataforseo_labs_google_historical_rank_live) or other domain-overview tools, so it stops short of full sibling 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 says nothing about when to use this tool versus alternatives, nor any prerequisites such as requiring a stripped domain (no https:// or www), being a live/paid call, or how it relates to the historical rank sibling. Usage must be inferred entirely from the name and title.

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 portrays a pure data-retrieval endpoint ('will provide you with historical monthly traffic volumes'), yet annotations declare readOnlyHint=false and destructiveHint=true. An agent will be confused about whether this call mutates state; the description also omits any auth, quota, or cost context for a live, open-world endpoint.

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 the core capability and then defaults and returned metrics. No filler or redundancy, though the final sentence about paid/featured/local pack is slightly separable.

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

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

An output schema exists, so return values need not be re-explained, and the description covers the headline capability and range defaults. However, the annotation/description mismatch and the absence of any usage or parameter guidance leave gaps for a live, multi-parameter, open-world 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 at 0%, so the description would need to compensate. It mentions the 1,000-domain cap and the default 12-month range, but says nothing about language_code/name, location_code/name, item_types, or tag, leaving most inputs unexplained.

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: providing historical monthly traffic volumes for up to 1,000 domains within a time range. The word 'historical' implicitly distinguishes it from the sibling post_dataforseo_labs_google_bulk_traffic_estimation_live (current traffic), but that alternative is never named, so sibling routing is only implicit.

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

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

The description explains default behavior (previous 12 months if no range is given) and the October 2020 floor, but never says when an agent should choose this endpoint versus the non-historical bulk_traffic_estimation_live endpoint or other traffic tools. There are no explicit when/when-not conditions.

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?

The description frames the endpoint as a passive data provider ('will provide you with historical data'), yet the annotations declare readOnlyHint=false and destructiveHint=true. A retrieval operation that merely returns rankings/traffic cannot be destructive, so the description and annotations give the agent conflicting signals 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?

A single front-loaded sentence that states the resource and the concrete data returned. Minor filler ('This endpoint will provide you with') but no wasted clauses.

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 nested request schema is rich. However, the description omits usage guidance, authentication/location-lookup notes, and any mention that the body is an array of request objects, leaving gaps for a fairly complex call.

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

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

The top-level 'body' array has no description and reported schema coverage is 0%, but the nested properties (target, date_from/date_to, location_, language_, correlate, ignore_synonyms, include_clickstream_data) are fully self-documented in the schema. The description only gestures at 'the specified domain' (target) and adds no 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?

The description names a clear verb (provide/retrieve) and resource (historical rankings and traffic for a specified domain) plus concrete scope (SERP distribution, organic and paid monthly traffic). The 'historical' qualifier implicitly separates it from the current-snapshot sibling post_dataforseo_labs_google_domain_rank_overview_live, but that sibling is never named explicitly.

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

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

Usage is only implied by the word 'historical'; there is no explicit when-to-use, when-not-to-use, or named alternative. It also omits practical guidance such as the double-price cost of include_clickstream_data or the recommendation to keep correlate=true.

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 declare destructiveHint=true and readOnlyHint=false, which is notable for what reads like a data-retrieval endpoint; the description says nothing about safety, side effects, or why the destructive hint is set, nor about rate limits or the fact that only English/US are currently supported (that detail lives only in the schema). The description adds no behavioral context beyond annotations.

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

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

Two short sentences, front-loaded with the core purpose, no filler or redundancy.

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

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

An output schema exists so return values need not be explained, but the description omits the critical constraints that the endpoint currently supports only English and only the US location, and offers no parameter or usage guidance for a tool whose schema has 0% description coverage.

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% and the description provides no parameter meaning at all – not app_id, limit, offset, filters, order_by, language, or location. With one top-level parameter (a required body array) and zero coverage, the description fully fails to compensate for the schema 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?

States a specific verb+resource: provides a list of keywords for which the target app ranks on Google Play, and adds that ranking position is returned. This distinguishes it from sibling tools like app_competitors_live and bulk_app_metrics_live, though it doesn't explicitly name the alternative keyword endpoints (e.g., apple_keywords_for_app_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?

No when-to-use, when-not-to-use, prerequisites, or named alternatives. The description states what the tool does but gives the agent no guidance on when this is the right choice versus the many related 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 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?

Annotations already declare destructive=true, openWorld=true, idempotent=false, and the description gives no counter-evidence, but it also adds nothing behavioral -- no mention of cost, latency, pagination behavior, or the double-pricing tied to clickstream data (which appears only in the schema). For a paid, non-idempotent remote call, that is a real gap.

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

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

Two sentences, front-loaded, with no filler. The only weak point is that the entire second sentence enumerates return fields, which is redundant given an output schema exists and therefore slightly misallocates the description's limited 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?

The endpoint is complex (14 nested fields, required location, offset_token pagination cutover at 10,000 results, cost implications) yet the description addresses none of the operational context. Output schema and annotations carry some load, but routing and cost/behavior context the agent needs to call this correctly are absent.

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

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

Reported top-level coverage is 0% (the 'body' wrapper is undescribed), but the nested item properties are documented exhaustively in the schema itself, so an agent can set target, location, limit and offset_token without the description. The description itself adds zero parameter meaning, which caps this at 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 states a specific verb and resource -- returning keywords relevant to a target domain -- which lets an agent distinguish it from category- or app-based siblings. It does not, however, differentiate itself from closer siblings like keyword_ideas, keyword_suggestions or ranked_keywords, all of which return keyword sets for a similar seed.

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

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

There is no when-to-use guidance, no named alternative, and no prerequisites (location_code/location_name requirement, pagination choice). An agent must 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?

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?

Adds substantial context beyond annotations: exact cost, response envelope structure, the fact that rejected requests still return HTTP 200, and pagination with offset_token. These are behavioral traits not present in annotations and are crucial for correct usage.

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 longer than average but every sentence earns its place: purpose, cost, alternatives, envelope, and use case are clearly front-loaded. Slightly verbose but 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 an output schema present, the description does not need to explain return values. It covers the key operational aspects (cost, response envelope, error behavior, pagination) and routes to alternatives, making it complete for 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?

Though schema coverage is 0% at the top-level, the nested schema descriptions are detailed. The description adds value by explaining pagination tokens and the limit/offset semantics. It doesn't cover all parameters, but the schema does, so the balance is good.

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: finds which pages of a target site earn its rankings, ranked by traffic. It distinguishes from siblings by pointing to alternative tools for keywords and backlinks, and by contrasting with the more expensive google_ads 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?

Explicitly says when to use it (to find pages worth defending/expanding) and when not, naming two alternative tools. Also compares cost and data granularity with google_ads endpoints, giving clear selection criteria.

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 already declare openWorldHint=true, destructiveHint=true and idempotentHint=false, so the safety profile is largely covered. The description adds nothing beyond output contents: no mention that this is a live, credit-consuming POST request per batch item, no auth or rate-limit context, and no acknowledgement that a supposedly read-style lookup is flagged destructive. Note the description does not explicitly claim read-only, so this is tension rather than a hard contradiction.

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

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

Two compact sentences, front-loaded with what the endpoint returns. The second sentence is slightly padded ('the provided domains gain from the specified keywords'), but nothing is truly wasted.

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

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

For a multi-keyword, multi-filter, live POST endpoint with a complex nested body and several near-identical competitor siblings, the description is too thin. An output schema exists so return values need not be restated, but request construction, batching, cost/side-effect expectations, and sibling differentiation are all absent.

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

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

The single top-level parameter ('body') is a batch array with many nested, required-combination fields (keywords, location_name/code, language_name/code, filters, order_by, limit, offset), and the description explains none of it. An agent must reverse-engineer the entire request shape from the schema, and the description gives no hints about batching or the either/or location and language constraints.

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

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

States a specific verb+resource: it returns a list of domains that rank for specified keywords, plus the metrics attached to those domains. That is clear enough for an agent to know what comes back, but it never distinguishes itself from close siblings such as get_semrush_organic_competitors or post_dataforseo_backlinks_competitors_live, so selection still requires guesswork.

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 stated preconditions (a keyword array plus a location/language pair is mandatory), and no reference to any alternative tool. The agent is told what the output contains but not when this endpoint is the right choice.

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 portrays a pure data-retrieval endpoint ('provide you with a list', 'get the estimated traffic volume'), yet annotations declare destructiveHint=true and readOnlyHint=false, a direct conflict. The description does add output context (which metrics come back), but the mismatch with the stated safety profile undercuts transparency.

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

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

Three sentences, front-loaded with the primary output, and every sentence states a distinct data category. Minor filler ('In addition to that') but no real 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?

Because an output schema exists, return-value detail is not required, and the description adequately frames the response content. However, for a live paid POST with a required body, the description omits input format, cost implications, and usage context, leaving meaningful gaps.

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

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

Top-level schema description coverage is 0% (the sole 'body' parameter is undocumented), and the description adds nothing about the required target domain, the body array wrapper, or filtering/ordering options. Parameter meaning must be inferred entirely from the nested schema, which the description never references.

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 (returns a list of subdomains for a specified domain) and enumerates the data delivered: organic/paid ranking distribution and estimated traffic volume. It is clear enough to distinguish from other DataForSEO Labs tools, though it never explicitly contrasts itself with siblings like domain_rank_overview.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (a 'live' paid endpoint posting a body array), and no notes on batching or cost. The reader gets what it returns but not when it is the right 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 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.