ScrapeUnblocker

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

Beyond the readOnly/openWorld annotations, the description discloses real behavioral context: price is set by the IP-inferred delivery location, proxy_country defaults to the marketplace's home country, the request is routed through in-country proxies, and exitCountry is reported back. Billing behavior is also disclosed, though the "listing plugins bill one unit per result page... keep max_results modest" clause references a parameter that does not exist here and reads as copied from a search tool.

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 field enumeration is front-loaded and the proxy/currency explanation is well placed, but the return-field list is a long comma chain and the final billing sentence drags in an irrelevant `max_results` concept. That stray sentence is not just redundant, it actively suggests a parameter the tool lacks.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does so thoroughly (title, price, availability, features, categories, images, exitCountry). Missing only failure-mode context such as behavior when an ASIN is invalid or a page is blocked.

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

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

With schema description coverage at 100%, the schema already documents all four parameters, including the proxy_country/currency rationale. The description restates the asin-or-url choice and the proxy_country default without adding format, validation, or precedence detail beyond what the schema provides, 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 opening sentence names a specific verb and resource ("Fetches a single Amazon product") and enumerates the JSON fields returned, so an agent knows both what it gets and that it is a single-item lookup rather than a search. This distinguishes it from siblings like amazon_search and amazon_reviews without ambiguity.

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 selection rule for inputs ("Identify the product with either `asin` (plus `marketplace`) or a full product `url`"), which is genuinely useful, but it never names an alternative sibling (amazon_search, browse_page, fetch_html) or states when not to use it. The closing sentence about "listing plugins" and "max_results" does not map to any parameter on this tool and muddies rather than clarifies usage.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description goes much further by disclosing the signed-out visibility limit, the typical 5-13 review window with local reviews first, the reviewsGated flag and empty-reviews fallback, the guarantee that all fields are present and null when absent, and the proxy_country/exitCountry 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?

It is front-loaded with return fields and covers the essentials, but the single dense paragraph enumerates every field rather than summarizing, repeats 'JSON' twice, and ends with an off-target billing sentence about max_results that does not correspond to any parameter here.

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, so the field-by-field return description is doing necessary work, and the gating behavior, null semantics, and proxy defaults leave nothing an agent needs to know before calling this tool 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 coverage is already 100%, but the description adds real meaning: the asin+marketplace vs url either/or identification rule, and the clarification that proxy_country does not change which reviews are returned (only exitCountry reports it). The closing reference to 'max_results' is confusing because no such parameter exists in the schema.

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

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

The description opens with a concrete verb and resource ('Returns the review data an Amazon product page shows to a signed-out visitor') and immediately enumerates what is returned (rating, reviewCount, histogram, customersSay, reviews), which separates it from amazon_product, amazon_search and trustpilot_reviews without the agent needing to open 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?

Usage context is explicit: it explains this is the public review slice on the product page, not a complete export, and that amazon.com often gates reviews with reviewsGated=true. It stops short of naming alternatives (e.g. use amazon_product for price/details), so the agent must infer those boundaries, which is the only gap.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing two non-obvious behaviors: cards with no visible price return `price: null` and are deliberately retained rather than dropped, and `proxy_country` defaults to the marketplace home country so currency matches expectations. It also surfaces a cost model (one billing unit per result page) and advises keeping result volume modest, which materially affects call strategy.

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

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

Front-loaded with purpose and return shape, then filters, then the detail-fetch route, then edge cases and cost — a sensible ordering. There is minor waste: "Returns JSON" repeats the opening "returns the result cards as JSON," and the billing sentence mentions `max_results`, a parameter that is not present in this tool's schema.

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

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

With no output schema, the description usefully enumerates the returned fields and explains the null-price edge case, which is exactly what an agent needs for a 7-parameter scrape tool. The only flaw is the dangling reference to `max_results`, which does not exist in the input schema and could mislead an agent into passing an unsupported argument.

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 is already documented structurally; the description largely restates the sort options, paging, and price filters. It does add the rationale that proxy_country exists to keep currency consistent, but it introduces no new syntax or semantics for the remaining parameters.

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

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

