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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that — the request is proxied through the Decodo Web Scraping API target `amazon_bestsellers` and results come back parsed as JSON — but says nothing about pagination limits, failure modes, or latency for what is an external scrape.

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 plus a docs link: purpose first, then usage intent, then reference material. Nothing is repeated from the schema and 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?

For a three-parameter read-only scrape with full schema coverage and no output schema, the description covers purpose, mechanism, and return type (parsed JSON), plus a docs link for deeper detail. Minor gaps: no mention of domain defaults or pagination depth limits.

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

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

Schema coverage is 100%, so query, domain, and pageFrom are each documented in the schema; baseline is therefore 3. The description adds only that the request is 'for a category', which loosely maps to `query`, and gives no extra detail on domain defaults or pageFrom behavior.

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

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

The description states a specific verb and resource ('Fetch the Amazon Best Sellers list for a category') and notes the parsed-JSON result, which clearly separates it from siblings like amazon_search or amazon_product. It stops short of explicitly naming an alternative tool, but the resource specificity makes selection unambiguous.

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

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

'Use it to see the top-selling products in a category' gives an implied usage context, but there is no explicit when-not guidance and no named alternative (e.g., amazon_product for a single item, amazon_sellers for seller data). The agent must infer the boundaries 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that requests are proxied through the Decodo Web Scraping API and that output is parsed JSON, which is useful context, but says nothing about pagination behavior (pageFrom exists), latency, or how an empty offers list appears.

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 compact sentences: action and return format first, use case second, doc link last. Nothing is wasted, though the docs URL and the API-target parenthetical are somewhat promotional rather than operational.

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 5 parameters, no output schema, and a 100%-described schema, the description covers purpose and return type but not the returned offer structure (price, seller, condition, shipping) an agent needs before consuming the JSON. It is adequate to invoke, but incomplete for interpreting results.

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

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

Schema description coverage is 100%, so every parameter (geo, query, domain, jsRender, pageFrom) is already documented in the schema. The description only restates that query is an ASIN and adds no syntax, default, or interaction details (e.g., how geo and domain combine). Baseline 3 is correct 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 names a specific verb (Fetch) and resource (offers for an Amazon product identified by ASIN), plus the transport layer (Decodo Web Scraping API `amazon_pricing` target) and the response shape (parsed JSON). An agent can distinguish it from amazon_product or amazon_sellers by the stated 'offers / what different sellers charge' framing, though no sibling is named explicitly.

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

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

It gives one positive use case: 'compare what different sellers charge for the same product'. There is no explicit when-not guidance, no mention of when to prefer amazon_product or amazon_sellers instead, and no prerequisites stated. Usage is implied rather than specified.

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, openWorldHint=true and destructiveHint=false, covering the safety profile. The description adds that the result is parsed JSON and identifies the Decodo API target, but it does not disclose rate limits, failure modes, auth needs, or how geo/domain/jsRender affect 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?

Two tight sentences front-load the purpose and usage condition, followed by a documentation link. There is no wasted or redundant text.

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

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

For a four-parameter tool with full schema coverage and annotations, the description covers purpose, usage condition, API target, and return format. Since there is no output schema, it could say more about the returned JSON shape, but it does list representative 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?

Schema description coverage is 100%, so parameter meaning is primarily carried by the schema. The description reinforces that query is the product ASIN, but it does not add meaning for geo, domain, or jsRender beyond what the schema already documents.

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

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

The description states a specific verb and resource: fetch an Amazon product page by ASIN and return parsed JSON details. It implies the ASIN-based use case, which helps distinguish it from search-oriented siblings, but it does not explicitly name those alternatives.

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

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

It gives a clear usage condition: use when you know the product's ASIN and need title, price, rating or description. It does not explicitly state when not to use it or name sibling alternatives like amazon_search.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds useful context that results come from a live scraping API and are returned as parsed JSON, implying real-time fetching, but says nothing about latency, credit cost, rate limits, or failure modes when scraping is blocked.

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: purpose first, then usage, with the docs link last where it belongs. No padding, though the docs URL could arguably be trimmed in favor of inline caveats.

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

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

No output schema exists, and the description does state the return shape (product listings parsed as JSON). For a scoped, low-parameter search tool this is nearly sufficient, with only pagination behavior and result-emptiness handling left unmentioned.

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

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

Schema description coverage is 100%, so all five parameters (geo, query, domain, jsRender, pageFrom) are already documented in the schema. The description only echoes the keyword and domain concept, adding no format or interaction guidance (e.g., how geo interacts with domain). 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 (search) and resource (Amazon product listings), plus the mechanism (Decodo Web Scraping API `amazon_search` target) and return type (JSON). The Amazon qualifier distinguishes it from walmart_search/target_search, but it doesn't explicitly distinguish itself from amazon_bestsellers or amazon_product, which also return Amazon product data.

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

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

