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

Goes well beyond annotations: discloses that this is a SANDBOX endpoint returning dummy data with no payment, that values are statistical estimates derived from 'People Also Ask' data, and that no real prompt counts from ChatGPT/Gemini/Perplexity are reported. That methodological caveat is exactly the kind of context an agent needs before quoting numbers to a user. It does not cover rate limits or response shape.

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

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

Front-loads the core capability, then the sandbox caveat, then the interpretation caveat — a sensible order for an agent scanning it. Slightly redundant in repeating 'modeled/estimated' three times and in spelling out the full DataForSEO source name, but nearly every sentence carries decision-relevant 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?

With no output schema, the description still conveys what comes back (a 12-month demand history per keyword) and how to treat it (relative, not absolute). Missing only a note on response structure/units and on the unsupported-language refusal behavior that the schema hints at.

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 keywords, language_code and location_code are already fully documented with limits and codes. The description only restates the 10-keyword cap and 12-month window, adding nothing about location/language semantics. Baseline 3 is appropriate when the schema does the work.

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: modeled AI-search demand for up to 10 keywords with 12-month history, and names the upstream source (DataForSEO AI Optimization Keyword Search Volume). It implicitly separates itself from keyword_metrics by scoping to AI search rather than classic search volume, though it never names that sibling 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?

Offers one real usage instruction — 'Use it as a relative demand indicator' — which tells the agent how to interpret output but not when to pick this over keyword_metrics or keyword_ideas. No exclusions or alternative routing are given, so the agent must infer usage 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 cover the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description adds two things annotations can't: sandbox/dummy-data behavior with no payment, and a prompt-injection warning that titles/descriptions are third-party content to be treated as data. It stops short of noting rate limits or result freshness beyond 'Live'.

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: return shape first, then sandbox status, then the security caveat. Every sentence carries information an agent needs, and the most important facts are 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?

There is no output schema, and the description compensates by enumerating the return fields and the fixed count of 10. Combined with the sandbox disclosure and the injection warning, an agent has everything needed to call it and to interpret the output safely.

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 detailed descriptions for keyword (max length, unsupported operators), language_code and location_code (default codes, lookup endpoint), so baseline is 3. The description adds no parameter-level meaning beyond what the schema already says.

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: 'Top 10 organic Bing results' with the exact returned fields (position, URL, title, description) and engine/device ('Bing', 'desktop'). It is clearly distinguishable from google_serp by engine, but it never explicitly contrasts itself with the Google sibling or news_search/image_search, leaving that routing to the agent.

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?

Adds real context for choosing/trusting it: it is sandboxed and returns dummy data with no payment, so an agent knows the results are not production-real. However, it never states when to prefer google_serp, news_search or image_search over this tool, so alternatives are left implicit.

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 useful behavioral context beyond the annotations: it caps results at 10, identifies the DataForSEO Labs source, and clearly states that the sandbox returns dummy data with no payment. The annotations already cover safety and openness hints, so this is appropriately supportive without needing to repeat them.

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 compact and front-loaded with the core capability, followed by the important sandbox caveat. Every clause carries useful information: scope, metrics returned, source, result limit, and sandbox behavior.

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 fully documented three-parameter schema and the lack of an output schema, the description does a good job explaining what is returned: up to 10 competitors with ranking overlap and traffic metrics. It also clarifies sandbox behavior. It could be slightly more complete by clarifying real-environment payment or output shape, but the key context is 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?

Schema description coverage is 100%, so domain, language_code, and location_code are already well documented in the input schema. The description adds no parameter-specific syntax or defaults beyond saying the tool analyzes a domain, 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 clearly states the resource and operation: organic search competitors of a domain, with ranking overlap and traffic metrics. It also names the underlying DataForSEO Labs endpoint, but it does not explicitly distinguish this from sibling tools such as keyword_gap or domain_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 use case is implied by the tool name and description: discovering competitors for a given domain. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the many 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 declare openWorldHint=true, idempotentHint=true, destructiveHint=false, readOnlyHint=false, so the safety profile is already covered. The description adds genuinely new behavioral context: it warns that this SANDBOX build returns dummy data and incurs no payment. It still doesn't say what non-sandbox invocation costs or whether results are cached/stale, which is the main remaining unknown for a paid data lookup.

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

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

