AIsa Business Listings & Reviews

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 read-only, idempotent, open-world, non-destructive behavior, lowering the bar. The description usefully notes that results are pinned to the establishment/location/language at task-setting time, that personalization is ignored, and that a check_url exists for verification. It says nothing about the 30-day id validity (schema covers it), error cases, or what happens if the task isn't complete.

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 four-sentence paragraph dominated by reassurance about search-accuracy emulation and Incognito verification, none of which helps an agent invoke the tool. The operational fact (what is fetched, from which task id) is absent, so the length is spent poorly rather than front-loading 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?

Output schema and annotations are present, so return format and safety need not be re-explained, but the description omits the essential contract: this fetches the result of an existing submit task, requires a valid task id within its retention window, and may not have results ready yet. For a fetch-by-id tool these are the gaps an agent needs filled.

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

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

Only one parameter, and the schema description already covers it fully (UUID format, task identifier, reusable within 30 days). Schema coverage is 100%, so the baseline of 3 applies; the description adds no parameter meaning of its own.

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 name and title convey the verb (fetch results by id), but the description body never states that it retrieves the results of a previously submitted Google extended-reviews task. Instead it describes characteristics of the returned data (location/language specificity, emulation accuracy). Purpose is inferable but not asserted, and nothing distinguishes it from sibling fetch tools like get_dataforseo_business_google_reviews_fetch.

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

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

There is no guidance on when to call this versus the submit tools it depends on, versus get_details, use, or the other *_fetch siblings. The only actionable hint, 'check the returned results accessing the check_url', is about validating output fidelity, not about tool selection or prerequisites.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: the DataForSEO envelope shape (`tasks[0].result` for data, `tasks[0].status_code` for outcome) and the critical warning that a rejected request still returns HTTP 200. That HTTP-200-on-failure disclosure is high-value context no structured field provides.

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

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

Three tight sentences, front-loaded with the action, then cost, then response envelope. Every sentence carries information; no filler or repetition of the schema.

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, yet the description still supplies the envelope/error-handling context an agent needs to interpret that output correctly. For a single-parameter read tool with full annotations, nothing material is missing.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented in the schema (UUID format, 30-day window). The description only says 'by `id`', adding no new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieves queued Google Business Profile updates by `id`') and enumerates the returned fields (text, media, date). An agent can distinguish this fetch tool from the sibling post_..._gmb_updates_submit without opening either schema.

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

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

The 'charge was on the submit' note implies this is the retrieval half of a submit/fetch pair, which hints at when to use it, but it never names the sibling submit tool or states the precondition (a prior submit producing the id) explicitly. Usage is implied rather than scripted.

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/non-destructive, so the safety profile is covered; beyond that the description adds genuine behavioral context — that results reflect the search state at task-setting time, that personalization/search history is ignored, and that check_url can be used to independently verify fidelity. It does not, however, state the 30-day retrieval window or pagination/result-size 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?

Three sentences are spent entirely on output provenance and verification, which is largely wasted because an output schema already exists. Nothing is front-loaded — the reader never learns the tool's action or its prerequisite, so the content is misallocated rather than tight.

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

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

Because an output schema exists, return-value explanation is unnecessary and the description's budget should have gone to the essentials: that this is the result-retrieval half of a submit/fetch pair and that the id comes from the submit call. Those critical usage facts are missing, leaving the definition incomplete for an agent deciding between it and its many 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?

With one parameter at 100% schema description coverage, the schema fully documents the UUID task identifier and its 30-day usability, so the baseline is 3. The description adds no meaning about the id beyond the vague phrase 'at the time of task setting'.

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

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

The description never states a retrieval verb: it describes what the returned results are scoped to (establishment, search engine, location, language) without saying the tool fetches the stored result of a previously submitted task. Only the tool name/title ('Get ... Results by id') conveys the action, and nothing distinguishes it from sibling fetchers like get_dataforseo_business_google_extended_reviews_fetch or get_dataforseo_business_tripadvisor_reviews_fetch.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of the prerequisite that a task must first be created via post_dataforseo_business_google_reviews_submit. The only actionable hint ('accessing the check_url') is about verifying output, not about choosing this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds only that results are tied to the URL path from the POST request; it omits the 30-day result retention (present only in the schema) and any note on result availability or pagination.

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 what the endpoint returns before the scoping note. Efficient, though the phrase 'feedback data' is slightly vague.

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 safety, a fully documented single parameter, and an output schema handling return values, the description is nearly sufficient. It nevertheless leaves the submit/fetch workflow and the 30-day expiration (only in the schema) implicit, so an agent must infer its place in the pipeline.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema, including the UUID format and 30-day usability window. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description states a clear verb+resource: retrieving Tripadvisor review results (locations, ratings, review content, count) for a given task id. It also notes the results correspond to the URL path from the original POST request, which helps pair it with its submit sibling. It stops short of explicitly distinguishing itself from get_dataforseo_business_tripadvisor_search_fetch.

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

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