States a specific verb and resource ("Searches any regional Amazon marketplace for `keyword`") and immediately enumerates the returned card fields. It also distinguishes itself from the sibling detail tool by naming the `POST /marketplace/amazon-product` endpoint used to fetch full records, so an agent can tell them apart without opening either schema.

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

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

Gives clear routing guidance: use this tool for listing cards, then call the amazon-product endpoint for full detail, and use `min_price`/`max_price`/`sort`/`page` to narrow results. It does not explicitly contrast with non-Amazon siblings (ebay_search, walmart_search, google_shopping), though marketplace identity makes the choice largely self-evident.

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 and openWorldHint, but the description adds genuinely non-obvious behavior: the billing model ('billed like an API request; listing plugins bill one unit per result page they fetch') and the pagination-driven cost of max_results. It stops short of noting rate limits, failure modes, or whether scraping can return partial pages.

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

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

Front-loaded with purpose and return shape, then constraints, which is the right order. The trailing standalone 'Returns JSON.' repeats the earlier 'returns the properties as JSON' and is the one sentence that does not earn its place.

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

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

With no output schema, the description compensates by listing the response fields, and it covers cost, pagination, and the date requirement for prices. Minor gaps remain around defaults for adults/rooms and how proxy_country affects results, but nothing that would cause a mis-call.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the cross-parameter dependency that the schema only hints at (prices require checkin/checkout) and by framing max_results as a cross-page collection budget rather than a page size.

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

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

The description opens with a specific verb and resource ('Searches Booking.com for `location`') and enumerates the returned fields (name, price, reviewScore, address, coordinates, image, url), which makes it unmistakable against generic siblings like browse_page or google_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?

It gives one useful conditional ('Prices only appear when check-in/check-out dates are given') and a cost-avoidance nudge ('keep max_results modest'), but it never says when to prefer this over zillow_search, google_shopping, or maps_place_details, so 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 flag destructive, non-idempotent, and open-world behavior, but the description adds important operational detail: steps run once per call and are not retried, and a failed step returns the failing step plus the page HTML at that point. It also discloses that billing is one request, giving the agent context beyond the annotations.

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

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

The description is front-loaded with the core behavior, then adds selector discovery, safety exclusions, failure semantics, and billing in focused clauses. The parenthetical action examples slightly duplicate the enum, but they serve as a useful quick capability summary.

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

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

For a complex, destructive, open-world browser automation tool with no output schema, the description covers purpose, execution model, safety limits, failure return shape, and billing. The agent has enough context to invoke it correctly, while the fully described schema supplies the parameter details.

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 each parameter in detail. The description still adds step-level meaning by saying steps are ordered, non-idempotent, and not retried; it does not add much for wait_method, wait_value, or proxy_country beyond the schema.

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

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

The description states a specific verb-resource pair: load a web page in a real browser, run ordered browser actions, then return the resulting HTML. It distinguishes the tool from read-only fetch siblings by emphasizing real-browser interaction and post-action HTML capture.

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 routes selector discovery to list_elements and gives a clear when-not rule: never use steps to buy, post, delete, or change anything unless the user asked for exactly that. It stops short of naming fetch_html or fetch_markdown as the simpler alternative for non-interactive retrieval, so the main sibling comparison is left implicit.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds real behavioral context beyond them — the no-exact-match fallback where eBay serves loosely related listings flagged by `exactMatches: false` plus a `notice`, and the billing model (one unit per result page fetched). The only weakness is that the cost warning references `max_results`, which is not a parameter name in the schema.

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

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

Front-loaded with purpose and return fields, then filters, then caveats — a sensible ordering with little waste. It loses a point for redundancy: "Returns JSON" is stated at the start and again as a standalone sentence, and the field enumeration partially repeats the filter list.

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 13-parameter scraper with no output schema, the description covers what is returned, how to filter/sort/page, the marketplace-currency implication, the misleading-results fallback, and the cost profile. An agent has everything needed to call it correctly and interpret edge-case responses.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds modest value by grouping the filters and noting that price filters are in the marketplace's currency and that marketplaces differ in price/availability, but it introduces no parameter meaning the schema does not already carry.

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

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

Opens with a specific verb + resource + scope ("Searches any regional eBay marketplace for `keyword` and returns the listings as JSON") and then enumerates the exact return fields, which separates it cleanly from siblings like amazon_search, google_shopping and google_search without requiring the agent to open 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?