A single line front-loads the returned metrics and closes with the sandbox caveat. Every clause carries information and there is no filler or 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?

For a 3-parameter tool with a fully described schema and no output schema, the description usefully enumerates return fields and flags the sandbox behavior, which is what an agent most needs before calling. It stops short of explaining the async/result-retrieval relationship with siblings like get_result and retry_request, which a caller would need for a complete picture.

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

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

Schema description coverage is 100%, and the schema itself documents domain normalization, language fallback, and location codes with examples and ranges. The description adds nothing about any of the three parameters, 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 resource (a domain's organic and paid search footprint) and enumerates the exact metrics returned: keyword count, estimated traffic, traffic value, and ranking distribution, plus the upstream endpoint (DataForSEO Labs Domain Rank Overview). 'Overview' plus the aggregate metric list implicitly separates it from per-keyword siblings like ranked_keywords or traffic_estimate, 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?

Usage is only implied: you call it to get a high-level snapshot of a domain's search footprint. There is no statement about when to prefer it over traffic_estimate, ranked_keywords, or competitors, and no prerequisites beyond what the schema already says. The sandbox note is environmental context rather than use guidance.

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

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

The description adds meaningful context beyond annotations: it is a sandbox endpoint returning dummy data with no payment, it deliberately omits contact details, and it warns that third-party titles/descriptions must be treated as data, not instructions. These are useful behavioral disclosures for safe invocation, though it does not explain idempotency or auth needs.

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, followed by sandbox and safety notes. It is appropriately sized, with no wasted sentences, though the security boilerplate is somewhat dense.

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 one-parameter read-style lookup with no output schema, the description explains the grouped return shape, sandbox behavior, and omitted fields. It is sufficiently complete for an agent to call correctly, with only minor gaps around alternative-tool routing.

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% and the single domain parameter is fully documented in the schema, including URL reduction and rejection of IPs/ports. The description adds no parameter-level detail beyond what the schema already provides, 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 clearly states the resource returned: technologies used by a website (CMS, analytics, servers, frameworks, marketing tools), grouped by category. It does not explicitly contrast with siblings like domain_overview or page_audit, but the resource is specific enough for an agent to identify it.

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

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

There is no guidance on when to use this tool versus alternatives such as domain_overview or page_audit. The sandbox note gives context, but the description does not say when this technology-detection call 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the valuable 'FREE' cost signal and explains how the returned codes are consumed downstream, but says nothing about lookup behavior (exact vs partial matching, ambiguity handling, empty-result behavior) beyond what the schema hints.

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

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

Two compact sentences with zero padding; the 'FREE' cost cue and the primary capability are front-loaded, and the downstream-code guidance follows immediately.

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 two-param read lookup with no output schema, the description explains what is returned (location codes) and how to use them, which is the key missing context. Minor gap: it never explains the optional 'country' filter or result determinism.

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 50%: 'query' is documented in the schema, but the optional 'country' enum (DE/AT/CH) has no description anywhere — the description mentions the countries only as a geographic scope, not as a filter parameter. Baseline 3 applies since the schema documents the primary parameter and the description adds no param-level details.

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?

Specific verb (look up) plus resource (city/region location codes) with concrete examples (Rosenheim, Wien, Zürich) and the geographic scope. An agent immediately knows this is a code resolver, not a search or metrics tool.

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

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

Explicitly names which sibling tools consume the returned codes (google_serp, local_business, news_search, image_search, local_market_check) and states that all other tools take country codes instead, with example numeric codes. This routes the agent correctly without 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 mark it read-only and closed-world. The description adds useful behavior beyond that: the call is free, it returns either the result or status, and it requires credentials from the original response.

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 definition is a single tight sentence with 'FREE' front-loaded. Every phrase, including the parenthetical status case and credential origin, adds useful 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?

The annotations cover safety, and the description covers cost and credential sourcing. With no output schema, however, it does not describe the shape of the returned result or status, nor what happens with expired or invalid tokens.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It names both required parameters and says they come from the original response, but does not explain their formats, distinction, sensitivity, or error behavior.

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: fetch a result or its status using request_id and result_token. The phrase 'already paid for' distinguishes it from paid query siblings, but no sibling such as retry_request is explicitly named.

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 clearly says to use this when you already have a paid result and the identifiers from the original response. It does not state when not to use it or name alternatives like retry_request.

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

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

Adds genuinely useful context beyond the annotations: that the backend is DataForSEO live SERP, that sandbox mode returns dummy data with no payment (implying the live path is billed), and an explicit prompt-injection warning that result titles/descriptions are untrusted third-party content. The only gap is that live-mode cost/rate behavior and result freshness are not spelled out.

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 what the tool returns, then the sandbox caveat, then the safety note. Every sentence carries weight, though the doubled provider parenthetical is slightly dense.

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?

There is no output schema, yet the description lists the return shape (top 10, position/URL/title/description) so the agent knows what comes back. Combined with the sandbox and injection notes, an agent can call this correctly; only live-mode billing and pagination/top-N flexibility are unmentioned.

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 meanings of keyword, language_code and location_code (including defaults, the 2840 US example codes, and the refusal-before-payment rule) are already fully documented in the schema. The description adds nothing parameter-specific beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Top 10 organic Google results for a keyword') and enumerates the returned fields (position, URL, title, description), plus names the upstream provider and surface (desktop organic). This clearly separates it from siblings like bing_serp, news_search, image_search and local_market_check without opening a schema.

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

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

The keyword-based organic-lookup use case is implied, and the SANDBOX note tells the agent that during development it will get dummy data rather than real results. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as bing_serp or news_search; the agent must infer that from sibling names.

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 genuinely useful context beyond the annotations: the 12-month window, the relative 0-100 normalization, and the critical 'SANDBOX (development): returns dummy data, no payment' caveat, which tells the agent the results are not real and that no charge occurs. It does not explain what happens in non-sandbox mode or whether the call is worth caching, keeping it short of a 5.

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

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

Two compact sentences, front-loaded with purpose, metric scale and timeframe, followed by the sandbox caveat. Slightly dense with stacked parentheticals, but no sentence 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?

No output schema exists, yet the description conveys the return shape (interest over time, relative 0-100, 12-month window) and the sandbox data caveat, which is enough for correct invocation. Minor gaps remain around production-mode billing and response granularity (weekly vs daily points).

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 all three parameters (including the location_code lookup hint and language fallback behavior) are already fully documented in the schema. The description only restates the 'up to 5 keywords compared' constraint, adding little beyond structured data, so the baseline 3 applies.

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

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

States a specific resource and metric ('Google Trends interest over time, relative 0-100, past 12 months, up to 5 keywords compared'), which clearly separates it from siblings like keyword_metrics or keyword_ideas. It never names a sibling explicitly, but the scope statement alone is enough to identify the tool's job.

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 phrases like 'compared against each other', suggesting comparative trend analysis, but the description gives no explicit when-to-use, when-not-to-use, or alternative routing (e.g., 'for absolute search volume use keyword_metrics'). The agent must infer the choice from the sibling list.

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

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

Annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) already convey the safety profile, and the description adds real context on top: a hard cap of 20 results, that the SANDBOX returns dummy data with no payment, and that returned texts are untrusted third-party content. It stops short of saying what production calls cost or how failures/payment refusals surface.

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 payload the agent cares about, then environment caveat, then content-safety caveat. Every sentence carries information, though the 'NOTE:' framing is slightly heavy.

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?