"Use it to find products and compare listings on a chosen Amazon domain" gives implied usage context, but there are no exclusions or alternatives named. An agent must infer that amazon_product is for a single ASIN and amazon_bestsellers for ranked lists rather than keyword search.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the Decodo Web Scraping API target name and that the response is parsed JSON, plus a docs link for deeper detail.

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 that front-load the action and resource, followed by a docs URL. Every element earns its place, though the URL adds a bit of trailing bulk.

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 and no output schema, the description tells the agent what is fetched and that it is parsed JSON. For a 4-param, fully-documented-schema tool, this is close to complete; only explicit alternative routing is missing.

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

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

Schema description coverage is 100%, so all four parameters (query, geo, domain, jsRender) are documented in the schema. The description only reinforces that query is a seller ID; the baseline 3 is appropriate 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?

States a specific verb+resource: fetches an Amazon seller profile by seller ID via the Decodo API and returns parsed JSON. The resource (seller profile) is distinct from sibling product/search tools, though no sibling is named explicitly.

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

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

"Use it to check a seller's name, rating and feedback" gives a clear usage context that maps to the resource type. It stops short of naming alternatives or when-not conditions, but no guidance is misleading.

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

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

Annotations already cover safety (readOnlyHint, openWorldHint, destructiveHint=false), so the bar is lower. The description still adds value by disclosing that requests are proxied through the Decodo Web Scraping API (implying external dependency/latency) and that the response is a parsed page rather than raw HTML. It does not mention rate limits, auth, or pagination behavior for pageFrom, which keeps it from a 5.

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

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

Two sentences: purpose/return first, usage and sibling differentiation second, then a docs link. There is no filler and the most important information is front-loaded.

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

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

With no output schema, the description usefully states what comes back (parsed JSON results page), and the schema fully documents inputs. Only minor gaps remain, such as pagination limits or how many results a page contains, which an agent may want when handling pageFrom.

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 all seven parameters, including the deviceType enum, are documented in-schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific verb (search) and resource (Bing, via the Decodo `bing_search` target) and states the return shape ('parsed results page as JSON'). It also distinguishes the tool from the Google sibling by name, so an agent can route correctly without opening a schema.

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

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

It gives an explicit selection condition: use when Bing results are needed specifically, or to compare with Google. That is clear positive guidance and implicitly routes Google-only needs to google_search, though there is no explicit 'do not use when' clause.

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, openWorldHint=true and destructiveHint=false, and the description adds real context: one prompt per call, no conversation history, and that `search` enables ChatGPT's web search. It omits anything on latency, rate limits, error behavior, or the shape of the returned JSON beyond 'parsed as JSON'.

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

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

Three short sentences, front-loaded with the core action and the single-turn constraint, followed by the usage example and a docs link. Nothing is padded or redundant.

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

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

With no output schema, the description does state the return type ('answer parsed as JSON') and the one-shot interaction model, plus a docs link for deeper detail. It could say more about the response envelope, but nothing essential for calling the tool is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description reinforces `search` ('set `search` to let ChatGPT use web search') but adds nothing for `geo`, so it only marginally exceeds the schema baseline.

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

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

States a specific verb and resource: send one prompt to ChatGPT via the Decodo Web Scraping API and return the answer parsed as JSON. It is clear about the single-turn nature of the call, but it never distinguishes itself from sibling LLM-answer tools like perplexity or google_ai_mode.

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?

Gives a concrete use case ('see how ChatGPT answers a question... check how it describes a brand') and a key constraint (no conversation history), which sets expectations about repeated calls. It stops short of naming alternatives or stating when not to use it versus the other AI-answer siblings.

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

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

With annotations already declaring mutation, destructiveness, idempotency, and open-world behavior, the description adds useful outcome context: no further pages are crawled and previously crawled pages remain readable via crawl_results. It does not describe return values or auth requirements, but the key side effect is disclosed.

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

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

The description is two focused sentences with no wasted language. The core action and the preservation of prior results are both front-loaded and easy to scan.

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

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

For a simple one-parameter cancellation tool with rich annotations and no output schema, the description covers the essential behavior: what is stopped, the prerequisite crawl_start reference, and what happens to already-crawled pages. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the single crawlId parameter is fully documented in the schema as the id returned by crawl_start. The description does not add syntax or format details beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Stop a crawl started with crawl_start so it crawls no more pages.' It clearly distinguishes cancellation from starting, checking status, or reading results.

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

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

It gives clear context for when to use this tool: to stop a crawl previously started with crawl_start. It does not explicitly mention alternatives or exclusions, but the usage is readily inferred for a cancel operation.

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

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

Annotations already mark the tool as read-only, open-world, and non-destructive, and the description adds important behavioral details beyond them: context overflow limits, a roughly 50 KB response cap, page splitting with contentPart ranges, and cursor-based pagination. It also explains that a missing nextCursor means all pages have been returned, which is exactly the kind of return behavior an agent needs.

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

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