Gives concrete operational guidance: which parameters filter, which sort, how to page (with the allowed 60/120/240 sizes), and that `marketplace` should be set when site-specific prices/currency matter. It never states when not to use it or names an alternative tool (e.g. google_shopping or amazon_search), so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and the description adds genuinely new context: the request goes through a third-party anti-bot bypass service (Cloudflare, DataDome, PerimeterX, Akamai, Shape) and returns raw, unstripped HTML. It stops short of disclosing latency, rate limits, cost, or payload size, which matter for a browser-rendering proxy 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?

Four short sentences, front-loaded with what it does, then when to use it, then the return type, then the two alternatives. Every clause carries routing or behavioral information; 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?

Five parameters, all fully documented in the schema, no output schema needed because the description states 'Returns raw HTML'. Combined with annotations and explicit sibling routing, an agent has everything required to choose and invoke it correctly.

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

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

Schema description coverage is 100%, so url, wait_method/wait_value, proxy_country and sleep_seconds are already documented in structured data. The description adds no meaning beyond that – notably it never mentions the render-wait or geo-routing options, so it neither compensates nor detracts; baseline 3 applies.

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

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

Names a specific verb and resource ('Fetch the fully rendered HTML of any web page'), names the provider (ScrapeUnblocker), and explicitly contrasts itself with fetch_markdown and browse_page, so an agent can separate it from siblings 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?

Gives an explicit when-to-use trigger ('when a normal fetch is blocked (403/429, captcha) or the page needs a real browser') and routes two adjacent cases to named alternatives: fetch_markdown for reading/summarising and browse_page for interaction.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds substantive behavior beyond them: browser rendering, anti-blocking capability, size reduction (2-25% of HTML), content stripping, link absolutization, and per-call billing. Those are exactly the facts an agent needs to predict cost and output shape.

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

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

Front-loaded with what the tool does, then output characteristics, then usage and the competing sibling, then cost. Long but dense and every clause carries a distinct decision-relevant fact; no repetition of the title or name.

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

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

For a single-URL fetch tool with no output schema, the description covers origin, rendering behavior, output format, failure modes handled, cost, and the alternative tool. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so every parameter including wait_method, proxy_country, sleep_seconds and main_content_only is already documented in the schema. The description adds no parameter-level guidance (e.g. when to set wait_method or which country codes matter), so it sits at the baseline for a fully documented 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 ('Fetch a web page ... return it as clean Markdown') and defines the output shape precisely: main content, absolute links, no scripts/styles/nav/footer. It also names the sibling it is not (fetch_html) and the condition that selects it, so the agent can differentiate among siblings 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?

Explicit when-to-use ('read, quote or summarise a page', JavaScript-rendered pages, 403/429/captcha walls) and an explicit alternative with its condition ('Use fetch_html instead when you need the markup, selectors or browser steps'). Also discloses billing as one request, which influences selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the JSON-to-rendered-HTML fallback when no structured data exists, and the billing consequence of that fallback. It does not mention authentication, rate limits, or latency for the external ScrapeUnblocker API.

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

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

Two sentences, front-loaded with the core action and output type, then the edge-case fallback. Every clause earns its place: the doc link, the output examples, the no-structure case, and the billing note each add information.

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

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

With no output schema, the description must convey the return shape, and it does: parsed structured JSON with named categories, or the rendered HTML plus an explicit signal when no structured data is found. For a two-parameter read-only tool this is close to sufficient; only external API auth/limits are unaddressed, and those are arguably outside the tool contract.

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

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

Schema description coverage is 100%, with both url and proxy_country documented in-schema, so the schema carries the parameter burden. The description adds only indirect meaning about what the url will yield (product/article/listing parsing); it says nothing about proxy_country or geo-affinity for the parse. 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 web page) plus the distinguishing output: AI-parsed structured JSON rather than raw HTML, with concrete examples of the structured categories (product details, article content, listings). The contrast with 'instead of raw HTML' and the reference to billing 'like fetch_html' makes it separable from the fetch_html/fetch_markdown siblings 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?