There is no output schema, and the description compensates by enumerating returned fields and the result cap, while the schema handles all three parameters and annotations cover safety. Remaining gaps (cost in production, error behavior) are minor.

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 keyword, language_code and location_code are already fully documented in the schema. The description adds no parameter-level detail beyond the implicit 'keyword', so the baseline 3 applies.

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

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

Names a specific verb+resource (Google Images results for a keyword) and enumerates the returned fields (image URL, page URL, title, alt text), which clearly separates it from text-SERP siblings like google_serp and news_search. It does not explicitly name those siblings, but the 'Images' qualifier makes the distinction legible.

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 never states when to pick this over google_serp, news_search or local_market_check, nor any prerequisites beyond the sandbox note. Usage must be inferred from the phrase 'Google Images results for a keyword'.

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, idempotency, and non-destructiveness, while the description adds important behavioral context that the annotations do not: sandbox mode returns dummy data and incurs no payment. It does not describe production pricing, rate limits, or response shape, but the sandbox disclosure is meaningful and non-contradictory.

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

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

The description is very compact and front-loads the core purpose before the sandbox caveat. Every sentence earns its place with no redundant or vague filler.

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

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

With a fully documented input schema and annotations covering the safety profile, the description supplies the key practical caveat about sandbox behavior. It could mention the per-keyword return structure or production behavior, but for this three-parameter lookup tool it 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 all parameters are already well documented. The description mentions the 100-keyword limit, but that is already present in the schema and it adds little parameter-level meaning beyond structured fields.

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

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