Usage is only implied: the mention of 'the POST request' signals this is the retrieval step following a submit task, but there is no explicit when-to-use statement, no mention of the 30-day retrieval window, and no guidance on choosing between this and other Tripadvisor fetch tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered by structured data. The description adds only a mild behavioral note that output is scoped to the location/keyword from the POST request, and omits richer context such as the 30-day id validity (which the schema carries) or result-retrieval semantics. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two sentences, front-loaded with the endpoint purpose, but the second sentence is largely boilerplate about location/keyword scoping and adds little actionable value. It is not bloated, but no sentence is maximally earning its place.

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

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

An output schema exists, so return values need not be explained. However, for a fetch-by-id tool in a submit/fetch pair, the description omits the critical workflow context (that the id originates from the submit sibling and that results are time-limited), leaving the agent to infer the async pattern from the title and schema alone.

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

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

There is a single parameter (id) with 100% schema description coverage, so the schema fully documents it as a UUID task identifier usable for 30 days. The description adds no additional parameter meaning beyond the schema, which is the expected baseline of 3 when the schema does the heavy lifting.

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

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

The description states it returns Tripadvisor business data, which is a clear enough resource, but it never articulates that this is an async fetch-by-task-id endpoint. It does not differentiate itself from the sibling post_dataforseo_business_tripadvisor_search_submit or the reviews fetch tools, so an agent cannot confidently pick it over alternatives 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 explicit when-to-use guidance. The mention that results are 'specific to the location... and keyword parameters used in the POST request' hints at a submit/fetch pairing but never states that this tool should be called after submitting a task or that the id comes from that submission. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them: results are emulated to match the search at task-setting time, personalized search factors are ignored, and results can be independently verified via check_url.

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

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

Front-loaded with the core purpose, but the body is verbose, repetitive, and marred by a missing sentence break ('Trustpilot platform The returned results'). The personalization note earns its place; the emulation-accuracy sentence is largely filler.

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

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

An output schema exists, so return values need not be explained. However, for a single-param retrieval tool in a submit/fetch pair, the description omits the crucial fact that it fetches results for a task created by post_dataforseo_business_trustpilot_reviews_submit, leaving the agent to infer the workflow.

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 1 parameter at 100% schema description coverage, the schema already documents the UUID id and its 30-day usability window. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description states a clear verb+resource: it provides Trustpilot reviews for a business entity. It does not, however, distinguish itself from its sibling get_dataforseo_business_trustpilot_search_fetch or explain that this retrieves results of a previously submitted task (the 'by id' nature is only in the title/schema).

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling submit/search tools it pairs with. The only procedural remark (checking check_url in Incognito) is about verifying results, not about when to call this tool versus 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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context — that personalization and search history are ignored and that results emulate the real search — but it omits the async task model (submit first, then fetch by id) and id expiry, which is only in the schema.

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

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

It is front-loaded with the resource, but a large fraction of the text ('We emulate set parameters with the highest accuracy...', repeated relevance claims) is marketing boilerplate that does not help an agent invoke the tool and dilutes the signal.

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

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

With an output schema present and annotations covering safety, the remaining burden is small; the id semantics are in the schema. However, the boilerplate describes the POST task rather than the fetch, so the async workflow the agent must understand is never made explicit.

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

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