The description is front-loaded with purpose and timing, then adds only necessary pagination and alternative guidance. Despite covering several behaviors, every sentence contributes to correct invocation.

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

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

There is no output schema, but the description sufficiently explains what is returned, how long pages are handled, and how to retrieve all results. Combined with annotations that cover safety, it is complete for correct 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?

Schema coverage is 100%, so the schema already documents all three parameters. The description still adds meaningful semantics by explaining the pagination flow for cursor/nextCursor and how limit interacts with the 50 KB response cap and split-page behavior.

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

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

The description states a specific verb and resource: return crawled pages as Markdown from a crawl started with crawl_start. It distinguishes this from crawl_start, crawl_status, and the precise-work alternative map plus scrape_as_markdown, so an agent can identify its role without opening sibling 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?

It explicitly says to call this once crawl_status reports the crawl is no longer pending, and it names the alternative for precise work: map plus scrape_as_markdown on the needed pages. This gives clear when-to-use, prerequisite, and alternative 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, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: the call is fire-and-forget and returns an id without waiting, and results can overflow context. It does not mention that repeated calls spawn duplicate crawl jobs (relevant given idempotentHint=false) or any resource/credit cost, which keeps it short of a 5.

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

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

Three sentences, front-loaded with the async return contract, then the sibling routing, then the context-safety caveat and the alternative. No filler and nothing repeated.

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

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

With no output schema, the description still tells the agent what comes back (a crawl id) and how to retrieve the actual content later, and it covers the main hazard (context overflow) for a 9-parameter open-world crawl. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so all nine parameters are already documented and the baseline is 3. The description goes beyond the schema by explaining *why* `limit` is low by default (crawled content can overflow context), which changes how an agent should tune it rather than merely restating the default 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?

States a specific verb and resource ('Start crawling a website') and immediately defines the scope of the operation as asynchronous — it 'returns the crawl id right away, without waiting for it to finish.' It also distinguishes itself from crawl_status, crawl_results, crawl_cancel, and the map/scrape_as_markdown pair, so an agent can place it in the workflow without opening schemas.

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

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

Gives explicit when-to-use routing: check progress with crawl_status, read pages with crawl_results, stop early with crawl_cancel, and for precise work prefer map plus scrape_as_markdown. That is a complete lifecycle plus a stated alternative with the condition that selects 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 cover the safety profile (readOnly, non-destructive, openWorld), so the description's job is to add operational context. It does: it discloses the returned fields and the termination condition, which are not in the annotations. It does not mention polling costs, caching, or the full set of status values, which would have earned a 5.

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

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

Two sentences, no filler, and the core purpose is front-loaded ahead of the termination detail. Every clause carries information an agent needs.

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

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

With no output schema, the description carries the burden of describing return values, and it does name status and the three counters. The remaining gap is that the possible status values beyond "pending" are never listed, so an agent cannot fully reason about terminal states.

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 with 100% schema description coverage, so the schema already explains that crawlId comes from crawl_start. The description adds nothing about the parameter beyond that, which is the baseline case.

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 ('Report the progress of a crawl') and enumerates what is reported: status plus discovered/completed/failed page counts. It ties itself to the sibling crawl_start, which anchors it in the crawl workflow, but never explicitly contrasts itself with crawl_results, the sibling most likely to be confused with 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?

Gives a concrete operational cue: poll this until status is no longer "pending". That tells the agent when to use the tool and when it may stop using it. It stops short of explicitly excluding crawl_results as the tool for retrieving crawl content.

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 and destructiveHint, so the safety profile is covered. The description adds that requests go through the Decodo Web Scraping API and come back as parsed JSON, but says nothing about latency, quota/rate limits, or how heavily the result set is summarized.

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 front-loaded sentences with the purpose first and the practical use case second, followed by a docs link. No filler and no repetition of the title.

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

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

For a simple read-only lookup with full schema coverage and annotations, the description covers what the tool is, what it returns conceptually, and where the reference docs live. The only gap is the shape of the returned ad objects, which no output schema defines.

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 every parameter (geo, locale, jsRender, pageFrom, deviceType) has its own description, so the schema carries the load. The description adds no extra meaning about any of the six parameters, which is the baseline case.

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

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

Names a specific verb and resource: it searches Google and returns the paid Google Ads for a query, parsed as JSON. That distinguishes it from the organic 'google_search' sibling by describing the result set, though it never names an alternative tool outright.

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

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

'Use it to see which advertisers bid on a keyword and what their ads say' gives a concrete use case and context. It stops short of explicit exclusions such as 'use google_search for organic results', leaving the routing decision partly to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the call goes through the Decodo Web Scraping API (implying proxied, possibly rate-limited/latency-bearing access) and that the result is JSON, plus a docs link, but says nothing about latency, quotas, or failure modes.

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 plus a docs link, with the action front-loaded. The parenthetical API target and URL are slightly incidental but useful; nothing is padded.

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

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