The description states a specific metric, its range, and its scope: keyword difficulty scores from 0 to 100 for up to 100 keywords. It also names the underlying DataForSEO Labs Bulk Keyword Difficulty service, making it distinguishable from adjacent keyword tools such as keyword_metrics.

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

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

The sandbox note gives clear usage context: this is for development and returns dummy data with no payment. It does not explicitly compare this tool with sibling alternatives, so it stops short of full when-to-use/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?

Beyond the annotations, it discloses the 25-result cap, the volume-descending ordering, the inclusion of the competitor's ranking page, and critically that this is a SANDBOX returning dummy data with no payment — a behavior an agent cannot get from annotations. It stops short of stating whether production calls are billable or how to page past 25.

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 names the resource, then parenthetically the cap, ordering, extra output field, data source and sandbox status. No padding, no repetition of the name.

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

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

For a read-style analytics call with no output schema, the essentials are covered: inputs implied, result size, ordering, an extra returned field and the sandbox caveat. Slight gap on pagination/result-count behavior and on cost in non-sandbox mode.

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% and each parameter carries a detailed description (domain normalization, location codes, language defaults), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond referencing domain and competitor implicitly. Baseline 3 is correct.

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

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

States a specific verb and resource: keywords a competitor ranks for in Google that your domain does not, plus the competitor's ranking page and the underlying data source. The 'gap' framing clearly separates it from ranked_keywords or keyword_ideas without needing those schemas opened.

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 when the tool applies (you need to find terms a competitor wins that you miss, given both a domain and a competitor), but it never names alternatives such as ranked_keywords, keywords_for_site or keyword_ideas, and gives no exclusions. Usage is inferable but not routed.

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 useful behavior beyond the annotations: it discloses the 25-result cap and explicitly notes that SANDBOX mode returns dummy data with no payment. This complements annotations such as openWorldHint=true and idempotentHint=true, though production billing/cost behavior is only implied.

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 and compact: it states output size, input concept, returned metrics, source and sandbox behavior in two short sentences with 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?

For a three-parameter keyword-idea tool with no output schema, the description is largely complete: it names the result fields, result cap and sandbox behavior. A minor gap is that it does not explicitly distinguish this generation tool from keyword metric or gap-analysis siblings.

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

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

Schema description coverage is 100%, so language_code and location_code are already well documented in the schema. The description reinforces the single-seed-phrase constraint for the required keywords parameter, but adds little beyond what the schema already provides.

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

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

The description states a specific resource and scope: up to 25 keyword suggestions containing the words of one seed phrase, with search volume, CPC and competition. It is clear what the tool does, but it does not explicitly differentiate itself from siblings such as keyword_metrics, keyword_gap or keywords_for_site.

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 'one seed phrase' implies the intended input shape and use case, but the description gives no explicit guidance on when to choose this tool over keyword_metrics, keywords_for_site or other sibling keyword tools. Usage is therefore 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 destructiveHint=false and idempotentHint=true, and the description adds genuinely new context: sandbox mode returns dummy data with no payment, and batching is capped at 1000 keywords per call. It does not explain what happens in production (credit consumption, latency, partial failures) which matters given readOnlyHint=false on an effectively read-only lookup.

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

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