Schema coverage is 100% and the sole id parameter is fully documented as a UUID with a 30-day validity window. The description adds nothing about the parameter, so the baseline of 3 applies — the schema carries the load.

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 resource — 'a list of business profiles listed on the Trustpilot platform' — but frames it around 'the keyword specified in a POST request,' which describes the prior submit task rather than this id-based fetch. It never explicitly distinguishes itself from trustpilot_search_submit or trustpilot_reviews_fetch, leaving the agent to infer the submit/fetch pairing.

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: nothing says this retrieves the results of a previously submitted Trustpilot search task, nor when to prefer it over trustpilot_search_submit or the reviews siblings. The only actionable hint is the incidental mention of check_url for verification.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description states a specific purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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

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

The description implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

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

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

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

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

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

For a zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap for an agent to call it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics gap.

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

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

The description clearly states what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

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

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

The description provides clear usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that: no disclosure that this is an asynchronous billed task, that results arrive via postback/pingback or a separate fetch, or that identifier choice (cid/place_id/keyword) multiplies charges — all of which live only in the schema. The read-framed wording ("provides results") sits awkwardly against write-oriented annotations, though it is a framing mismatch rather than a direct contradiction.

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

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

Two tight, front-loaded sentences with no padding, which is well sized. However, the content is misdirected — both sentences describe a results-returning endpoint rather than the task-submission action, so they do not fully earn their place for this tool.

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

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

For a high-complexity submit tool with 15+ nested body fields and asynchronous, charge-multiplying behavior, the description omits the operation's core mechanics (task creation, deferred retrieval, pingback/postback option). The output schema covers return values, but everything about how and when the task actually executes 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 top-level schema exposes only a single `body` parameter with 0% description coverage, so the description carries the burden of explaining request structure. It compensates only marginally by referencing the List of Locations and List of Languages, saying nothing about the required identifier triad (keyword/cid/place_id) or the body array shape, and adding no syntax beyond what the nested schema already states.

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

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

The description names a clear resource (Google SERP "Reviews" data, including third-party sources like TripAdvisor and Yelp), but the verb is "provides results" for a tool whose name is `..._submit`. It never states that this endpoint creates/queues a task rather than returning data, so it does not differentiate itself from the sibling `get_dataforseo_business_google_extended_reviews_fetch`.

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 submit tool versus the fetch sibling, no mention that it is asynchronous, and no mention of what must be done to retrieve results afterward. The only usage-adjacent content is a pointer to external Location/Language lists, which is parameter help, not when-to-use guidance.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, indicating a non-read-only, potentially destructive, external-interaction operation. The description does not mention that this creates a live task, that it may have side effects, or that it is non-idempotent. It also fails to explain what 'live' means or what happens to previous data, leaving a significant gap for a mutation tool. This is not a contradiction, but the description adds no behavioral context 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 description consists of two sentences that are somewhat concise, but they are generic and not front-loaded with actionable information. The first sentence restates part of the tool name/title, and the second adds minor detail about location/language. There is no wasted text, but the content is insufficient.

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 complexity (nested array parameter with multiple required fields), the presence of an output schema (which the description doesn't need to cover), and the annotations indicating a non-read-only, destructive operation, the description is highly incomplete. It omits any mention of the task creation aspect, parameter requirements, or behavioral implications. The agent would struggle to use this tool correctly.

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

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

The schema description coverage is 0% (per context signals), yet the description provides no information about parameters. The single parameter 'body' is an array of objects with complex nested requirements (keyword, location/language constraints, etc.), none of which are explained in the description. The description completely fails to compensate for the lack of schema documentation, making it impossible for an agent to know how to structure the request.

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

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

The description states the tool provides business entity information from Google, specific to location and language, which gives a rough idea of the resource. However, it doesn't specify that this tool creates a live task (as implied by the tool name and 'Setting' in the title), or distinguish it from siblings like post_dataforseo_business_google_hotel_info_live or post_dataforseo_business_listings_search_live. The verb is vague and the resource is only implied.

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 indication of when to use this tool versus alternatives. The description provides no context about prerequisites, differences from similar tools (e.g., hotel_info_live, hotel_searches_live, qa_live), or any exclusions. The agent is left to infer usage entirely.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds scope context (location/language) but omits the key behavior of a *_submit tool: that it enqueues an asynchronous task whose results must be retrieved separately. The word 'provides' even suggests synchronous results.

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, reasonably front-loaded, but the first sentence carries a typo ('This endpoints provides') and the second is boilerplate scoping text. It is short without being especially information-dense.

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

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

An output schema exists so return values need not be explained. However, for a task-submission endpoint among many siblings, the description omits the async submit-then-fetch workflow and does not clarify the array body, leaving an agent under-informed about 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?

Top-level schema description coverage is 0% for the sole 'body' parameter, so the description must compensate, but it only alludes to location and language settings. It says nothing about the keyword, depth, tag, pingback, or priority fields that actually drive the task.

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

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

The description identifies the resource (latest updates of a business entity from Google SERP) and its location/language scoping. But it uses the verb 'provides,' which reads like a retrieval endpoint, whereas the tool name is 'submit' and it actually creates a task. It also does not distinguish itself from the sibling get_dataforseo_business_google_gmb_updates_fetch.

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 submit endpoint versus the fetch counterpart, no mention of prerequisites (task creation, polling for results), and no alternatives. The only usage hint is the location/language reference.

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 implies a read operation ('provide you with structured data'), but annotations declare destructiveHint=true and readOnlyHint=false. This is a direct contradiction. Additionally, the description omits critical behavioral traits such as the potential double charge when load_prices_by_dates is true.

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

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

The description is a single sentence with a clear lead, but ends with the vague phrase 'and more' and lacks structure for an agent to quickly parse requirements or constraints. It is concise but not optimally structured.

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

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

Given the tool's complexity (a POST body with many optional nested fields, conditional pricing, and required hierarchical parameters), the description is far too thin. It does not explain the request format, authentication, cost implications, or the structure of the 'body' array.

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 'body' has no schema description (coverage 0%), and the tool description says nothing about the parameter structure, required fields, or optional sub-fields. Even though nested properties have descriptions, the top-level parameter is undocumented and the description does not 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 gives a specific verb ('provide') and resource ('structured data for a specific hotel entity on the Google Hotels platform') and enumerates data types. It does not differentiate from sibling tools like post_dataforseo_business_google_hotel_info_live_html or post_dataforseo_business_google_hotel_searches_live, so it falls short of a 5.

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

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

No guidance is given on when to use this tool versus alternatives, nor are prerequisites (API key, pricing implications) or exclusions mentioned. The description only states what it returns.

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

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

Annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true) already carry the safety/idempotency profile, so the description only needs to add context. It usefully discloses that the output is unstructured HTML, but omits that this is a billed POST, that the hotel must first be resolved, and any rate/cost behavior. Note the mild tension: the description reads as a retrieval operation while annotations mark it destructive, though a paid non-idempotent POST is a defensible reading.

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

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