Usage context is clear: pick this when you want parsed structured data, and the description warns that pages without structured data fall back to rendered HTML billed like fetch_html, which implicitly signals when the raw-HTML siblings would have been equivalent. There is no explicit 'use fetch_html instead when...' routing statement, so it stops short of full when-not guidance.

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

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

Annotations already cover read-only/open-world/no-destructive, yet the description adds substantial behavior: billing is per fetched page, Google saturates around 400-500 results per query, and every page fetched costs a request. It also discloses a non-obvious edge case (PDF-embedded images return Google's thumbnail as `imageUrl` with `sourcePageUrl` pointing at the document).

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 purpose and scope are front-loaded in the first sentence, and the billing/pagination guidance is appended logically at the end. The long result-field sentence is dense with parentheticals and harder to scan, but nearly every clause carries actionable information rather than 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 takes on the burden of explaining return values and does so field by field, including the thumbnail-vs-original distinction. Combined with billing and market behavior, an agent has everything needed to call this tool correctly and predict cost.

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 baseline is 3, but the description adds real meaning: it explains that `proxy_country` implicitly sets the Google market (`gl`) and that `gl` decides ranking while being only an optional override. It also characterizes `pages` as ~100 each, capped at 5, and billed per page.

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

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

The opening sentence names a specific verb ('Runs'), the exact resource (the Google Images vertical, `udm=2`) and the output form (image results as JSON). This clearly separates it from sibling tools like `google_search` and `google_shopping` without needing to inspect 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?

It gives concrete usage context: `time_range`/date filters for 'repeated scans' returning only new images, and `proxy_country` for market targeting. It also flags the mutual exclusion of `time_range` with date filters. It stops short of explicitly naming a sibling alternative ('use google_search for web pages'), so it is clear but not fully directive.

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 readOnlyHint and openWorldHint already supplied, the description still adds real value beyond the annotations: per-page billing units, a ~20-result cap, and the caveat that `phone`/`website` are null when Google does not render them. The remaining gap is pagination behavior and what happens when the ~20 cap is hit.

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?

Dense and front-loaded: the search verb, the result shape, and the field list come first, with cost and caveats trailing. Minor waste in the redundant closing 'Returns JSON.' after the opening already said results come back as JSON.

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 listing the returned fields and flagging nullable ones, plus cost and locale caveats. It loses a point for the phantom `max_results` reference and for saying nothing about volume beyond ~20 results or about failure/empty-result cases.

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 four parameters are already documented and the baseline is 3. The description reinforces the location-sensitivity of `proxy_country` and mentions `gl`/`hl`, but it also references `max_results`, a parameter that does not exist in the input schema, which muddies rather than clarifies parameter usage.

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 and resource ('Runs a Google Local (`tbm=lcl`) search for `keyword`') and even enumerates the returned business fields, so an agent knows exactly what it produces. It never names the closest sibling (`maps_place_details`, `google_search`), so the boundary between bulk listing scrape and single-place lookup has to be inferred.

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

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

Usage guidance is present but parameter-oriented: it tells the agent to set `proxy_country` (optionally `gl`/`hl`) because local results are location-sensitive, and to keep result volume modest for billing reasons. There is no explicit when-to-use / when-not-to-use statement or named alternative, which is what separates a 5 from a 3 here.

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 that results come from the ScrapeUnblocker API as JSON with a docs link, but discloses nothing about rate limits, cost, latency, or how pages_to_check affects the response beyond the schema's own wording.

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

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

One front-loaded sentence with the action first and the return payload after; nothing is redundant. The long enumeration of result sections is dense but each element carries informational value, so it is not 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?

With no output schema, the description's enumeration of returned sections is genuinely necessary and supplies it well; all three parameters are self-documented in the schema. Remaining gaps — pagination behavior, error/failure modes, and cost of multi-page scraping — are minor for a read-only search tool.

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

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

Schema description coverage is 100%, so the schema already documents keyword, proxy_country (ISO code) and pages_to_check (default 1, max 10). The description adds no per-parameter meaning such as how proxy_country influences results or what happens when multiple pages are requested, 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 ('Run a Google search') and resource, and enumerates the returned content types (organic results, ads, AI Overview, knowledge panel, etc.), which makes the tool's scope unmistakable. It does not explicitly distinguish itself from vertical siblings like google_images, google_local, google_shopping, or the broader search_and_read, so differentiation is only implied.

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

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

Usage is only implied: the agent can infer this is the general web-search tool versus the vertical (images/local/shopping) and page-fetch siblings. There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as search_and_read.

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

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

Beyond the readOnly/openWorld annotations it discloses non-obvious traits: only the first page is returned (v1), there is no per-product URL so `url` is omitted, `image` is best-effort, ids are stable across searches, and listing plugins bill one unit per result page. That is exactly the context annotations cannot carry.

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

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

Front-loaded with what it returns, then parameters, then caveats and billing. Dense but every sentence carries information; the single-block format and parenthetical asides make it slightly harder to scan than a bulleted layout.

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 substitutes by listing every returned field, and it covers pagination limits, missing fields, and cost model. Nothing an agent needs in order to call this correctly appears to be 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 the baseline is 3; the description earns more by explaining why `gl`/`proxy_country` matter (region-specific prices/merchants) and that `productId`/`catalogId`/`offerId` are stable identifiers for tracking a single product.

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 ('Runs the Google Shopping vertical (`udm=28`) for `q` and returns the product cards') and enumerates the returned fields, so an agent can distinguish it from google_search, amazon_search, or walmart_search 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?

Gives concrete guidance on when to set `gl`/`proxy_country` (region-specific prices) and `min_price`/`max_price` filtering, and warns to keep `max_results` modest for cost reasons. It stops short of explicitly naming which sibling tool to use when Google Shopping is wrong, so no full when-not/alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds non-obvious behavior: Cloudflare + PerimeterX anti-bot handling is done for the caller, paging collects up to max_results across pages, `date` sort includes sponsored placements, and the cost model is one billing unit per fetched result page. Only retry/error and rate-limit behavior remain unstated.

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

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

A single front-loaded paragraph that leads with what is searched and returned before filters and cost. It is densely packed with useful content, though "Returns JSON." is redundant with the opening "returns the job listings as JSON" and could be dropped.

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 11-parameter, no-output-schema tool, the description covers the return shape, filtering, pagination, sorting, anti-bot handling, and cost, which is most of what an agent needs to call it correctly. It omits failure modes (blocked requests, zero results) and pagination resume behavior via `start`.

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

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

With 100% schema coverage the baseline is 3, but the description goes beyond the schema by clarifying that `days` is posting age, that `sort=date` returns collected jobs newest-first including sponsored ones, and that `max_results` is accumulated across pages rather than a single-page size. That is real added meaning for the two least obvious parameters.

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

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

The description opens with a concrete verb+resource ("Searches Indeed for `query` in `location` and returns the job listings as JSON") and enumerates the returned fields, so an agent can immediately tell this is the Indeed job-listing tool rather than the google_search, amazon_search, or zillow_search siblings.

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

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

It names the available filter knobs (country, job_type, days, remote), the sort options, and gives an explicit operational constraint: "keep max_results modest" because listing plugins bill one unit per result page. It does not state when to prefer this over a general web search or when results are unavailable, so there are no explicit 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 cover safety (readOnly, non-destructive, open-world). The description earns credit beyond that by disclosing the external ScrapeUnblocker API dependency, the structured non-HTML return format with a ready-to-use selector per element, and the render-wait capability implied by wait params. It does not mention cost, rate limits, or failure behavior, 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, both dense and front-loaded: the return shape and element enumeration come first, the routing guidance second. No filler or restated title 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?

With no output schema, the description compensates by specifying the JSON envelope and element contents, and it also states the downstream workflow. Error handling and pagination/limits on large pages are the only notable omissions for a 5-parameter open-world fetch tool.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including wait_method/wait_value pairing and the ISO country code. The description adds no syntax or constraint detail beyond what the schema provides, 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 page, return its interactive elements), enumerates the element types, and pins down the exact return shape ({url, count, elements:[...]}) while explicitly contrasting it with raw HTML, which distinguishes it from fetch_html/fetch_markdown. An agent can pick it over every sibling 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?