For a simple three-parameter read tool with no output schema, the description covers intent and return type ("AI answer as JSON") but leaves the response shape, sourcing behavior, and any limits unstated. Adequate but with visible gaps.

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

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

Schema description coverage is 100%, and all three parameters (query, geo, deviceType) are already documented with examples and an enum in the schema. The description adds no parameter meaning beyond the schema, 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: ask Google AI Mode a question via Decodo and return the AI answer as JSON. It's clear what it does, but it doesn't distinguish itself from close siblings like google_search, chatgpt, or perplexity.

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

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

"Use it to see what Google's AI search says about a query" gives an implied usage context, but there is no guidance on when to prefer this over google_search or chatgpt/perplexity, and no exclusions.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds real context: the request is proxied through Decodo's Web Scraping API and results come back as parsed JSON. It omits any mention of credentials, quota/rate limits, or latency of the rendering path, so not a full 5.

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

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

Two sentences, front-loaded with the action and scope, with the docs link trailing where it belongs. Slightly dense — the API and target-name detail could be trimmed — but every clause 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?

For a 3-parameter, no-output-schema tool, the description tells the agent the return type (parsed JSON visual matches) and the execution path (Decodo proxy). An agent can call it correctly; only error/auth behavior and result structure detail are absent.

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

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

Schema description coverage is 100% with enum and defaults documented, so the baseline is 3. The description only implies that `query` is an image URL and says nothing about `jsRender` or `deviceType` beyond what the 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?

States a specific verb (run) and resource (Google Lens image search on an image URL) and names the backend target (`google_lens`). The image-URL dimension clearly separates it from the text-oriented siblings like google_search and 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?

Gives two concrete use cases: identify what an image shows, or find pages where it appears. That's clear context, but no explicit when-not or named alternative is offered, so it stops short of the 5 bar.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context by revealing the request is proxied through the Decodo Web Scraping API and returns parsed JSON with organic results, but it says nothing about rate limits, credit consumption, pagination, or failure modes despite being a scraping-backed 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 plus a docs URL, with the core action and return format front-loaded. Every element earns its place, though the parenthetical target name is mildly redundant with the tool 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?

With no output schema, the description carries some of the return-value burden and does state 'parsed results page as JSON, including organic results' – helpful but incomplete, since it doesn't describe what other result sections exist or how they are shaped. Combined with fully covered params and adequate annotations, it is minimally sufficient but leaves the agent guessing at the response structure.

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 query, geo, locale, and jsRender are all documented in the schema itself. The description adds no further meaning beyond pointing at the upstream target name; with the schema doing all the work, the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Search Google through the Decodo Web Scraping API") and names the exact return shape ("parsed results page as JSON, including organic results"). It does not, however, differentiate itself from close siblings like bing_search, search, or google_ai_mode, leaving the agent to infer why one Google-flavored search tool should be picked over another.

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

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

"Use it for fresh web results or Google rankings for a query" implies the intended use case, but there are no exclusions and no named alternatives despite five-plus competing search tools in the sibling list. The agent gets a hint of when to reach for it but no guidance on when not to.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, and the description usefully adds the exact upstream target (google_travel_hotels) and the output format (Markdown listings). It does not cover rate limits, pagination depth, or result-count behavior, which keeps it below a 5.

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

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

Two tight sentences: purpose and target first, use case second, docs link last. No filler and the key information is front-loaded.

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

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

With no output schema present, the description responsibly states that results come back as Markdown listings, which is the main thing an agent needs to know about the return value. Pagination semantics and result volume remain unstated, a minor gap for a 5-parameter read 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 every parameter including the enum-constrained deviceType is already documented in the schema. The description adds no parameter-level meaning (e.g., how pageFrom interacts with results or what locale affects), 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: search Google Travel for hotels via the Decodo web scraping API, returning Markdown. The hotel-specific scope distinguishes it implicitly from generic siblings like google_search or scrape_as_markdown, though no sibling is named.

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

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

The sentence 'Use it to find hotel options and prices for a destination' gives a clear use case, but there is no guidance on when to prefer this over google_search or scrape_as_markdown, and no exclusions or prerequisites are 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 read-only, open-world, non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: it does not fetch page content, large sites can overflow context, and the default limit is 10. It does not explain sitemap/domainFilter behavior, but it meaningfully exceeds the annotations.

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

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

Three compact sentences, front-loaded with the core operation and immediately followed by the context-overflow caveat and workflow guidance. No sentence is redundant.

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

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

For an 8-parameter tool with no output schema but full schema descriptions, the description provides the essential mental model and workflow. It omits details about sitemap modes, domainFilter, and geo/locale, but those are fully documented in the schema, so the description is largely complete.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description still adds semantic value by explaining why limit defaults to 10 (context overflow) and why selectPaths/excludePaths should be used to narrow results, rather than merely restating the schema.

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

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