A single front-loaded sentence that leads with what the tool does and then lists the payload. It is slightly list-heavy but contains no filler or redundant restatement of the name.

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

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

An output schema exists, so return values need not be explained, and the description adequately conveys the payload. However, for a tool with a complex nested input body and a close sibling, the absence of routing guidance and parameter context leaves it only minimally complete.

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

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

Reported schema description coverage is 0% and the description says nothing about the input parameters (hotel_identifier, location_*, language_*, check_in/out, adults/children, currency, priority). It neither names the required identifier nor explains the location/language anyOf constraints, so it fails to compensate for the coverage gap.

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

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

States a specific resource (HTML info for a Google Hotels hotel entity) and enumerates the payload it returns (description, location, rating, amenities, reviews, images, prices). An agent can tell what it yields, but the description never distinguishes it from its near-identical sibling post_dataforseo_business_google_hotel_info_live (the non-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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as the non-HTML hotel_info_live endpoint or hotel_searches_live. The only hint is the phrase 'for a specific hotel entity', which is scope, not routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is externally supplied. The description adds nothing about live billing per 18 results, rate limits, or what a 'live' request entails, so it does not enrich behavior beyond the annotations.

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

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

Two short sentences with no waste, and the location/language scoping is stated up front. It is appropriately sized, though the content is largely boilerplate rather than operationally useful.

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 paid, open-world live search this thin description leaves the agent without sibling differentiation, usage conditions, or any hint of the request payload it must construct.

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

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

Schema description coverage is reported at 0% for the top-level body parameter, so the description would need to compensate. It does not: it never mentions the request fields (keyword, depth, dates, guests, filters) despite the nested schema being the whole input. It also does not explain the array-of-requests batch 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 description states a specific verb and resource: it returns hotel results from Google Hotels, and notes they are scoped by location and language. It is clear what the tool does, but it does not distinguish itself from close siblings such as post_dataforseo_business_google_hotel_info_live or post_dataforseo_business_listings_search_live.

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

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

There is no guidance on when to use this tool versus the many sibling search/info endpoints, and no mention of prerequisites beyond a pointer to Locations/Languages lists. An agent gets no routing signal at all.

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

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

Annotations mark the tool as not read-only, destructive, open-world, and non-idempotent, suggesting a mutating operation. The description instead frames it as purely data retrieval, which contradicts the destructive/ write hints (see annotation contradiction flag). Additionally, it does not explain the billing model fully or the destructiveness implied by 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 moderately concise but front-loads less critical information. Some sentences, like the billing and answer limit details, are useful, but the overall structure lacks a clear logical flow from purpose to usage to parameters.

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

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

The tool has an output schema, so return values need not be explained. However, the description does not cover key aspects like the expected input structure (a body array of task objects), authentication needs, or the discrepancy between stated retrieval behavior and the destructive 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 0%, meaning no parameter descriptions are provided in the schema. The tool description fails to compensate, offering no details about required fields, the body array structure, or how to specify a business entity beyond a vague reference to 'location' and 'language' settings.

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 purpose: retrieving questions and answers for a Google My Business entity, with explicit mention of full text and metadata. This distinguishes it from reviews siblings (which fetch reviews) but does not explicitly name those siblings for contrast.

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

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

No guidance on when to use this tool versus alternatives is provided. The description does not mention the sibling review endpoints or explain the differences between live submission and retrieval modes present in other sibling names.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the agent knows it is a write with side effects. The description adds only location/language scoping (already in the schema) and omits the most important behaviors: async task creation, billing per task, and the cost multipliers documented in the schema. It even uses read-like language ('provides results') for a non-readOnly, destructive 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?

It is compact and front-loaded at two sentences, so structure is fine. However the content is misplaced rather than merely sparse, which undercuts the value of the brevity.

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 submit/billing tool the description should explain task queuing and cost implications. Combined with 0% schema description coverage at the top level, the definition leaves an agent without enough to invoke it correctly.

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

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

Top-level schema description coverage is reported at 0% (the only property, 'body', has no description), so the description must compensate and does not. It references location and language conceptually but adds no format, no mention of the cid/place_id/keyword selection logic, cost-multiplying keyword operators, or depth billing.

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 resource (Google SERP Reviews element) but frames the tool as one that 'provides results,' which is the semantic of the sibling get_dataforseo_business_google_reviews_fetch, not a task-submission endpoint. The tool name clearly says 'submit,' yet the description never states that a task is created. An agent cannot tell what operation actually happens.

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

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

No when-to-use guidance is given, and the sibling fetch tool for the same data (get_dataforseo_business_google_reviews_fetch) is never mentioned as the alternative. Nothing explains whether this tool queues an async task versus returning data synchronously.

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

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

Annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false) are not reconciled anywhere in the text; a data-returning listings lookup is described purely as a read, which leaves the agent with no explanation of side effects, cost, billing, or rate limits. The description adds essentially no behavioral context beyond what the annotations already assert, and it does not resolve its own tension with them.

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

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