Gives a concrete workflow: discover targets here, then drive the page with browse_page's `steps` param, naming the sibling explicitly. It lacks an explicit when-not (e.g., use fetch_markdown when you want text content), so a small inference remains.

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 and openWorldHint=true, so the agent knows this is a safe read. The description adds genuinely useful context beyond that: the call is free and 'calls nothing', i.e. no scraping request is issued. The mild tension with openWorldHint is best read as the catalog covering an open-ended site list rather than an external call, so it is not a contradiction, but nothing is said about response size or shape beyond 'lists every plugin with its parameters'.

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

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

Front-loaded with the core purpose, and the calling modes come before the ancillary details. The twenty-plus brand enumeration is somewhat padded, but it does convey breadth and searchable examples economically in one parenthetical.

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

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

With no output schema, the description still conveys what comes back: a plugin list with parameters and required markers, or full parameter docs for a single name. The main omission is any pointer to run_plugin for actually executing a discovered plugin, which an agent would need to complete the workflow.

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

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

Schema description coverage is 100% and each parameter already documents itself, including the category enum. The description's only added detail is the default no-argument behavior and the '* = required' marker in the output, which is marginal value over 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 ready-made site plugins) and defines the resource concretely as scrapers returning clean structured JSON for named sites. It also draws the boundary against fetch_html, which is the sibling an agent would otherwise 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?