Two short sentences, zero filler, with the concrete metrics and batch limit front-loaded and the sandbox caveat isolated in parentheses. Every clause carries information an agent can act on.

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

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

With no output schema, the description does the necessary work of enumerating the returned fields (volume, competition, CPC, 12-month history), and the sandbox note prevents misreading dummy values as real data. It stops short of describing result ordering or error behavior when some keywords are rejected, which would complete the picture.

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 keywords, language_code and location_code are already well documented in the schema. The description only restates the 1000-keyword cap already encoded as maxItems and adds no meaning about language/location interaction beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ('Google Ads search volume, competition, CPC and 12-month history') with an explicit batch capacity of up to 1000 keywords, and names the upstream provider (DataForSEO Google Ads Search Volume Live). It never names or distinguishes itself from similar siblings such as ai_keyword_demand, keyword_difficulty or search_intent, so an agent must still infer which metrics tool fits.

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 when-to-use or when-not-to-use guidance and never points to an alternative sibling. The only situational note ('SANDBOX (development): returns dummy data, no payment') describes an environment rather than a usage decision, so keyword-research routing is left entirely to inference.

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

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

Goes beyond annotations by disclosing the 25-result cap, the exact result fields, and the critical sandbox behavior (dummy data, no payment) — which explains why readOnlyHint is false despite the tool only reading. It stops short of stating cost/credit behavior for production calls or what happens when a domain has no keyword coverage.

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 clauses: the payload description first, then the sandbox caveat. No filler, and the output fields are front-loaded so an agent can judge fit immediately.

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

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

With no output schema, the description correctly enumerates return fields, and it flags the sandbox mode. Minor gaps remain around empty-result behavior and whether production calls consume credits, but for a 3-parameter read tool this is largely 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?

Schema description coverage is 100%, so the schema already explains domain normalization, language defaults and location codes in depth. The description adds nothing about parameters, which is acceptable here since defaults and rejection rules are fully documented in the schema.

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

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

States a specific verb+resource: up to 25 Google keywords relevant to a website, plus the metric fields returned (volume, CPC, competition, difficulty, intent) and the upstream endpoint name. It does not, however, distinguish itself from close siblings such as keyword_ideas, keyword_metrics or ranked_keywords, which an agent could plausibly confuse with 'keywords relevant to a website'.

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 context is implied (analyze a domain to discover keyword opportunities), and the SANDBOX note usefully tells the agent the data is dummy during development. But there is no explicit when-to-use / when-not-to-use statement and no routing to alternatives for seed-based ideas or already-ranking keywords.

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 openWorldHint=false, so the safety profile is covered. The description adds cost information not present in annotations ('FREE') and discloses the payload contents (prices, limits, notices, examples), which is meaningful beyond the structured fields; it does not cover pagination or ordering of results, but the tool is a small static catalog.

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 with zero waste, and the highest-value fact (free) is front-loaded before the contents list and the call-ordering directive.

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?

No output schema exists, so the description carries the burden of describing the response, and it does so concretely (price in USDC, limits, notices, example requests). An agent has everything it needs to call this correctly; only minor details like result count or ordering 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?

The tool takes zero parameters, so there is no parameter syntax to explain and the baseline is 4. The description instead spends its words on what the caller receives, which is the right trade-off here.

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

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

States a specific verb and resource ('List all paid data services') and enumerates exactly what each entry contains: price in USDC, limits, notices, and example requests. That scope clearly separates it from the sibling tools, which are individual paid data 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?

'Call this first' is an explicit ordering directive that tells the agent when in the workflow to reach for this tool. It doesn't name any alternatives or exclusions, but as a catalog/discovery entry point there is no real alternative to disambiguate against.

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 safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description adds real value on top: a hard cap of 20 results, the sandbox/no-payment behavior (implying the live mode does cost money), and an explicit prompt-injection warning about third-party listing text. What it doesn't clarify is cost or rate-limit behavior in live mode. No contradiction with readOnlyHint=false, since it describes a paid external query with no data 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?

Three dense sentences that are front-loaded with the capability and the result fields, then environment and safety caveats. Nothing is filler, though the parenthetical provider name and the block-caps annotations make it slightly heavier than necessary.

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

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