Three short sentences, purpose front-loaded, no filler or repetition. The closing clause on location settings is slightly awkward but each sentence carries 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-value explanation is unnecessary, and the description does cover the result shape. What is missing for a tool in this dense sibling set is live-vs-task semantics, required location/category setup, and pagination/limits behavior, leaving real gaps for correct invocation.

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

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

The top-level 'body' wrapper is undocumented (schema coverage for the declared parameter is 0%), but the description does add meaning by pointing at the two key inputs: categories ('in the specified categories') and location scoping. The deep nested field docs (limit, offset, offset_token, filters, order_by, location_coordinate) carry the rest, so the description neither compensates for nor undermines the schema.

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

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

The description names the resource (business entities listed on Google Maps) and the payload it returns (address, contacts, rating, working hours), so an agent can tell roughly what it fetches. However it never states the action verb ('search') explicitly and gives no differentiation from the many sibling retrieval endpoints (hotel searches, GMB info, Tripadvisor/Trustpilot search), nor does it explain the 'live' vs 'submit' distinction that separates it from the *_submit 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 when-to-use guidance, no prerequisites, and no named alternative. The only routing hint is an oblique reference to 'the selected location (see the List of Locations) settings', which does not tell an agent when this tool beats a sibling or what must be configured first.

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

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