Explicitly says to check here before scraping a known site with fetch_html, and explains the three calling modes (no args = list all, category/search = narrow, name = full docs). It never names run_plugin, the sibling that actually executes a discovered plugin, so the follow-on step 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, non-destructive, open-world), and the description goes beyond them with genuinely useful operational context: the US proxy default exists to clear Google's consent wall, an EU proxy will hit that wall, and calls are billed per API request. The note about listing plugins and keeping max_results modest is slightly off-target since this tool has no max_results parameter.

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

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

Front-loaded with the outcome, then identifiers, then the proxy caveat and cost note — the ordering matches how an agent needs the information. The field enumeration is long but justified given there is no output schema; the trailing billing sentence drifts into plugin-specific concerns that do not belong to this call.

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 7 optional parameters, no output schema, and no required fields, the description does the heavy lifting well: it lists return fields, explains identifier precedence, and warns about proxy country and billing. Gaps are minor — no guidance on what happens when multiple identifiers are supplied, and none on failure modes for an invalid or unresolvable place.

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 baseline is 3, but the description adds real value by grouping the three mutually substitutable identifier parameters and framing the tool as location-neutral with feature_id resolving the place directly. It omits any elaboration on gl, hl, and raw, which the schema already covers adequately.

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

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

Opens with a specific verb+resource+scope: 'Returns the full data for one Google Maps place as JSON', then enumerates exactly which fields come back. That enumeration plus the identifier options makes it unmistakable versus search-oriented siblings like google_local or google_search, even 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 clearly says how to invoke it (place_id, url, or raw feature_id) and that it is location-neutral, which implies the correct usage pattern: resolve a place elsewhere, then fetch details here. But it never states when to prefer this over google_local or google_search, nor what to do if you only have a name — the usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description's real addition is billing behavior — every run costs like an API request and listing costs per result page — which is genuinely useful context not in the annotations. Beyond that it says nothing about failure modes, rate limits, or auth, so it is a modest add over structured data.

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

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

Front-loaded with the core action and examples, then the prerequisite, then parameter conventions, then cost. Every sentence carries information, though the final billing sentence is the longest and could be trimmed slightly without losing meaning.

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?

Two parameters, one enum and one free-form object, no output schema — the description covers the full calling flow (discover via list_plugins, then run with snake_case params), the return shape (JSON), and the cost model. There is nothing essential an agent would need to call this correctly that is missing.

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

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

Schema coverage is 100% and the 'name' enum is self-documenting, so the baseline would be 3. The description earns above that by explaining that `params` keys must match the snake_case names list_plugins reports and that list values are accepted where a parameter takes several — semantics the free-form `params` object in the schema cannot convey on its own.

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

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