With no output schema, the description correctly enumerates what is returned, states the result cap, and flags sandbox behavior and untrusted content, which is what an agent needs before calling. The main remaining gap is sibling disambiguation against local_market_check and google_serp.

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 keyword, language_code and location_code are already fully documented with patterns, defaults and lookup hints; the baseline of 3 applies. The description only supplies example query strings ("plumber", "coffee shop"), which incidentally illustrates the keyword param but adds no semantics for language or location selection.

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?

Opens with a concrete verb+resource+scope: up to 20 Google Maps businesses for a query, with an example query and an enumerated return field list (name, category, address, phone, website, rating, coordinates). An agent immediately knows what it gets. It does not distinguish itself from the sibling local_market_check or google_serp, 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?

"SANDBOX (development): returns dummy data, no payment" gives useful context about the environment the tool runs in, but there is no statement of when to choose this over local_market_check or google_serp, and no prerequisites or exclusions. Usage is implied by the query examples rather than 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?

With annotations present, the description still adds substantial non-schema behavior: it is a paid call bundling two data calls under one payment, SANDBOX mode returns dummy data with no payment, and unsupported country/language pairs are refused before payment. The prompt-injection warning about third-party titles/addresses/phones is a valuable safety note. It does not cover rate limits, sample-size truncation behavior, or what happens on partial failures, keeping it below a 5.

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

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

The return contents are front-loaded and the sandbox and security caveats follow logically. There is some redundancy: 'one payment' appears both in the source parenthetical and again as 'Package of two data calls for one payment,' and the 'NOTE:' sentence repeats the bundling point a third time.

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 four-parameter, no-output-schema tool, the description adequately enumerates what comes back (organic results, local pack, search features, Maps businesses, competitor domains, position check) and flags the paid and sandbox modes. It stops short of describing result limits beyond 'top 10', failure/partial-result behavior, or the response envelope, which matters for a two-call bundle.

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

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

Schema description coverage is 100%, so every parameter (including location codes, language fallback behavior, and the keyword format constraints) is already documented in the schema. The description adds only the framing of 'optional position check for your domain,' which the schema's domain description already conveys. Baseline 3 applies.

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

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

The description names the exact resource and scope: top 10 organic Google results with local pack, top 10 Google Maps businesses, competitor domains, optional domain position check. It also identifies the underlying data sources (DataForSEO SERP Google Organic + Maps Live), which lets an agent distinguish this bundled local-SEO snapshot from single-purpose siblings like google_serp or local_business.

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

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

Usage is implied by the scope ('Package for one local search') and by the cost note ('one payment' for two data calls), so an agent can infer this is the bundled alternative to separate SERP + Maps calls. However, it never explicitly says when to choose this over google_serp, local_business, or competitors, nor does it state exclusions such as non-local or non-English-market queries.

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 real behavioral context beyond the annotations: the sandbox returns dummy data with no payment, and headlines/snippets are flagged as third-party content to treat as data rather than instructions. That injection warning is genuinely useful; what is missing is whether live calls incur cost or how failures/refunds are handled, though the schema hints at pre-payment refusal.

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, front-loaded with the result set and fields, then sandbox status, then the safety note. No waste, though the parenthetical provider attribution is slightly incidental.

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 three-parameter fixed-top-10 tool with no output schema, the description covers return fields, sandbox behavior, and content-safety handling. Remaining gaps (live-call cost, failure modes) are minor given the rich schema descriptions.

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 keyword length, language defaulting and location codes all documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (Google News search) and immediately enumerates the five returned fields, so an agent knows exactly what comes back. It does not explicitly differentiate itself from google_serp, bing_serp or image_search, which keeps it from 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?

Usage is implied by 'results for a keyword' and the sandbox/no-payment note clarifies the development context, but there is no explicit statement of when to prefer this over the sibling google_serp or bing_serp tools and no exclusion 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 valuable behavior beyond annotations: it names the provider (DataForSEO On-Page Instant Pages), notes that no JavaScript rendering is performed, discloses sandbox dummy-data/no-payment behavior, and warns that title and description are third-party content. It does not explain why readOnlyHint is false despite the audit being a read operation, leaving a minor gap.

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

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