The description adds meaningful behavioral context beyond the annotations: it reveals that a rejected request still returns HTTP 200, describes DataForSEO's response envelope, notes per-target charging, and explains that the tool reads the platform upstream. It does not contradict the annotations, even though destructiveHint is true, because the description does not claim the operation is safe or non-destructive.

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

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

The core behavior is front-loaded in the first sentence, followed by compact, useful details about return fields, batching, response envelope, and cost. Some content, such as 'Measured at 546 bytes' and the ambiguous final sentence, is marginally useful or confusing, but the description remains dense and structured without becoming bloated.

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 presence of an output schema, the description is not required to explain every return value, and it covers the key operational facts: target list input, per-URL result fields, DataForSEO envelope, HTTP 200 even on rejection, and batching behavior. It leaves out explicit constraints like the 10-target maximum, but that constraint is already visible in the schema, so the description is largely complete for a callable tool.

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

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

The schema coverage signal is 0%, so the description carries the burden of explaining parameters, but it only partially does so: it clarifies that `targets` are URLs to count and that a list is expected, but it never explains the `body` wrapper, the required nested structure, or the `tag` parameter. This is better than no guidance but does not fully compensate for the missing schema descriptions.

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

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

The first sentence states a specific action ('How many times each of `targets` has been pinned on Pinterest') and names the exact value type, page_url, and pins_count fields returned per URL. It is clearly scoped to Pinterest pin-count retrieval, distinguishing it from the Reddit-live sibling and other DataForSEO business tools.

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

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

The description clearly communicates when to use the tool for Pinterest pin counts and that it accepts a list of targets in one call, giving reasonable usage context. However, it does not explicitly say when not to use it or name a concrete alternative, and the final sentence about 'Pinterest content rather than counts' is too vague to serve as an actionable alternative-routing cue.

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 is candid operationally (50304, no tasks array, HTTP 200, measured date), but annotations mark destructiveHint=true while the description presents a read-style count operation and even says the Reddit server reads the platform directly. Since the description contradicts the destructive annotation rather than reconciling with it, the contradiction rule caps this dimension at 1.

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?

Despite its length, every sentence adds value: purpose, availability status, failure signature, envelope behavior, and an alternative. The key warning is front-loaded immediately after the purpose statement, and no filler is present.

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 envelope and top-level failure mode are fully specified, so an agent can detect 50304 even though HTTP status is 200. Given an output schema exists, return-value documentation is unnecessary, and the alternative tools are named; the definition is complete for operational use.

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 reported at 0%, the description needed to explain the body shape; it only echoes `targets` without clarifying the array-of-objects wrapper, the required absolute-URL format, the 10-target maximum, or the per-URL charge. The nested schema provides those details, but the description itself adds minimal parameter semantics beyond naming the key 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?

The first sentence states a concrete contract: 'return Reddit sharing counts for `targets`'. This clearly names the verb, resource, and input scope, and the member name plus sibling list distinguishes it from the other DataForSEO business tools. The intended behavior remains unambiguous even though the endpoint is currently unavailable.

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 explicitly warns that the endpoint is 'currently unavailable upstream' and gives the exact failure signal, so an agent knows not to rely on it. It then names the working Pinterest sibling and the direct Reddit source as alternatives, which is more explicit routing than most tool descriptions provide.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the bar is lower, but the description adds nothing about the write/task-creation behavior, job lifecycle, billing, or return of a task id. Worse, 'provides results' reads like a read operation, which is at odds with the task-submission semantics implied by the name and 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?

It is short and front-loaded, but contains a duplication typo ('and and') and squanders its brevity on vague, uninformative phrasing rather than essential behavior. Length is fine; content density is low.

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 an async task-submission endpoint whose only top-level parameter is an undocumented body array, the description omits the task lifecycle, batching, and any differentiator from the fetch/search siblings. The presence of an output schema excuses explaining return values, but not the missing operational context.

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

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

