AIsa SERP — Google

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

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

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

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

Three short sentences with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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

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

With annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the description doesn't need to compensate.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds only a generic note about JSON response structure, which is redundant given the existing output schema and reveals nothing about the operation itself. It provides no useful behavioral context beyond structured data.

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

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

The description is a single sentence, so it is structurally concise, but the sentence is entirely about response formatting and does not earn its place. It is front-loaded with irrelevant information rather than the tool's purpose or usage.

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 list/get tool with an output schema, the description should at minimum state what is being listed. Instead it only describes a generic JSON response shape, which is already covered by the output schema. It leaves the agent without any understanding of the tool's function or when to invoke it.

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

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

The tool has zero parameters, so there are no parameter semantics to document. Baseline for zero parameters is 4. The description neither helps nor harms here, as it contains no parameter information.

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 does not state what the tool does. It only describes a generic API response format ('JSON-encoded data containing a tasks array'), which does not identify the tool's purpose or distinguish it from any sibling. The title contains the actual purpose, but the description fails to convey 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or sibling tools like get_dataforseo_serp_gads_search_locations or post_dataforseo_serp_gads_advertisers_live. The agent receives no routing information.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is already clear. The description adds useful behavioral details: the cost comparison, the DataForSEO envelope structure (data in tasks[0].result, status_code), and the fact that rejected requests still return HTTP 200. These go beyond annotations. However, it does not explain why the tool takes no parameters despite implying a keyword is needed, which is a notable gap in behavior disclosure.

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 structured into three sentences: purpose, return fields, and cost/envelope details. It front-loads the primary action and uses concise bullet-like listing of fields. The cost and envelope details are extra but relevant. The emoji and pricing might be slightly extraneous, but overall it is efficient.

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

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

Given the tool has no parameters and an output schema exists, the description should clarify its purpose and usage. However, it contradicts the title (locations vs. ads) and fails to explain how a keyword is specified without parameters. It also does not mention any relationship to the locations family of tools. The description leaves critical gaps about the tool's actual function and invocation context.

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

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

The input schema has zero parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, but it implies a keyword is used ('ads running against a keyword') without indicating how it is supplied. This is misleading given the empty schema. It does list return fields, which adds some value, but the mismatch undermines parameter understanding.

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

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

The description states a clear verb+resource: 'Returns the ads running against a keyword on Google' and lists the fields returned. However, the tool name and title reference 'locations' for the SERP API, which contradicts the described purpose. This mismatch likely confuses an agent about whether this returns ad results or a location list, and it does not clearly differentiate from siblings like get_dataforseo_serp_gads_advertisers_locations.

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

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

No guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or recommended contexts. The only extra context is cost and response envelope, but nothing about usage scenarios.

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 the description adds nothing about auth, rate limits, or caching. The only extra claim, that the response is JSON with a 'tasks' array, duplicates a return format already covered by the output 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?

It is short, but the second sentence is boilerplate about a 'tasks array' that adds no information given the output schema, and the useful premise (what these languages are) is absent. Efficient in length but not in value.

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

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

With no parameters and an output schema present, the definition is minimally viable, but it omits the one thing an agent would want: that this is a reference list of language codes for the AI Mode SERP endpoints. Complete enough to call, incomplete for selection.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to supply; baseline 4 applies. Nothing in the description misrepresents the empty input contract.

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 says only that the caller 'will receive the list of languages by calling this API', which essentially restates the name and title. It never mentions Google AI Mode, SERP, or what the language list is used for, so an agent learns nothing beyond the tool name.

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 that this feeds the AI Mode SERP endpoints (e.g. post_dataforseo_serp_google_ai_mode_live), and no exclusions. The reference-lookup intent is only inferable from the title, not the 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the exact response envelope (tasks[0].result, tasks[0].status_code), the fact that rejected requests still return HTTP 200, and the pricing model. This goes beyond the annotations and helps an agent interpret responses correctly.

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 behavior, then adds pricing and envelope details. The emoji and pricing note are somewhat tangential but still useful for cost-aware selection. Every sentence earns its place, though the pricing detail could be considered extra.

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

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

Given the tool has no parameters and an output schema exists, the description is largely complete. It explains the response envelope and error behavior, which is critical for DataForSEO APIs. It doesn't explain what 'events' means in Google SERP context, but the title and sibling names provide enough context. The pricing note adds operational context beyond the schema.

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

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

The input schema has zero parameters, so there is no parameter semantics burden. The description lists the output fields, which is useful for understanding what the tool returns. With 0 params, the baseline is 4, and the description adds value by enumerating the response fields.

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

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

The description states a specific verb ('Returns') and resource ('events Google surfaces for a query on Google'), and lists the exact fields returned. It distinguishes itself from sibling tools by naming the 'events' SERP feature, though it doesn't explicitly name a sibling alternative. The title 'List of Google Events Locations for SERP API' is somewhat misleading because the description is about returning SERP results, not locations, but the description itself 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?

The description implies this is a read-only lookup tool for Google Events SERP data, and the sibling list shows many live/post tools, but it doesn't explicitly state when to use this vs. alternatives like post_dataforseo_serp_google_events_live. The pricing note hints at cost-based selection ('cheapest source of search data here'), which is a usage signal, 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds zero behavioral context (no retry semantics, no 30-day expiry note, no auth notes), so it contributes nothing beyond the annotations.

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

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

The single sentence is a content-free stub rather than a concise statement. It is short but earns no place, leaving the agent with no actionable information.

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

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

An output schema exists, so return values need not be described, and the single parameter is well documented in the schema. However, the description fails to establish even minimal purpose or usage context, leaving the definition incomplete for selection among dozens of similarly named 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% and there is only one parameter, whose UUID format and 30-day reuse window are fully documented in the schema. The description adds nothing, but the baseline of 3 is appropriate when the schema does all 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?

The description is a placeholder ('Description of the fields for sending a request:') that says nothing about what the tool does. Any sense of purpose comes entirely from the tool name and title, not the description itself.

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

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

No when-to-use, when-not-to-use, or alternative is mentioned. The agent gets no help distinguishing this fetch-by-id tool from siblings like get_dataforseo_serp_google_jobs_fetch_html or post_dataforseo_serp_google_jobs_submit.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered, but the description contributes zero additional behavior — not what HTML payload is returned, not size limits, not that the result expires. The 7-day retention detail lives only in the schema, not 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?