States a specific verb and resource: list URLs on a website without fetching their content. The phrase 'without fetching their content' clearly distinguishes it from scrape_as_markdown and crawl tools, so an agent can select it without opening the schema.

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

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

Explicitly recommends the workflow: 'map the site, then scrape_as_markdown only the pages you need', naming the alternative and the condition that selects it. It also explains when to narrow with selectPaths/excludePaths, leaving little inference.

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

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

Annotations already declare readOnly, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely useful context the annotations do not: statelessness (no conversation history), one prompt per call, JSON-parsed output. It omits anything about credentials, quotas, latency, or failure modes, which is a real gap for a third-party scraping proxy.

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

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

Three short sentences, front-loaded with the action and the stateless constraint, with the docs URL relegated to the end where it belongs. The only cost is that the docs link occupies a sentence without conveying behavior itself.

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

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

For a two-parameter, no-output-schema tool, the description covers what matters: single-turn behavior, that the answer comes back as JSON, and that sources are part of the value. Slight incompleteness in not sketching the JSON payload (answer field, sources field) or noting the stateless implication for follow-ups.

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% for both parameters, so the structured data already documents `prompt` and `geo`; the baseline of 3 applies. The description adds no meaning beyond the schema — nothing about prompt length limits, what a country name does to results, or the default when `geo` is omitted.

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 pairs a concrete verb (send a prompt) with a concrete resource (Perplexity via Decodo's `perplexity` target) and states the return shape (answer parsed as JSON). It does not name the obvious sibling `chatgpt`, which is the main thing keeping it from a 5, since an agent must infer the differentiation 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?

It gives one positive use case ('see how Perplexity answers a question and which sources it draws on') plus an implicit constraint (single prompt, no conversation history). There is no when-not guidance and no explicit alternative such as `chatgpt` or `search`, so selection against siblings rests on inference.

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

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

Adds real behavior beyond the annotations: very long pages are truncated and `tokenLimit` can lower the cap, and it discloses the upstream dependency (Decodo `universal` target). It doesn't mention rate limits, cost, or failure modes for blocked/private pages, keeping it short of 5.

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

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

Two tight sentences: capability first, then the routing rule and truncation caveat, plus a docs link. Nothing repeated from the title and no filler.

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

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

For a read-only single-URL scraper with a fully described schema and no output schema, the description covers what's returned (Markdown) and the main length constraint. Minor gaps: it doesn't say how failures (paywalls, JS-only pages, crawling restrictions) manifest, though jsRender in the schema hints at the JS case.

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 geo, locale, jsRender, and url are already fully documented. The description only reinforces tokenLimit behavior, which the schema also states; baseline 3 is appropriate when the schema carries the parameter 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?

Names a specific verb (fetch) and resource (any public web page via the Decodo Web Scraping API `universal` target) and states the output format (Markdown). This clearly distinguishes it from site-specific siblings like amazon_product or youtube_metadata.

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

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

"Use it to read a specific URL when no site-specific tool fits" gives an explicit selection rule against the many site-specific siblings. It lacks a stated when-not (e.g., dynamic JS-heavy pages needing jsRender, or bulk crawling where crawl_start applies), so not quite a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds useful context about the output format (PNG via the 'universal' target) and a docs link, but does not say how the image is delivered (URL vs base64), whether existing data is affected, or any rate/latency 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?

Two tight sentences: capability plus backend detail first, disambiguation and docs second. No filler, and the most decision-relevant information is front-loaded.

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

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

For a simple two-parameter read tool with rich annotations but no output schema, the description covers purpose, selection criterion, and output type. The one remaining gap is the shape of the returned artifact (image payload vs URL), which is only inferable via the docs link.

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

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

Schema description coverage is 100%, so both `url` and `geo` are already documented in the schema. The description adds nothing about geo behavior or URL formatting, 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 ('Capture a PNG screenshot of a web page') plus the backend mechanism ('universal' target with PNG output). The second sentence draws a clear line against the text-scraping sibling by explaining the visual-vs-text 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?

Gives an explicit selection criterion: use when layout or visuals matter rather than text only, which implicitly routes text extraction to scrape_as_markdown. It stops short of naming that sibling tool or stating exclusions (e.g., dynamic-page caveats, cost/latency tradeoffs).

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds beyond that: results can overflow context and `limit` defaults to 10, which is a real behavioral warning an agent needs before calling. It stops short of noting rate limits or whether results are cached/live.

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

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

Three short sentences, front-loaded with purpose and return shape, then the context-overflow constraint, then the follow-up tool. No sentence is filler.

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

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

With no output schema, the description compensates by naming the returned fields (title, link, description). Combined with full schema coverage for pagination and limit, an agent can call this correctly. The only gap is which search backend powers it, relevant given the crowded search sibling set.

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

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

Schema description coverage is 100%, so all five parameters are already documented, and the description's mention of the `limit` default merely restates the schema default. It adds no meaning for `geo`, `locale` or `page` beyond the schema, 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 gives a specific verb and resource ("Search the web") plus the shape of the result (ranked results with title, link and description), which lets an agent know exactly what it gets back. It does not distinguish this generic `search` from engine-specific siblings such as `google_search`, `bing_search` or `youtube_search`, so sibling differentiation is missing.

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

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

It gives one clear follow-up route ("To read a result, pass its link to scrape_as_markdown"), which is genuinely useful chaining guidance. It offers no guidance on when to pick this over the many engine-specific search siblings, and no exclusions, so usage is only partially implied.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds useful context beyond that: the call routes through the Decodo Web Scraping API, the payload is parsed to JSON, and it returns price/availability/description. It doesn't mention failure modes, rate limits, or blocking risk, which a scraper tool could reasonably disclose.

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

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

Three tight sentences with the action and the return shape front-loaded, followed by the selection hint. The docs URL is a minor but justified addition; nothing is redundant with the title.

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

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

No output schema exists, so the description usefully names what comes back (price, availability, description) as parsed JSON. For a single-required-param read tool with full annotation coverage, that is close to sufficient; only error/empty-result behavior is unaddressed.

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 every parameter including product_id, jsRender, deviceType and deliveryZip is documented in the schema itself. The description adds no syntax or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a Target product page by product ID'), names the underlying API target, and says the result is JSON-parsed details. This clearly separates it from target_search, which would be the discovery path rather than a known-ID lookup.

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

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

'Use it when you know a Target product ID and need its price, availability or description' gives a concrete trigger condition. It stops short of naming target_search as the explicit fallback when you don't have an ID, which keeps it out of 5 territory.

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, non-destructive, and open-world, so the safety profile is covered. The description adds real context beyond that: the request is proxied through a third-party scraping API with linked docs and results come back as Markdown, which tells the agent about output form and external dependency. It does not cover latency, rate limits, or failure 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?

Two tightly written sentences with the purpose and use case front-loaded, plus a docs link. No filler or redundant restatement of the title.

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

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

For a single-shot search tool with full schema coverage and no output schema, the description supplies the return format (Markdown) and the domain, which is everything needed to call it correctly. Minor omissions like pagination or result-count behavior keep it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents query, jsRender, deviceType, and deliveryZip completely. The description only mentions the keyword and the optional delivery ZIP, adding no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: search Target for a keyword via the Decodo Web Scraping API and return Markdown results. It clearly scopes the tool to Target product search, which separates it from generic siblings like search or google_search. It does not, however, explicitly distinguish itself from target_product, which an agent could 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?

The second sentence gives a clear use case: find products sold by the Target retail store, optionally with a delivery ZIP code. That is enough context to select it for product discovery. It stops short of exclusions or naming an alternative (e.g., use target_product for details on a specific item's page).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, yet the description adds genuinely useful context: the response is 'raw HTML, often several hundred KB' (a payload-size warning) and that xhr swaps the return shape entirely. It does not cover auth, rate limits, or failure behavior, so it is not a 5.

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

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

Two sentences plus a docs link, front-loaded with the core action and return type, with zero filler. The long URL is the only mildly wasteful element.

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

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

With no output schema, the description carries the return-value burden and does so for both modes (raw HTML vs XHR JSON list). Both parameters are fully documented in the schema, so the only remaining gap is operational detail like auth or rate limits.

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

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

Schema coverage is 100%, so baseline is 3; however the description adds meaning the schema does not carry plainly, namely that xhr yields 'a JSON list of the page's XHR/fetch requests instead of the HTML.' That clarifies the actual consequence of the flag rather than restating its type.

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

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

The description states a specific verb and resource ('Fetch a TikTok video post by URL') and names the backing API target, so the agent knows exactly what the tool returns. It does not explicitly distinguish itself from scrape_as_markdown, which could also fetch an arbitrary URL, so it stops short of full sibling differentiation.

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

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

'Use it to analyse a specific TikTok video' gives a usage context and the xhr sentence implies a second mode, but there is no guidance on when to prefer scrape_as_markdown or tiktok_shop_url instead, nor any exclusions 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 already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: the request is proxied through the Decodo Web Scraping API under the 'tiktok_shop_product' target, the response is Markdown (important since there is no output schema), and a docs link is provided. It still says nothing about credits, rate limits, or failure modes.

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 action and return format front-loaded, followed by a single docs URL. Nothing is redundant with the title, and every clause carries usable information.

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

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

For a four-parameter read-only scraper with a fully described schema and no output schema, the description covers what it does, how to invoke it, and what comes back (Markdown). Only edge-case behavior — failures, geo-restriction effects of the country parameter, cost — 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?

Schema description coverage is 100%, so all four parameters (country, jsRender, deviceType, product_id) are already documented at the schema level. The description only reinforces product_id and says nothing about country/jsRender/deviceType, so per the baseline rule this sits at 3.

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

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

The description gives a specific verb and resource ('Fetch a TikTok Shop product page by product ID') and states that the result comes back as Markdown via the Decodo Web Scraping API. The clause 'Use it when you know a TikTok Shop product ID' implicitly separates it from URL-based sibling tiktok_shop_url, though no sibling is named explicitly.

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

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

It states a clear trigger ('when you know a TikTok Shop product ID and need its price, seller or description'), which is enough to route an agent away from search-type siblings. It stops short of naming alternatives or stating when not to use it (e.g., when you only have a URL, use tiktok_shop_url).

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 readOnly/openWorld/destructive, so the description's value-add is noting the request is routed through the Decodo Web Scraping API and returns Markdown rather than raw HTML. That extra context on output format is useful. It does not discuss rate limits or result caps, which would be a 5.

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

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

Two short sentences with the purpose and the return type front-loaded, followed by a docs link. Every element earns its place; the only slight cost is the docs URL, which isn't actionable information for the model.

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

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

There is no output schema, and the description compensates by stating results are returned as Markdown. Combined with full schema coverage and annotations, an agent has enough to call the tool correctly; only the result shape (item fields) is left undefined.

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

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

Schema description coverage is 100%, so all four parameters (query, country, jsRender, deviceType) are already documented, including the enum for deviceType. The description adds nothing about parameter semantics, so baseline 3 applies.

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

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

The description gives a specific verb and resource (search TikTok Shop for a keyword) plus the return format (Markdown), so an agent knows exactly what it does. It stops short of naming how it differs from siblings like tiktok_shop_product or tiktok_shop_url, which is the only gap.

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

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

"Use it to find products sold on TikTok Shop in a given country" is implied guidance but never states when not to use it or which sibling to prefer for a direct product/URL lookup. The alternative tool routing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description adds genuinely useful context: it returns the page's raw HTML and warns the payload is often several hundred KB. It does not discuss rate limits, auth, or failure modes, but the key behavioral trait (large raw payload) is disclosed.

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

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

Two tightly written sentences, front-loaded with the action and resource, followed by routing guidance to siblings. Every clause carries information; the size warning earns its place.

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

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

With no output schema, the description correctly compensates by stating the return value is raw HTML. Combined with annotations and full schema coverage, an agent has enough to call it correctly; only minor gaps (e.g. dynamic content handling) remain.

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 both url and jsRender are already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (any TikTok Shop page by URL) and explicitly names the two sibling tools it complements (tiktok_shop_search and tiktok_shop_product). An agent can immediately tell this is the generic URL-based fallback scraper.

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

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

Clearly states when to use it: for TikTok Shop pages the search and product tools do not cover, such as shop or category URLs. It names the alternatives but does not explicitly state when NOT to use it (e.g. for single product pages where the dedicated tool is better).

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 establish read-only, non-destructive, open-world behavior. The description adds useful context that the request goes through the Decodo Web Scraping API's walmart_product target and returns parsed JSON, though it does not discuss failure modes or rate limits.

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

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

The description is two tight sentences plus a documentation link, with purpose and usage condition front-loaded and no wasted language.

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 scraping tool with no output schema, the description gives enough context about source, required input, and returned fields to call it correctly. It could say more about JSON structure or missing-product behavior, but the core information is present.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description mentions only the product ID and adds no extra meaning for storeId, jsRender, or deliveryZip, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: fetch a Walmart product page by product ID and return parsed JSON details. It implicitly distinguishes itself from walmart_search by requiring a known product ID, though it does not explicitly name the sibling 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?

It clearly says to use the tool when you know the product ID and need price, availability, or description. It does not explicitly mention when to use walmart_search instead, but the product-ID condition gives agents enough routing 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 readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds two genuinely useful facts: results come back as Markdown and the call is proxied through the Decodo Web Scraping API. It says nothing about result counts, pagination, latency, or failure modes inherent to scraping, which is the main remaining 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 efficient sentences: the action and return format come first, the optional scoping second, and the docs link last. No wasted clauses, though the docs URL occupies space that could carry a behavioral detail.

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

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

For a read-only search endpoint with full schema coverage and no output schema, the description covers what the tool does, its optional scoping, and its return format (Markdown). Only minor gaps remain around result volume and pagination.

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 defines all four parameters including `jsRender`. The description only echoes `storeId` and `deliveryZip` at a high level and adds no format or behavioral detail (e.g., how storeId affects inventory results). Baseline 3 given 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?

States a specific verb and resource ("Search Walmart for a keyword") plus the return format ("results as Markdown"), and names the underlying service and target. It is clearly distinguishable from siblings like walmart_product or amazon_search by the search-vs-product and Walmart-vs-other-retailer framing, though it never explicitly contrasts with them.

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

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

"Use it to find Walmart products, optionally for a store or delivery ZIP code" gives a usage context and mentions the store/ZIP scenarios, but it restates the purpose rather than providing when-to-use-vs-alternatives guidance. No exclusions, no pointer to walmart_product for detail lookups, no mention of when to prefer google_search or target_search.

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 establish readOnly, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds that calls route through the Decodo Web Scraping API with a named target and return parsed JSON, but says nothing about failure modes, rate limits, pagination, or default value for limit.

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 operation and payload, followed by a docs link that does not crowd out the essential text. No filler, though the docs URL is somewhat take-it-or-leave-it.

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

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

With only two parameters, annotations covering the safety profile, and no output schema, the description supplies what an agent needs: the input identity form, the source API, and the JSON return shape. It lacks detail on the video object fields and whether limit has a default.

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

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

Schema description coverage is 100%, so both 'query' (handle/ID) and 'limit' are documented by the schema itself. The description's 'by handle or ID' merely restates the schema and adds no syntax or constraint detail beyond it, which is the expected baseline.

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

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

States a specific verb and resource ('Fetch the videos of a YouTube channel by handle or ID') and clarifies the return ('parsed as JSON'). The channel-scoped resource distinguishes it from youtube_search and youtube_metadata implicitly, but no sibling is named explicitly.

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

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

'Use it to list what a channel has published' gives a clear positive usage context that no sibling covers as cleanly. There are no exclusions or explicit pointers to alternatives such as youtube_metadata for single-video lookups.

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 and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses the Decodo Web Scraping API backend, the `youtube_metadata` target, JSON return format with example fields, and a docs link. It could still say more about failure behavior for invalid/private IDs.

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 plus a docs URL, front-loaded with the verb and resource, with the usage cue second. The parenthetical target name is slightly redundant with the tool name but does name the API parameter.

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

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

With no output schema, the description compensates by naming example fields (title, channel, views, description) and the JSON format. An agent has enough to select and call it; only edge-case behavior for private/blocked videos is unstated.

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

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

Schema description coverage is 100% and the single `query` param is documented with an example ID in the schema. The description only reinforces that the input is a video ID ('by video ID'), adding no format or validation detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a YouTube video's metadata by video ID') and names the backend target, so the agent knows exactly what it returns. The 'by video ID' scoping implicitly separates it from youtube_channel and youtube_search, but no sibling is named explicitly.

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

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

'Use it when you know the video ID and need details about the video' gives a clear positive trigger. It does not state exclusions or point to youtube_subtitles/youtube_channel for the cases this tool does not cover, so alternatives remain inferential.

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, openWorldHint=true, and destructiveHint=false, so safety is covered structurally. The description adds useful context: results come via the Decodo Web Scraping API's youtube_search target and are returned as JSON, plus a docs URL. It does not discuss rate limits, pagination, or result caps, which keeps it from a 5.

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

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

Two sentences plus a docs link: purpose first, then usage context. No filler and nothing buried later in the text.

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

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

For a single-parameter search tool with no output schema, the description covers purpose, mechanism, and return type adequately. The only gap is that JSON result structure and result-count behavior are left unspecified, which the absence of an output schema makes slightly more noticeable.

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

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

Schema description coverage is 100%, and the single 'query' parameter carries its own description with an example, so the schema does the heavy lifting. The tool description adds no syntax, qualifier, or formatting guidance beyond that, matching the baseline for high-coverage schemas.

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 ('Search YouTube for videos'), names the underlying API target, and describes the return format ('JSON'). It is clearly distinguishable from its siblings youtube_metadata, youtube_channel, and youtube_subtitles.

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?

Gives an explicit use case ('find videos on a topic before fetching their metadata or subtitles'), which also routes the agent along the intended workflow toward youtube_metadata and youtube_subtitles. It does not state when not to use it versus generic search tools, but the platform restriction makes alternatives largely moot.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful context — the third-party API dependency, JSON output, and a docs URL — but says nothing about missing/auto-generated captions, default language behavior when language_code is omitted, failure modes, or rate limits.

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

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

Two tight sentences plus a docs link; the action and resource are front-loaded with no redundant restatement of the title. The docs URL is mildly extraneous but defensible as a pointer to deeper detail.

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

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

With no output schema, the description should say more about the returned JSON structure (segments vs plain text, timestamps) and about the default-language behavior. It is adequate to invoke the tool but leaves meaningful gaps for interpreting results.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples, giving a baseline of 3. The description only reinforces language_code as the language selector and does not clarify what happens by default when it is omitted.

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 ('Fetch the subtitles of a YouTube video by video ID') plus the transport ('through the Decodo Web Scraping API') and the return shape (JSON). An agent can distinguish this from youtube_metadata or youtube_channel without opening any 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?

Gives a clear use context ('read or summarise what is said in a video') and a parameter-level hint for language selection. It does not name alternatives or state when not to use it (e.g., when a video has no captions, or when metadata is what you actually need), so it stops short of explicit routing.

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