Schema description coverage is reported as 0% at the top level (the single 'body' parameter has no description), so the description must compensate, and it does not. It never explains the required body array, the url_path/keyword and location mutual-exclusion rules, or any of the filter 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 says the endpoint 'provides results from the Reviews element on Tripadvisor,' which restates the resource but frames it as a read/retrieval endpoint. The tool name is 'submit' and it sits among task-submission siblings, yet the description never states that it creates an asynchronous task. It also fails to distinguish itself from get_dataforseo_business_tripadvisor_reviews_fetch.

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 task-submission endpoint versus the fetch sibling, nor any note about polling the resulting task or batching. The only implied usage is that inputs are scoped by URL path/keyword and location, which is parameter scope, not usage guidance.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, i.e. a non-idempotent write that creates a task. The description instead says the endpoint 'provides a list of business profiles', implying a read. This framing contradicts the write/task-creation semantics declared by the annotations.

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

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

Two tight sentences with no filler; the content is front-loaded. It is well-sized, though what it conveys is misdirected rather than padded.

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

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

For an asynchronous submit tool with a rich input schema (billing, pingback/postback, priority, depth) and an output schema, the description omits the essential task-submission behavior it should be clarifying. It leaves the agent without the context needed to use the tool correctly relative to its fetch sibling.

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

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

The description adds no information about the body parameter or its fields; it only vaguely references 'keyword' and 'location'. With a single required parameter and no coverage contributed by the description, the agent gets no added clarity from the text.

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

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

The description frames this as a retrieval endpoint that 'provides a list of business profiles', but the tool name 'submit' and the sibling 'get_..._tripadvisor_search_fetch' indicate this actually submits an asynchronous search task. It identifies the data domain (Tripadvisor business profiles) but obscures the core action, making it hard to distinguish from the fetch sibling.

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

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

There is no guidance on when to use this submit tool versus the corresponding fetch tool, nor any mention that it queues a task rather than returning results inline. The agent is left to 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 readOnlyHint=false, destructiveHint=true, and idempotentHint=false, but the description frames the call as simply "providing" reviews, implying a safe read. This contradicts the write/destructive profile and discloses nothing about task queueing, billing per SERP, or pingback/postback notification behavior documented only in the schema.

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

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

It is a single, well-formed sentence with no padding, but that brevity comes from under-specification rather than efficient information delivery.

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 critical context for a billable asynchronous task submission—cost implications, task ID handling, notification callbacks—is absent and the read-like framing is misleading.

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 single top-level parameter is 0%, so the description must compensate, yet it only echoes the domain field and never explains the body array or the tag/depth/sort_by/priority/pingback options. Those fields are documented inside the nested schema, which limits the description's added value.

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

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

The description says the endpoint "provides reviews published on the Trustpilot platform," which frames it as a retrieval operation, while the tool name and annotations indicate it submits a task. It also fails to differentiate from the sibling get_dataforseo_business_trustpilot_reviews_fetch, which is the actual fetching 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?

There is no guidance on when to use this submit tool versus the _fetch sibling, no mention that it enqueues an asynchronous task, and no prerequisites. The agent has to infer everything from the name alone.

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

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

Annotations declare a destructive, non-idempotent, open-world write operation, but the description says nothing about task submission, asynchronous execution, billing (cost per SERP, priority surcharge), or that it enqueues work rather than returning results synchronously. Contrasted against an endpoint that returns a completed list, the description misleads about the operation's nature.

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

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

Two short sentences, front-loaded, with no waste — but the brevity stems from under-specification rather than discipline. It is concise but says nothing that 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 destructive, billed, asynchronous task-submission endpoint with a rich nested schema, no annotations context, and a subtle task/fetch workflow, the description is completely inadequate. It never explains what the call does, how results are retrieved, or any of its many optional parameters.

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

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

Schema description coverage is 0% against the outer body object, and the description adds zero parameter detail. It never mentions keyword, depth, tag, priority, pingback_url, or postback_url — all of which are only described deep in nested item schemas, not at the tool level.

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 endpoint's OUTPUT ('provides a list of business profiles listed on the Trustpilot platform'), not the action the tool performs. The name says 'submit' — this tool creates/submits a search task — but the description never states that. It's essentially a tautological restatement of what the endpoint returns, and it doesn't distinguish this task-submission tool from the live/fetch sibling get_dataforseo_business_trustpilot_search_fetch.

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 submit/fetch task-based workflow, and no routing between this tool and its many siblings (the *_search_fetch variant, the *_reviews_submit variant, etc.). An agent must infer the entire submission-then-fetch pattern from the name alone.

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

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

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.