It is short, but it is a broken placeholder sentence that carries no information and is not front-loaded with any purpose. Brevity without substance is under-specification, not conciseness.

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

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

An output schema exists so return values need not be explained, but for a retrieval-by-id tool the description should at minimum state that it returns stored HTML results for a previously submitted Google Jobs task. As written, the definition is effectively 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 100% for the single 'id' parameter, so the UUID format and 7-day reuse window are already documented in the schema. Per the baseline rule, a high-coverage schema yields 3 even with no param content in the description, which is exactly the case here.

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

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

The description is a fragment — 'Description of the fields for sending a request:' — that describes nothing about the tool. The purpose is only inferable from the tool name, not the description text, and there is no differentiation from siblings like get_dataforseo_serp_google_jobs_fetch or the various *_fetch_html 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?

No when-to-use guidance, no mention of the 7-day retrieval window as a usage constraint, and no routing versus the plain fetch sibling or the live/submit variants. Nothing tells an agent when this 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds useful behavioral context: the cost ratio ($0.002 vs $0.012) and the response envelope structure (tasks[0].result, status_code, HTTP 200 on rejection). However, the core behavior described (returning job listings) is misaligned with the intended purpose (locations), so transparency is incomplete.

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 not overly long, but the first sentence is confusing and adds noise. The cost and envelope details are useful and could be retained. The structure could be improved by front-loading the actual purpose (list of locations) rather than the misleading job listings phrase.

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 fails to explain that this tool returns a list of location codes for Google Jobs, which is its core purpose. It lists output fields but doesn't clarify their meaning in the context of locations. The output schema exists but the description doesn't connect it to the intended use. An agent would be uncertain about what data to expect and how to use it.

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

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

With zero parameters, the schema is empty and the description does not need to explain any parameters. The baseline of 4 applies; the description adds nothing about parameters but also doesn't mislead.

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

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

The description states 'Returns the job listings Google surfaces for a query on Google' which contradicts the tool name and title indicating it should return a list of locations for Google Jobs. It lists SERP fields (keyword, item_types, etc.) that are typical of a search result, not a location list, making the purpose vague and potentially misleading.

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 provided on when to use this tool versus alternatives like get_dataforseo_serp_gads_advertisers_locations or get_dataforseo_serp_google_events_locations. There is no mention of use cases, exclusions, or how it differs from sibling location 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds nothing on top — no return format, no freshness/expiry behavior, no note that the task must already exist. A placeholder sentence contributes zero 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?

It is short, but it is not concise in a useful sense — it is a truncated placeholder fragment that fails to front-load any real information. Brevity here reflects under-specification, not 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 the description need not explain return values, but it still fails to state the core operation or its relationship to the submit tool. For a tool whose only identifier parameter references an asynchronous task, the description leaves the full burden unmet.

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 'id' parameter has full schema description coverage (UUID format, 30-day reuse window), so the schema carries the semantics. Per the high-coverage baseline, a 3 applies even though the description adds no parameter detail.

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

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

The description is a dangling metadata label ('Description of the fields for sending a request:') that never states what the tool does. It does not identify the verb, resource, or the fact that it retrieves a previously submitted Google Search-by-Image task's results by id; only the name/title convey any purpose, and the description provides none.

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 fetch tool versus its siblings (e.g. get_dataforseo_serp_google_search_by_image_fetch_html, google_jobs_fetch, or the submit endpoint). No mention of the submit-then-fetch workflow or the 30-day retrieval window is made in the description itself.

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 signal read-only, idempotent, and non-destructive behavior. The description adds high-value behavioral context beyond that: the large payload size (2.4 MB vs 57 KB parsed), the 'free' cost model, and the important envelope quirk that a rejected request still returns HTTP 200 with outcome in `tasks[0].status_code`. This is exactly the kind of runtime behavior an agent needs to know.

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 concise sentences, each earning its place: the first states the core retrieval action, the second flags payload size and cost, and the third explains the response envelope and HTTP status caveat. No filler or redundant restatement of the tool 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 single-parameter, read-only fetch tool with a provided output schema generated, the description covers the critical operational details: queued result retrieval, raw HTML output, size warning, free retrieval, and the envelope structure with the HTTP 200-on-rejection caveat. There is no meaningful missing context.

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

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

Schema description coverage is 100% for the single `id` parameter, which is already explained as a UUID task identifier. The description repeats the use of `id` but adds no extra semantic detail about how to obtain it or what format beyond the schema. 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 ('Retrieves') and a specific resource ('a queued Google search by image result by `id`'), and narrows the output to 'raw HTML'. This cleanly distinguishes it from the parsed sibling tool, and the title reinforces the same meaning.

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 to use this tool: after a submit has been queued)Skip and when you want raw HTML rather than parsed data. It also clarifies cost behavior ('Free - the charge was on the submit'), but it never explicitly names the parsed alternative or states when not to use this tool, so the guidance remains 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?

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, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotence. The description adds valuable behavioral details: pricing per row ($0.09, up to 20 rows, header excluded), that 4xx/5xx errors are not charged, and that the response is semicolon-delimited text. These go beyond the annotations and are relevant for cost and parsing decisions. It does not mention error handling or rate limits, but the disclosed traits are sufficient for a read-only operation.

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

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

The description is three concise sentences: the first states the core purpose, the second explains pricing, and the third describes the response format. It is front-loaded with the essential function and packs all critical operational details with no waste. 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 is simple (2 params, 1 required) and has an output schema, so return structure is covered. The description adds the pricing model and response format, which are not in the schema or annotations. It does not explicitly mention edge cases like empty results or rate limits, but for a straightforward read-only lookup, the provided details are sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters ('phrase' and 'database'). The description does not add any additional parameter-specific semantics, such as format nuances or examples beyond what the schema provides. Per the rubric, a high-coverage schema earns a baseline of 3, and the description adds no extra value here.

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

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