States a specific verb and resource ('Run one ScrapeUnblocker site plugin and return its JSON') and grounds it with concrete examples (Target/Walmart search, Zillow listing search, Google Trends, App Store reviews). It does not, however, distinguish this generic runner from the many sibling tools that do the same job for a single site (amazon_search, walmart_search, zillow_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 an explicit workflow prerequisite ('Find the plugin and its parameters with list_plugins first'), which is the key gating step an agent needs. It stops short of saying when to prefer run_plugin over the dedicated per-site siblings like google_search or indeed_jobs, which is the main ambiguity 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 declare readOnlyHint=true, non-destructive and openWorld, so the safety profile is covered. The description adds substantive behavior beyond that: the billing model ('one request for the search plus one per page read') and the exact shape of what is returned. Missing is any disclosure of failure modes, rate limits, or what happens when a page cannot be read.

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 the return shape, then the usage line, then the billing caveat. No filler or 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?

With no output schema, the description carries the burden of explaining returns and does so precisely: AI Overview when present, `results` pages as Markdown, other organic results as title/URL/snippet. Combined with the cost note, an agent has everything needed to decide and call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by tying the `results` count to cost ('one per page read'), giving the parameter an implication the schema does not state. `proxy_country` and `keyword` are left entirely to the schema, which is acceptable at full coverage.

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?

Uses a specific verb-plus-resource framing ('Search Google... and read the top results in one call') and spells out the composite output: AI Overview, top pages as Markdown, and remaining organic results as title/URL/snippet. That composite shape is enough to tell it apart from plain search siblings like google_search without opening either schema.

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

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

'Use it to answer a question from the live web' gives a clear positive selection criterion. It stops short of naming alternatives or exclusions, though — nothing tells the agent when plain google_search or fetch_markdown would be preferable.

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

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

Beyond readOnlyHint/openWorldHint it adds real behavioral context: a billing model with one unit per fetched page and a caution to keep result counts modest, plus 20 reviews per page and early stop at the last page. It does not state failure modes (unknown domain, missing profile) 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?

Front-loaded with purpose, then response shape, then pagination/filters, then cost note – a logical order with mostly dense phrasing. Minor waste: 'Returns JSON' appears twice, and the parameter list reads as a schema recap.

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 enumerates the response envelope (company summary fields and per-review fields including reply and dates), which is what an agent needs to decide whether to call it. It leaves only error behavior and the proxy parameter 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 coverage is 100%, so every parameter is already documented, and the description largely restates them (page/pages, stars, sort, language, date, search, verified, replies) with a little added context like '20 reviews per page'. proxy_country, the one parameter with non-obvious semantics, is not mentioned at all.

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?

Description opens with a specific verb and resource: returns a company's Trustpilot profile and reviews, keyed on the reviewed domain. It is clearly distinguishable from generic fetch/scrape siblings, though it never names an alternative source tool to contrast 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?

It explains use of pagination and filters and gives a cost warning about keeping max_results modest, implying when to page deep versus just take the summary. There is no explicit when-to-use/when-not guidance or comparison to sibling review tools such as amazon_reviews.

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 material behavior beyond them: the exact payload shape returned, cross-page aggregation, and the billing model per result page with a practical warning to keep max_results modest. It does not mention failure modes common to scraping (blocks, partial pages) or rate limits, so it is strong but not exhaustive.

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

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

Front-loaded with the action and return shape, then controls, then cost, which is a sensible order. Points deducted for the redundant standalone sentence "Returns JSON." after the opening sentence already established a JSON return, which is pure 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 carries the return-value burden and does so by listing the fields, and it explains cost behavior for a paid scraping endpoint. Minor gaps: no mention of what happens at page boundaries or what an empty/failed scrape returns.

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 is already documented in the schema, and the description mostly restates them (`sort`, `min_price`/`max_price`, `max_results`). The only added nuance is that max_results collects products across pages, which the schema also states. Baseline 3 applies; `page` and `proxy_country` are not addressed at all in the prose.

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 ("Searches Walmart ... returns the products") and enumerates the returned fields, which lets an agent distinguish it from amazon_search, ebay_search, or google_shopping purely by store scope. There is no ambiguity about what the tool does.

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

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

Gives concrete usage context: sort with `sort`, bound with `min_price`/`max_price`, and cap volume with `max_results` because listing plugins bill per result page. It does not name alternatives (e.g. when to prefer google_shopping for cross-store comparison) or state exclusions, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description's real contribution is the billing model — one unit per result page fetched — and the cross-page collection behavior, both of which an agent cannot infer from structured fields. It omits anything about rate limits or failure behavior, keeping it short of a 5.

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

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

Front-loaded with purpose, filters, and billing in that order, and the field enumeration is compact. The redundancy of stating 'returns the results as JSON' at the start and 'Returns JSON.' again at the end is wasted space.

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

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

With no output schema, the field-by-field return-value enumeration is genuinely necessary and present, and the billing/paging notes cover the main operational risk. The only real gap is `proxy_country`, whose geo effect on results is never explained even though it can change what an agent gets back.

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 baseline is 3. The description does add paging semantics for `max_results` ('collect ... across pages'), but it duplicates the enum values already in the schema, silently omits the `movie` type the schema allows, and never mentions `proxy_country`.

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 ('Searches YouTube for `query`') plus the return shape. It is clearly distinguishable from `youtube_transcript` by implication, but it never names the sibling or states that it returns listings rather than transcript/text content, so the differentiation is left to inference.

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

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

Gives operational guidance ('filter with type and sort', 'keep max_results modest') but no when-to-use/when-not-to-use framing relative to alternatives such as youtube_transcript or google_search. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: the exact response shape, prefix language matching ('en' matches 'en-US'), and cost character ('Billed like an API request'). The trailing sentence about plugins billing one unit per result page is boilerplate that doesn't apply to this tool and slightly muddies the cost disclosure.

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

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

Front-loads the return payload, then inputs, then use cases — a sensible order with no filler in the first three sentences. The final sentence about plugin billing is irrelevant to this tool and costs it a perfect score.

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

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

With no output schema, the description fully carries the return contract (segments, joined text, availableLanguages, isAutoGenerated, title/author/lengthSeconds) plus input and fallback behavior. For a four-param read-only fetch tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four params including the `en`-matches-`en-US` prefix rule and the format default. The description only restates that `video` takes an id or URL and that `lang` picks a caption track, adding no syntax or edge-case meaning 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?

Opens with a specific verb+resource ('Returns a YouTube video's captions as JSON') and enumerates the returned fields, so the agent knows exactly what it gets. It does not, however, differentiate itself from the sibling youtube_search (e.g., 'use youtube_search first to find a video id'), so routing still requires inference.

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

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

Usage context is implied through the 'Ideal for LLM/RAG pipelines, subtitles and content analysis' sentence and the note that `video` accepts an id or URL, but there is no explicit when-to-use-this-vs-youtube_search guidance or stated prerequisite that a video id must be obtained first. The `lang` omission behavior ('Omit for the default/first track') is the only concrete calling rule.

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

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

Beyond the readOnly/openWorld annotations, the description discloses genuinely non-obvious behavior: pagination (~41 per page) driven by max_results, the rental building variant that lacks `zpid` and instead carries `lotId`, `buildingName`, a price-to-maxPrice rent range, `units` and `availableUnits`, and the billing model (one unit per result page fetched). These are exactly the traits an agent could not infer from the schema or annotations.

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

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

The most important information (location search, returned fields) is front-loaded, and the rental-building edge case and billing warning are placed after the core usage. It is dense but well ordered; the trailing 'Returns JSON.' sentence is redundant with the opening 'returns the listings as JSON' and is the one piece of dead weight.

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 11-parameter scraper with no output schema, the description carries the needed load: it enumerates return fields, explains the anomalous rental-building shape, documents the pagination/cost tradeoff for max_results, and notes proxy_country's role implicitly through the request context. An agent has enough to call this correctly without further discovery.

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 baseline is 3, but the description adds real meaning on top: min_price/max_price also mean monthly rent when status=for_rent, and max_results is framed as collection across multiple pages rather than a single request. The remaining filters (sort, home_type, status) are restated from the schema rather than extended.

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

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

The description opens with a specific verb+resource pair ('Searches Zillow for `location` ... returns the listings as JSON') and enumerates the returned fields, so an agent can distinguish it from the other marketplace scrapers in the sibling list (amazon_search, ebay_search, walmart_search) at a glance.

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 operating context: filter with status/min_price/max_price/beds/baths/home_type, sort with sort, and cap collection with max_results. It also advises keeping max_results modest because of per-page billing. What's missing is any explicit statement of when NOT to use it or a pointer to an alternative sibling, so it stops short of a 5.

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