The description is front-loaded with the core purpose, then efficiently adds provider, sandbox, and safety notes. Every sentence contributes distinct information without repetition or padding.

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

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

With no output schema, the description compensates by listing the categories of returned data. It also covers sandbox behavior and JavaScript limitations. It could be slightly more complete by clarifying production billing/credit behavior or request limits, but it is sufficient for a single-parameter audit 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 coverage is 100%, so the single URL parameter is already fully documented, including rejection of IP addresses, ports, and credentials. The description adds context about auditing one public page but does not provide additional parameter-level guidance 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 gives a specific verb and resource ('technical SEO audit of one public page') and enumerates the audited elements: status code, title, meta description, headings, links, images, load time, and on-page checks. This clearly distinguishes it from sibling tools such as keyword_metrics, google_serp, or domain_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 scope is clear ('one public page') and the sandbox note sets development expectations, but the description does not explicitly contrast this tool with alternatives like domain_overview or competitors. It still gives enough context to know when this tool is appropriate.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), but the description adds material behavior of its own: it performs no payment, contacts no data provider, checks budget/limits, and returns the normalized input. That cost and side-effect disclosure is exactly the context an agent needs before spending money.

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 'FREE.' as the decisive fact, then the operation, then the return value, then the call-to-action. No sentence is redundant.

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

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

For a two-parameter validation tool with no output schema, the description covers cost, side effects, what is checked, and the return value. The one gap is failure behavior — it doesn't say whether an invalid input raises an error or returns a flag in the normalized result.

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 `service` and `input` documented in the schema itself, so the baseline is 3. The description reinforces that `input` must mirror the paid tool's arguments ('Returns the normalized input') but adds no syntax or format detail beyond that.

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: validates an input for a paid tool and checks budget/limits, and explicitly says it does so without paying or calling any data provider. That distinguishes it cleanly from the paid siblings like keyword_metrics or google_serp, which actually fetch data.

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

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

'Use it before a paid call to avoid wasted payments' gives a clear trigger condition, and 'FREE' reinforces the cost rationale. It stops short of naming a specific sibling to pair with or stating when a preflight can be skipped, keeping it just below a 5.

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 real information beyond annotations: the hard cap of 25 results per call, the fields returned (important since there is no output schema), and the explicit SANDBOX warning that data is dummy and no payment is taken. Annotations already cover safety/idempotency for production, though rate limits, auth/preflight requirements and the production billing implication of readOnlyHint=false are left implicit.

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 tightly written sentences; scope and cardinality lead, then the sandbox caveat. No filler, nothing buried.

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 tool with no output schema, the field enumeration plus the 25-result ceiling gives the agent a working picture of the response, and the sandbox note prevents misinterpreting dummy data. Only the absence of any production billing/limit or preflight context keeps it from being complete.

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

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

Schema coverage is 100%, so domain, language_code and location_code are already fully documented including defaults and rejection rules. The description adds nothing about parameter effects or interactions, so the baseline 3 applies.

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

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

States a concrete verb+resource ('Google keywords a domain ranks for') plus the exact payload fields returned (position, ranking page, volume, CPC, difficulty) and cites the upstream source. It stops short of naming a sibling like keyword_metrics or keywords_for_site to disambiguate, so the agent must still compare schemas.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative named among the many adjacent siblings (keywords_for_site, keyword_metrics, domain_overview). The only contextual note is the SANDBOX warning, which is environment info 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?

Annotations already declare non-read-only, non-idempotent, open-world behavior; the description adds the commercial fact that this call is FREE and capped at one retry, which is the key context an agent needs before retrying. It does not disclose what happens if the retry also fails or what the response contains.

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 most decision-relevant token ('FREE') front-loaded, then the precondition, then the inputs. Nothing is redundant.

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

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

For a two-parameter tool with no output schema, the description covers cost, trigger condition, retry limit, and input provenance. Only the failure path (second failure, token invalidation) is left unstated.

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 0% and neither property is documented, so the description carries real weight by explaining that both values come from the error response. It still says nothing about what request_id identifies, whether result_token expires, or how to handle missing/stale tokens.

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 verb and object ('re-run it once') together with the exact precondition that selects it: a PAID call that failed at the data provider after payment settled. It does not name a sibling, but the payment-failure precondition implicitly separates it from get_result and free_sample.

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

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