The description clearly states the tool returns 'Domains and URLs currently ranking in Google organic results for a keyword,' specifying the verb, resource, and scope. It is distinct from siblings like get_semrush_domain_organic_keywords (which returns keywords for a domain) and get_semrush_organic_competitors (which returns competitors), so an agent can differentiate based on the keyword-centric focus.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention that this is the keyword-to-domain lookup as opposed to domain-to-keyword tools, nor does it suggest any conditions for selection. The only context is the tool's name, which implies usage but is not explicit.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses materially important behaviors: the per-row billing at $0.18 (up to 20 rows, header excluded), that 4xx/5xx responses are not charged, and that the response is semicolon-delimited text rather than JSON. These details directly influence invocation and parsing decisions and are absent from the annotations and 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?

Three tight sentences: the first states the core purpose, the second covers billing constraints, and the third flags the response format. Every sentence earns its place and the most important decision-relevant facts (what it returns, what it costs) 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?

For a read-only keyword lookup with an output schema present and annotations covering the safety profile, the description covers the critical invocation facts: cost model, row cap, error-charging policy, and response format. Minor gaps remain (e.g., behavior on empty results, whether the row cap is per phrase), but nothing blocks 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?

The description itself adds no parameter-level detail, but schema coverage is 100%: both `phrase` (with URL-encoding guidance) and `database` (with default `us`) are already documented in the schema. This matches the baseline of 3 where the schema carries the parameter-semantics 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 opening sentence names a specific output ('Domains and URLs currently running Google Ads'), the query basis ('for a keyword'), and the live status of the data. This clearly separates it from the organic counterpart get_semrush_organic_results among the siblings, and the title 'Paid Results' reinforces the distinction.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The intended use case is only implied by the contrast between 'Paid Results' and the sibling get_semrush_organic_results. An agent could infer the choice, but nothing in the description states it.

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

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

Annotations already declare 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 annotations already mark the operation as non-read-only and potentially destructive; the description adds valuable behavior beyond them: synchronous behavior, response envelope behavior, rejection semantics (HTTP 200 still used), measured payload sizes, and billing cost. It does not fully explain what destructive side effect exists, but it also does not contradict the annotations.

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

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

The description is dense but efficiently organized: purpose first, then size, depth choice, cost, and error-envelope behavior. The return-field list is slightly redundant with the output schema, but each other 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?

For a billed live endpoint, the description covers response location, error behavior, cost, depth choice, and approximate response size. The main gap is request-body guidance, but the schema supplies that structure, so the description is otherwise 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?

With schema description coverage at 0%, the description does not compensate for the input contract: it mentions `keyword` only among returned fields and never explains that the caller must send a `body` array containing keyword/location identifiers. The agent must still reverse-engineer request shape from the schema alone.

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

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

The first sentence states a specific operation: return advertisers matching a query in Google's ads transparency data, and it emphasizes the synchronous execution. This clearly differentiates the tool from organic-search and Google Ads search siblings by naming the resource type ('advertisers'). No inference is needed to understand what the tool does.

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

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

The description gives explicit selection guidance among the three result depths, positioning `advanced` as the default and saying when to use `regular or `html`. It does not name sibling tools like `gads_search_live` as exclusions, but the depth-selection rule is clear and actionable.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context: the synchronous nature, the DataForSEO envelope with data in tasks[0].result and status_code, and the critical note that a rejected request still returns HTTP 200. This exceeds what annotations provide and warns the agent about response handling.

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

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

The description is dense but efficient, front-loading the core purpose and then providing operational details (size, cost, envelope). Each sentence adds value; no filler. The length is justified by the amount of critical operational 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 description thoroughly covers output envelope and cost/depth trade-offs, and the output schema handles return values. However, it omits input structure entirely, fails to reconcile the 'keyword' mention with the actual schema fields, and does not explain the anyOf requirement. For a tool with nested array input and multiple optional fields, this is a significant gap.

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

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

The description says 'keyword' but the schema requires either advertiser_ids or target (domain), creating confusion. It provides no explanation of the body array structure, the anyOf constraint, or how to specify location. With schema description coverage reported as 0%, the description fails to compensate for parameter meaning, leaving the agent without guidance on how to construct valid input.

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

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

The description clearly states the tool's function: 'Returns the ads running against a keyword on Google, synchronously.' It specifies the verb (returns), resource (ads), and context (keyword on Google). This distinguishes it from the many sibling tools that return other SERP types (organic, images, etc.) and from the advertiser-focused 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?

The description gives detailed guidance on choosing among the three result depths (regular, advanced, html) and notes this family is the cheapest source of search data. However, it does not explicitly compare against alternative tools (e.g., advertiser_live) or state when to use this tool vs. others, only intra-tool depth selection.

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 profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the bar is lower, but the description adds nothing behavioral: no mention that this is a live (billable, open-world) request, no auth or rate-limit notes, no note on whether the call mutates state or is merely an expensive read. No contradiction with annotations.

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

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

One front-loaded sentence with no filler, so nothing wastes space. However it is under-specified rather than well-scoped; brevity here reflects missing content rather than tight editing.

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

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

An output schema exists, so return values need not be explained, but for a live search endpoint with an opaque body parameter and an open-world/destructive annotation profile, the description supplies neither usage context nor behavioral detail. It is inadequate for an agent to invoke confidently beyond guessing from siblings.

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

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

The single parameter is an opaque 'body' array and schema description coverage is reported at 0% for the top level, so the description must compensate. It says nothing about the required keyword, the location/language fields, or the optional screen/rectangle parameters, leaving the semantics entirely to the nested 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 specific resource (AI Mode search results from Google Search) but is essentially a restatement of the title 'Live Google AI Mode SERP'. It never distinguishes this endpoint from close siblings like post_dataforseo_serp_ai_summary or post_dataforseo_serp_google_organic_live, so an agent cannot route between them 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-selection guidance. With many overlapping SERP siblings in the list, the absence of any routing hint is a real gap.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and non-idempotent, yet the description only says it 'provides' a page, adding no context about the live POST, credit consumption, or side effects. It neither reinforces nor contradicts the annotations, so it contributes essentially nothing beyond the structured 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?

One sentence, front-loaded and free of filler. It is efficient, though for a tool with a nested body and many optional location/language fields the brevity edges toward under-specification rather than true conciseness.

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

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

An output schema exists so return-value explanation is not required, but the description omits the live-POST/credit behavior, the required keyword plus language/location constraints, and any routing guidance among the large family of sibling SERP tools. For this complexity level it leaves too much to the schema and the tool name.

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

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

The description names only keyword, search engine, and location at a high level, while the actual request body fields (language_code/language_name, location_code/location_name/location_coordinate, device) are only documented in the nested schema. With reported top-level coverage at 0%, the description does not compensate for the parameter-documentation gap.

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

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

The description states a specific verb and resource: it returns a raw HTML page of 100 search results for a given keyword. It differentiates itself implicitly from the non-HTML sibling via 'raw HTML page', but it never explicitly contrasts itself with post_dataforseo_serp_google_ai_mode_live or the many other *_live_html siblings, so an agent must infer the AI-Mode-vs-organic distinction from the name alone.

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

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

Nothing is said about when to use this HTML variant versus the structured post_dataforseo_serp_google_ai_mode_live, nor about prerequisites such as required language/location fields or the live-POST nature of the call. Usage must be inferred entirely from the tool name.

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

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

Annotations already provide a full profile (openWorldHint=true, readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds no behavioral context on top of them. It describes a pure informational retrieval yet never reconciles that with the destructiveHint=true / readOnlyHint=false metadata, nor mentions credit consumption, rate limits, or authentication. The tension is real but not an explicit contradiction, since the text makes no safety claim of its own.

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?

Only two sentences and no padding in length, but the lead sentence explains Google's Autocomplete feature rather than the tool's action, so the actual capability is back-loaded behind non-tool context. Front-loading the retrieval action would make every sentence 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?

With annotations and an output schema present, the description does not need to explain return values, and it roughly does anyway. However, it omits any usage framing and does not address the misleading read-only/destructive metadata, leaving an agent with only a bare capability statement for a 1-parameter request that accepts rich nested fields.

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

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

The top-level body parameter is undocumented (reported schema description coverage 0%), so the description must compensate. It names 'a particular keyword' and 'the search client', which partially maps to the nested body fields, but it never explains that body is an array of request objects nor covers the language/location requirements. The nested field descriptions in the schema do carry substantial semantic detail, keeping this at the baseline rather than below it.

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

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

The description names a specific outcome and resource: it returns all Google Autocomplete suggestions for a particular keyword, plus cursor position and search client. An agent can tell what it does, but nothing distinguishes it from siblings like post_dataforseo_labs_google_keyword_suggestions_live or the other SERP tools, and the first sentence is spent explaining what Google Autocomplete is rather than what this tool does.

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

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

There is no when-to-use, when-not-to-use, or alternative-routing guidance. In a sibling set crowded with keyword-suggestion and other SERP endpoints, the agent gets no signal about when autocomplete is the right choice over keyword_suggestions_live or serp_google_organic_live.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=true; the description adds nothing behavioral on top of that (no cost, rate limit, or side-effect detail) and simply describes returned content. The description does not explicitly contradict the annotations — it never claims the call is a safe read — so this is a gap, not a 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?

Purpose is front-loaded in the first sentence. The second sentence ('data from a page of the dataset displayed separately from the SERP') is awkward and largely redundant with the third, but the overall size is reasonable and every part is on-topic.

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, the description need not explain return values, and it correctly focuses on what data is fetched. However, for a live POST endpoint it omits how to obtain the required dataset_id and gives no routing guidance against the very similar dataset_search sibling, leaving the definition minimally viable.

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 per-field descriptions (dataset_id with an example value, device enum 'desktop', the language_code/language_name mutual exclusivity), so the structured data does the heavy lifting. The tool description adds no parameter meaning at all, which is acceptable only because the schema already documents the fields.

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

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

The description states a specific verb+resource: it returns real-time Google Dataset Info for a specified dataset, and lists the content fields (authors, licenses, description). It does not name the sibling post_dataforseo_serp_google_dataset_search_live, which is the obvious near-duplicate an agent could confuse it with, 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?

No when-to-use guidance, no exclusion versus the dataset_search sibling, and no hint that a dataset_id must first be obtained (from a dataset URL or Dataset Search result). The agent gets the what but none of the routing or prerequisite context.

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

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

Annotations already declare openWorldHint=true and the striking destructiveHint=true, which the description never addresses or explains; it only says the tool 'provides real-time data,' which is silent on the tension with a destructive hint. Nothing is said about cost, rate limits, or what the live request actually mutates.

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 resource and result cap, with no padding beyond a mildly redundant closing sentence about optional parameters. Efficient overall.

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, but for a live open-world POST whose annotations flag it destructive, the description is too thin: it omits the array-wrapped request shape, any of the available filter semantics, and any operational caveats an agent would need before invoking.

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

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

Schema description coverage is reported at 0% for the top-level body parameter, and the description contributes only 'other parameters optionally.' It never mentions that the input is an array of request objects, nor any of the meaningful nested filters (file_formats, usage_rights, last_updated, language_code/name) that the schema itself does document.

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: live Google Dataset Search results, capped at the top 20, scoped to the supplied keyword. It is distinguishable from most siblings, though it never differentiates itself from the adjacent post_dataforseo_serp_google_dataset_info_live, which an agent might reasonably confuse it with.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of alternatives like dataset_info_live, and no cost/prerequisite notes. The only guidance offered is the vague 'You can specify other parameters optionally,' which tells the agent nothing about selection.

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 rich operational context far beyond the annotations: byte-size measurements for the three depth options, cost per call, and the envelope contract—'data in tasks[0].result', with 'a rejected request still returns HTTP 200'. This gives the agent concrete expectations about size, cost, and failure semantics that the annotations do not cover.

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 front-loads purpose and response fields, then condenses depth choice and cost into compact, decision-relevant sentences. Some numbers are repeated (e.g., the 57 KB measurement appears twice) and the envelope detail appears late, but every sentence does 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?

With an output schema present and annotations supplied, the description is nearly self-sufficient: it covers what the tool returns, the three depth modes, pricing, and envelope/error behavior. The remaining gap is the undocumented request body, which matters given it is the sole required parameter.

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 carries the burden, but it never explains the body parameter shape: that it is an array of task objects with only keyword required, nor the meaning/selection of location_code, language_code, or coordinate fields. The only request-behavior hint is 'Wrapped in DataForSEO's envelope', which describes response structure, not input semantics.

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

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

The opening line, 'Returns the events Google surfaces for a query on Google, synchronously,' states a specific verb, a specific result type (events), and synchronous delivery. This is enough to distinguish it from siblings like post_dataforseo_serp_google_organic_live or post_dataforseo_serp_google_maps_live without opening their schemas.

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

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

The description gives explicit decision rules for choosing between result depths: 'advanced is the default choice; take regular when only the ranked list matters and html only to check what the parser dropped'. It also frames cost/position relative to the family ('this family is the cheapest source of search data here'), though it does not name an alternative tool for a different SERP type.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the description does not need to restate them. It adds only 'real-time' and the location/language scoping note; it is silent on cost, rate limits, or what makes this call fail, which is meaningful for a live third-party SERP 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?

Two tight sentences with the resource definition front-loaded and no filler. It is appropriately sized, though the second sentence is essentially a restatement of the parameter semantics rather than new guidance.

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

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

An output schema exists, so return values need not be described. However, for a tool sitting in a very large family of finance/SERP variants, the absence of any routing guidance or prerequisite (e.g., needing a valid location/language lookup) leaves a notable gap.

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

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

The top-level parameter is a single body array, and the nested property descriptions in the schema document device, language_code/name, and location_code/name with required-field logic and lookup endpoints. The description adds a slight framing ('specific to the parameters you specify') but omits device and the either-or requirement between code and name fields, so the schema carries most of the 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 names a specific resource (the 'Explore' tab of Google Finance) and states it returns real-time data, which is enough to distinguish it from finance_markets, finance_quote, and finance_ticker_search siblings. It does not name those siblings explicitly, but the scope 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?

It mentions that results depend on the location and language parameters, but never says when to choose this tool over the many finance/SERP siblings, nor any prerequisites or exclusions. No alternative routing is provided.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true). The description adds no behavioral context beyond 'raw HTML' – no note about live-request cost, rate limits, or what the HTML payload contains. It does not contradict the annotations, but it contributes almost nothing.

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 the resource named first. 'These results are specific to the parameters you specify' is somewhat filler, but the whole thing is tight and 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?

An output schema exists, so return values need no explanation. However, for a live, billed SERP endpoint with a nested array parameter body, the description omits any guidance on request shape, cost, or the live-vs-task distinction, leaving 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?

Schema description coverage is reported as 0%, so the description should compensate. It names location and language as the dimensions that shape results, which is meaningful, but says nothing about the code-vs-name duality or the device 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?

States a specific verb+resource: retrieving raw SERP HTML for the 'Explore' tab of Google Finance. This implicitly distinguishes it from the non-HTML sibling post_dataforseo_serp_google_finance_explore_live, 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?

Only says results depend on the specified location and language. There is no when-to-use guidance, no mention of when the HTML variant is preferred over the plain explore_live sibling, and no prerequisites or cost/account notes.

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, openWorldHint=true, and idempotentHint=false. The description only says it provides real-time data and adds no warning about the POST/mutation-style profile, authentication needs, rate limits, or non-idempotency. It does not explicitly contradict the annotations, but it leaves their safety signals 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 with no filler, front-loading the data source and then the parameter scoping. 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?

An output schema exists, so return values need not be explained. Still, for a live endpoint with destructive/openWorld annotations and nested request parameters, the description is thin on operational context beyond the data source and parameter categories.

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 location, language, and market_type as the parameters that shape results. The schema's top-level body parameter has no description, and the description does not explain code-vs-name alternatives, required market_type, or the array/body structure, so it only partially compensates.

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

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

States a specific verb and resource: provides real-time data from the Markets tab of Google Finance. It is clear but does not differentiate from siblings such as finance_quote, finance_explore, finance_ticker_search, or the HTML variant.

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?

Indicates the results are scoped by location, language, and market_type, which implies when to use it for Markets-tab data. However, it gives no explicit when-not guidance and does not name alternative finance endpoints that might be more 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 already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true and idempotentHint=false, and the description adds nothing about credentials, quota/cost per call, or payload size despite returning raw HTML. Worse, 'provides raw HTML' reads as a passive retrieval while the annotations flag a destructive non-read-only POST, so the description leaves the agent guessing about side effects.

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

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

Two short sentences, resource identified up front with no filler. It is efficiently written, but the brevity comes at the cost of the missing required-parameter and sibling information rather than being pure 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?

An output schema exists, so return-value explanation is rightly omitted. However, for a tool with a same-named JSON sibling and a required market_type selector, the description omits both the HTML-vs-JSON choice and the required parameter, leaving real gaps an agent must resolve by opening schemas.

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

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

Schema description coverage is reported as 0% at the top level, so the description is expected to compensate, but it only mentions 'location and language' and omits market_type entirely — the single required field, whose values (most-active, indexes, gainers, losers, cryptocurrencies, currencies, etc.) drive the whole response. It adds no format or default-value detail beyond what the nested schema already lists.

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 resource and scope: raw HTML from the 'Markets' tab of Google Finance, delivered live. An agent can distinguish it from most siblings, though it never explicitly names its closest sibling post_dataforseo_serp_google_finance_markets_live (the JSON counterpart), so the HTML-vs-JSON distinction is left 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 second sentence ('specific to the parameters you specify: location and language') is scoping, not guidance. There is no statement of when to choose this HTML variant over the non-HTML finance_markets_live tool, no prerequisites, and no conditions under which it should not be used.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is somewhat covered. The description adds only that data is real-time from the Quote tab; it omits meaningful behavioral context such as billing (the schema notes a 2x charge for non-1D windows) and any prerequisite handling. Modest added value.

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 resource. No waste or filler, though it stops just short of routing guidance.

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

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

An output schema exists, so return values needn't be described, and the operation itself is simple. However, for a billed, non-idempotent, open-world POST endpoint the description omits prerequisites, cost implications, and parameter-wrapping mechanics, leaving it minimally adequate.

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

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

Top-level schema coverage is 0% (the single 'body' param is undocumented), though nested item fields carry their own descriptions. The description compensates somewhat by mapping 'keyword' to a ticker and naming location and language, which clarifies intent. Still leaves the body-array wrapping and required nested fields 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?

States a specific resource (Google Finance 'Quote' tab data) and that it is live/real-time. It partially differentiates from siblings like finance_markets_live and finance_explore_live by naming the Quote tab, but doesn't explicitly contrast them. Clear enough for an agent to know what it fetches, though sibling differentiation is 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 says results depend on the parameters, but gives no when-to-use guidance, no exclusions, and never mentions the closely related siblings (quote_live_html, finance_markets_live, finance_explore_live). An agent gets no signal on when to pick this over alternatives.

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

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

The description adds one useful behavioral fact beyond the annotations: the return is unrestricted raw HTML rather than structured JSON. It does not contradict the annotations, but it is silent on permissions, rate limits, and the odd destructiveHint=true / readOnlyHint=false profile, which an agent calling a live fetch would want clarified.

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 the core behavior front-loaded, no filler or restatement of the title. Slightly under-specified for the parameter surface, but nothing 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?

An output schema exists, so return values need not be described, and the description correctly notes the raw-HTML payload. What is missing is differentiation from the sibling quote/ticker-search endpoints and coverage of the window parameter, which leaves the agent with avoidable ambiguity.

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

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

Schema description coverage is reported as 0% at the top level, so the description carries some of the burden by telling the agent to put the ticker in the keyword field and that location/language shape results. However, it does not mention the window parameter or the location_code/location_name and language_code/language_name alternatives, leaving real gaps.

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 specific verb+resource: fetching live raw SERP HTML from the 'Quote' tab of Google Finance. This distinguishes it from most siblings, but it never names the non-HTML sibling post_dataforseo_serp_google_finance_quote_live, so the agent must infer the difference from the word 'HTML'.

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 second sentence explains what drives the result (ticker in the keyword field, location, language) but gives no when-to-use or when-not-to-use guidance, and no routing rule versus the many sibling SERP endpoints (e.g. the non-HTML quote endpoint or the ticker_search variant). Usage is implied only.

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 nominally covered. The description adds nothing behavioral beyond 'Live' — no cost/credit implications of a live SERP call, no note that the body is a batch array, and no explanation of the surprising destructive/idempotent flags on what reads like a query operation.

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

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

Two sentences, front-loaded with the purpose, and the second sentence cleanly enumerates the driving parameters. It is slightly padded ('along with additional information') but holds no real 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. Given the tool is one of dozens of Google SERP 'live' endpoints, the description is minimally adequate but leaves gaps: no batch/submit semantics for the required body array, no differentiation among finance siblings, and no explanation of the non-obvious destructiveHint annotation.

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 body array itself is undescribed), and the nested field descriptions are extensive, so the schema carries most of the load. The description does restate that keyword accepts a company or financial instrument name and that location/language matter, which partially compensates, but it omits the array/batch nature of body and the standard placeholder-decoding rules already spelled out in the schema.

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

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

The description states a specific verb and resource: 'search for financial instruments available on Google Finance along with additional information,' which is clear enough to identify a ticker-lookup endpoint. However, it does not distinguish itself from the many finance siblings (google_finance_explore, google_finance_quote, google_finance_markets), so an agent cannot easily tell which finance endpoint to pick from the text alone.

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

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

There is no when-to-use guidance, no mention of alternatives like google_finance_quote or google_finance_explore, and no statement about what this tool is not for. The agent receives no routing help despite sitting in a large family of near-identical finance endpoints.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description's burden is reduced. It adds useful scope context ('real-time', 'top 100 images'), but says nothing about billing impact (the schema notes a 5x charge multiplier for advanced operators), rate limits, or auth requirements.

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. It is appropriately short, though it could have spent that space on the usage/cost guidance it lacks.

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 annotation covers the safety profile. Still incomplete for a live, billed SERP endpoint: no cost signal, no result-volume semantics beyond 'top 100', and no routing guidance among the many live/_html/regular siblings.

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

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

The description maps keyword/search-engine/location to the request body, which mirrors the schema field set. However it adds no syntax, defaults, or format detail (e.g., location_coordinate formatting, language code vs name mutual exclusivity) beyond what the nested schema descriptions already provide.

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: live Google Images SERP returning real-time top 100 image results for a keyword, engine, and location. That is clear enough to distinguish it from most siblings, though it never explicitly names the immediate alternative post_dataforseo_serp_google_images_live_html (the HTML variant).

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, no prerequisites, and no mention of the live (synchronous) vs _html or _submit sibling variants. The agent must infer the selection rationale 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?

Annotations already disclose the safety profile (destructiveHint=true, readOnlyHint=false, non-idempotent, openWorld). The description adds the useful detail that the payload is a raw 100-result HTML page, but omits key behaviour such as the billing multiplier for special operators, the POST/task semantics, and that raw HTML is unstructured versus the parsed 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?

A single efficient sentence with the resource and result count front-loaded and no filler. It is appropriately sized, though it could have used the same budget to mention that this is the images SERP.

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

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

An output schema exists, so return-value explanation is not required, and the description still usefully notes the return is raw HTML of 100 results. For a POST tool with a complex nested body and no usage guidance, the description leaves gaps about when and how to invoke it versus siblings.

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

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

The description names the inputs at a high level (keyword, search engine, location), matching the nested schema fields. The nested schema properties carry rich descriptions, so the description does not need to restate formats like the latitude/longitude/radius coordinate string or the %25 encoding rule; it adds little 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 clear verb+resource (retrieves a raw HTML SERP page) and the result count (100), so the agent knows it is the HTML-format variant. However, it never mentions 'images' (the actual SERP surface) and does not differentiate itself from siblings such as post_dataforseo_serp_google_images_live or post_dataforseo_serp_google_organic_live_html.

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 the HTML variant versus the parsed images_live sibling, no mention of task creation/asynchronous behaviour, and no exclusions or prerequisites. The agent must infer usage entirely from the name.

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

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

Annotations declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the write nature is partly covered, but the description omits the critical behavioral traits of this endpoint: it queues an asynchronous task, is billable (high priority costs extra), and delivers results later via pingback/postback or a separate fetch call.

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 the resource stated up front and no filler. It is not bloated, though given the tool's complexity the brevity comes at the cost of usefulness rather than being purely efficient.

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

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

For a multi-field, billable, asynchronous task-submission endpoint, the description leaves out the async lifecycle, the need to retrieve results separately, and any billing/permission caveats. An output schema exists so return values need not be described, but the operational context is largely 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?

Top-level schema coverage is 0% (the body array itself is undocumented), though the nested item properties are richly described in the schema. The description mentions 'keyword as well as the language and location parameters,' adding only a token gesture at the parameter model without compensating for the missing top-level documentation.

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 resource (SERP data from Google Jobs) but frames the tool as if it returns results directly ('will provide you with SERP data'), whereas the name and title indicate it submits an asynchronous task. It also does not distinguish this submit endpoint from the get_dataforseo_serp_google_jobs_fetch sibling, leaving the verb ambiguous.

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

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

There is no guidance on when to use this tool versus the fetch/fetch_html/locations siblings, and no explanation of the submit-then-fetch workflow. An agent gets no signal about task lifecycle, ordering, or alternatives.

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

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

Annotations already declare openWorldHint=true, destructiveHint=true, and readOnlyHint=false, covering the safety profile. The description adds genuinely useful behavioral context not in the annotations – real-time execution and default result caps of 20 (desktop) / 10 (mobile) – but says nothing about the absence of a device parameter that would make those caps selectable, nor about cost/auth implications.

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 the purpose front-loaded and the result-limit detail second. It is efficient and wastes nothing, though the under-specification is a completeness problem rather than a conciseness virtue.

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

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

An output schema exists, so return-value detail is not required, and annotations carry the safety profile. But for a live SERP endpoint in a dense sibling cluster, the description omits usage routing, device-selection mechanics (the promised desktop/mobile caps have no corresponding parameter), and any mention of the nested body contract.

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

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

Schema description coverage for the top-level parameter is 0% – the required 'body' array carries no description of its own. The description adds no meaning about the body structure, the keyword field, or the location/language alternatives, so it does not compensate for the coverage gap even though the nested field descriptions are 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?

The description states a specific verb (provides real-time search results) and resource (Google Local Finder SERP) scoped by keyword and location, so the core purpose is clear. However, it offers no differentiation from the many sibling SERP tools (e.g. google_maps_live, google_organic_live, google_news_live), leaving the agent unable to distinguish which SERP endpoint to pick from the name alone.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative guidance. For a tool sitting alongside a dozen near-identical SERP and data-source siblings, the absence of any routing cue is a significant gap.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so safety is carried there. The description adds almost nothing beyond that: no cost/call implications, no note that 'live' consumes quota per request, no explanation of why a destructive hint applies to what is essentially a read of external search results — an odd annotation pairing the description does not clarify.

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?

Single sentence, front-loaded with the tool family, no wasteful filler. But it is under-specified rather than concise-with-substance, so it doesn't earn above a middling 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?

For a tool with 0% schema description coverage, an output schema (so return format needn't be explained) but complex conditional parameter rules and non-obvious annotations, the description omits everything an agent needs to invoke it correctly — no parameter rules, no alternative routing, no behavioral caveats.

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 carries the full burden — yet it mentions only 'keyword, search engine, and location' and never addresses the required/conditional logic among language_code/language_name and location_code/location_name/location_coordinate, nor the 'up to 700 characters' and encoding rules that are essential to correct invocation.

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

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

States a specific verb (provides) and resource (raw HTML SERP for Local Finder) and identifies the tool family. However, it doesn't differentiate from its direct sibling post_dataforseo_serp_google_local_finder_live (the presumably structured-data variant), leaving the agent to infer the HTML-vs-structured distinction.

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 mention of alternatives, no prerequisites. The description merely restates what the tool returns; nothing helps an agent decide between this and the non-HTML 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?

Annotations already declare openWorldHint=true, idempotentHint=false, readOnlyHint=false and destructiveHint=true, so the safety profile is partly covered. The description only echoes 'real-time', adding almost nothing beyond structured data: it does not explain that calls bill the account per SERP, that depth above 100 may incur extra charges, or why the operation is flagged destructive. Note the mild tension between the benign 'provides data' framing and destructiveHint=true, though this is not an outright 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?

A single, front-loaded sentence with no filler or redundancy. It is well sized, though arguably under-specified given the tool's billing and location requirements 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?

An output schema exists, so return values need not be explained. However, for a live, billed, non-idempotent endpoint with multi-mode location/language selection, the description omits cost implications and is barely sufficient alongside the annotations.

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

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

Schema description coverage is reported as 0% at the top level, but the single 'body' parameter encapsulates a rich nested object whose properties (depth, keyword, language_code/name, location_code/name/coordinate) are extensively documented in the schema. The description names only keyword, search engine, and location, adding no syntax or format detail beyond what the schema already supplies.

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 concrete verb and resource: it 'provides real-time data on top 100 search engine results' for a keyword, search engine, and location. That is a clear statement of what the tool does, though it does nothing to separate it from sibling SERP tools such as post_dataforseo_serp_google_organic_live or post_dataforseo_serp_google_local_finder_live.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. organic vs local finder vs batch variants), and no prerequisites such as supplying a location or language. The agent gets no routing help from the prose and must infer usage 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false, so the safety profile is covered structurally. The description adds nothing behavioral beyond 'real-time': it omits the critical fact that this endpoint is billed per SERP and that depth>10 can incur extra charges, which the schema only buries in a nested field 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 or repetition. It is efficient, though the brevity is partly under-specification rather than disciplined concision.

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. But for a paid, billed live endpoint with destructiveHint=true annotations and a complex nested body schema, the description leaves out cost implications, the body array structure, and any live-vs-task distinction, leaving the agent under-informed for 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?

Top-level schema description coverage is 0%: the single 'body' parameter has no description, and the description only vaguely echoes 'keyword, search engine, and location'. It does not explain the array-of-object body shape, the required keyword, or the language/location mutual-exclusion rules that a caller must get right.

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 (Google News SERP) and states it returns real-time top results for a keyword, engine, and location, so an agent can tell what it fetches. It does not, however, distinguish this from close siblings like post_dataforseo_serp_google_organic_live or post_dataforseo_serp_bing_organic_live beyond the implicit 'News' in the title, and 'top search engine results' is slightly loose.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling SERP endpoints (organic, bing, maps, youtube, autocomplete). The only implied usage comes from the parameter list, which is 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 states the tool 'provides a raw HTML page', implying a safe read operation, but the annotations declare readOnlyHint=false and destructiveHint=true. This directly contradicts the behavior described, and the description adds no other behavioral context such as cost, rate limits, or 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?

The description is a single, front-loaded sentence with no wasted language. Its brevity is appropriate, though the content is under-informative for the tool's complexity.

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

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

Given the many sibling tools, nested array schema, and contradictory annotations, the description is too sparse. It omits the Google News vertical, the task-array structure, and any behavioral or routing guidance needed to call the tool correctly.

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

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

Schema description coverage is 0% at the top level, and the description mentions a 'search engine' parameter that does not exist in the schema while omitting the fact that the body is an array of task objects. It does not compensate for the missing top-level body 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 ('provides') and resource ('raw HTML page of 10 search engine results'), making the general purpose clear. However, it fails to identify the tool as Google News-specific and mentions a 'search engine' parameter that does not exist, so it does not distinguish this tool from the many other SERP HTML 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 guidance is provided. The description does not explain when to choose this HTML endpoint over the non-HTML Google News live endpoint or other SERP HTML variants, leaving the agent without routing 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 declare the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the description does not need to restate it. The description adds only modest extra context — that results are 'real-time' and include featured snippets and other SERP extras — while omitting the highest-impact trait, per-task billing and surcharges (depth>10, special operators), which is the real reason this POST is not read-only. No contradiction with the annotations, but a notable gap.

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

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

Two sentences with no padding, and the core capability is front-loaded in the first sentence. It is efficient, though the second sentence is largely decorative detail about featured snippets rather than information that changes how the tool is called.

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 billed, non-idempotent POST with a nested body array, ten optional fields and cost multipliers, the description says nothing about credit consumption, batch usage or required inputs. An output schema exists, so return values need not be explained, but the pre-call operational context an agent needs is absent.

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

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

Reported schema description coverage for the sole top-level parameter (body) is 0%, so the description is expected to compensate; it names only keyword, search engine and location, adding no syntax, format or default information. The nested item schema is detailed in its own right, which keeps this above a 1, but the description leaves required fields, batch-array semantics and billing-affecting options entirely to the schema.

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

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

States a concrete verb+resource: retrieving real-time top organic Google search results for a given keyword, engine and location, plus the extra SERP elements (featured snippets) it returns. An agent can distinguish it from siblings like bing_organic_live, google_news_live or google_maps_live from the organic/featured-snippet framing, though the description never explicitly says 'Google' or contrasts with 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?

There is no explicit when-to-use or when-not-to-use guidance and no alternative named, despite a large sibling set (news, maps, local finder, AI mode, Bing, YouTube). Usage is only implicit in 'real-time data', leaving the agent to infer that this is for live Google organic rankings.

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) already establish the safety profile, so the bar is lower, yet the description adds almost nothing: no mention of the per-task/per-SERP billing, no note that this is a live billed call, and no distinction between 'raw HTML' and the parsed output of sibling tools.

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. It is efficient, though somewhat under-specified rather than genuinely concise — there is room to add one routing sentence without bloat.

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

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

The output schema exists, so return-value detail is unnecessary, but for a live POST endpoint in a crowded family of near-identical Google SERP tools, the definition omits cost implications, live vs. batch/fetch semantics, and any differentiation from the regular JSON sibling — gaps an agent needs to select correctly.

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

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

Reported schema description coverage is 0% at the top level, so the description is expected to compensate. It does name the three core inputs (keyword, search engine, location), which maps loosely onto keyword/se_domain/location_* fields, but ignores the OS/device, depth, max_crawl_pages, tag, and language parameters.

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

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

The description names the resource (Live SERP HTML) and the discriminating trait — it returns a 'raw HTML page' rather than structured results — plus the key inputs (keyword, search engine, location). This implicitly separates it from post_dataforseo_serp_google_organic_live and ..._live_regular, though it 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?

No when-to-use guidance at all. For a tool whose only real reason to exist is the HTML output format, it should say when raw HTML is preferable to the JSON-producing siblings, and it should flag that this is a live (billed, non-cached) 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?

Annotations already carry the safety profile (destructiveHint=true, openWorldHint=true, idempotentHint=false), so the description's job is to add context. It only restates 'real-time data', which duplicates the 'Live' in the title, and omits material behavior such as the per-SERP billing mentioned in the schema and the payload/credit implications of running a live 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?

A single front-loaded sentence with no filler. It is efficient, though arguably too terse given the complexity of the request body it wraps.

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

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

An output schema exists, so return values need not be described. But for a billable live-API tool wrapping a complex nested body with sibling ambiguity, the description leaves out cost/credential context and the regular-vs-plain-vs-html distinction, making it incomplete enough that an agent could mis-invoke it.

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

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

The description names keyword, search engine and location, which maps loosely to a few of the nested fields, but the schema's item properties (keyword, device, os, depth, language, location, max_crawl_pages) already document these in far greater detail. The description adds no syntax, format, or mutual-exclusivity information 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 clear verb and resource: it returns live search engine results for a given keyword, engine and location. However, it does not differentiate itself from the sibling `post_dataforseo_serp_google_organic_live` (the non-'regular' variant) or the `_html` variant, so an agent cannot tell which of these near-identical names to pick.

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

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

No when-to-use guidance and no routing to alternatives. With siblings like `post_dataforseo_serp_google_organic_live`, `..._live_html`, and `..._live_regular`, the description gives no basis for choosing among them.

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 a destructive, non-idempotent, open-world write operation, yet the description gives no indication that this submits a billable asynchronous task. It reads like a read-only retrieval, omitting cost, task queueing, and postback mechanics.

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 redundancy. However, the sentences focus on API capability rather than tool action, so they are concise but not optimally front-loaded for agent decision-making.

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 submit-task tool with destructive annotations and async behavior, the description omits critical operational context: that it creates a task, may incur costs, and requires later fetching. The output schema covers return values, but the action model 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 nested schema provides rich descriptions for all task fields, so the schema carries the parameter semantics. The description adds nothing, but baseline 3 is appropriate given the schema's detail, though the top-level 'body' array lacks a 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 describes the API's output ('provides up to top 100 search engine results') but never states that this tool submits a task for asynchronous processing. The title says 'Setting ... Tasks', but the body implies direct retrieval, making it ambiguous versus live/fetch 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 guidance on when to use this submit tool versus live, fetch, or fetch_html alternatives. The references to Locations and Languages lists are not usage instructions.

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.