It gives a clear trigger ('If a PAID call failed ... after payment was settled') and tells the agent where the two inputs come from ('request_id and result_token from the error response'). It does not explicitly state when not to use it, e.g. for free calls or failures before settlement, but the 'once' and 'PAID' qualifiers bound the usage tightly.

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, idempotentHint, destructiveHint=false; the description adds useful context beyond them: sandbox returns dummy data with no payment, labels come from DataForSEO's classifier, and non-English results aren't guaranteed. However, it doesn't explain why readOnlyHint=false for a lookup call or what the output looks like, leaving a behavioral 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?

Front-loaded with the core capability, then caveats. Every sentence carries useful information (sandbox behavior, classifier source, language limits). Minor redundancy: 'up to 10 keywords' repeats what the schema already enforces.

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 one-parameter, no-output-schema tool, the description covers what it returns (intent labels plus probability) and the key operational caveats. Missing only detail on probability format/range, which is a small gap.

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

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

Schema coverage is 100%, so the single parameter is fully documented in the schema (1-10 items, 80 chars). The description restates the 10-keyword cap but adds no new constraint or format detail beyond the schema. Baseline 3 applies.

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

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

The description names a specific verb (search intent) and resource (keywords) and enumerates the four intent categories with probabilities, plus the source (DataForSEO Labs Search Intent). It doesn't explicitly differentiate from siblings like keyword_metrics or ranked_keywords, but the scope (intent labels for a keyword list) is unambiguous.

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

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

Use is implied: look up intent for a list of keywords. No explicit when-to-use/when-not guidance, no named alternative, and no prerequisites stated. The sandbox and language-coverage notes are caveats 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?

Annotations already mark this as open-world, idempotent, and non-destructive, but the description adds important context not covered there: it is in SANDBOX mode and returns dummy data with no payment. That is meaningful behavioral information for an agent. It does not cover return format or pagination, but the annotations carry the safety profile.

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

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

The description is two sentences, front-loaded with purpose and followed by the critical sandbox caveat. Every sentence earns its place 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?

For a bulk estimation tool with no output schema, the description covers the core operation, the domain limit, and the sandbox behavior. It could optionally describe the shape of the returned traffic estimate or note that results are asynchronous, but it is largely sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters including domain constraints, default language, and location codes. The description only repeats the 'up to 10 domains' limit and adds no syntax or format detail beyond the schema, making 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 verb and resource: 'Estimated monthly organic and paid Google traffic' for up to 10 domains. It also names the underlying source (DataForSEO Labs Bulk Traffic Estimation), which distinguishes it from sibling tools like domain_overview or keyword_metrics.

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

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

The phrase 'up to 10 domains in one call' implies a bulk use case, but there is no explicit guidance on when to prefer this tool over alternatives such as domain_overview or keyword_metrics. Usage is implied rather than 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 only declare readOnlyHint=false and openWorldHint=false; the description goes well beyond them by disclosing the write-only semantics, that nothing is published and no reply is returned, and the 3-per-day rate limit. It also states a privacy constraint (no personal data) that is not in the schema. No contradiction with readOnlyHint=false.

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 carrying distinct information: incentive, constraint, and write semantics. The most decision-relevant token ('FREE') is first.

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 one-parameter, no-output-schema, write-only tool, the description covers the side effects (nothing published, no reply), the size limit, the privacy rule, and the rate cap. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the meaningful 'no personal data' restriction and restates the 10-300 character bound as a content constraint rather than just a type limit. It does not add syntax examples or formatting guidance beyond that.

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 and object ('tell the operator which data tool you would pay for'), which is unmistakably different from every sibling tool that fetches data. An agent can tell this is a feedback/request channel rather than a data lookup without opening the schema.

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

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

'FREE' front-loads the incentive and 'Write-only: nothing is published and no reply is sent' tells the agent what to expect from the call. It also bounds usage ('one short text', 'Limited to 3 per day per client'), though it never explicitly states when to prefer this over sibling tools or when not to call it.

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