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

Beyond the annotations (readOnlyHint, openWorldHint, non-destructive), the description discloses that the call starts a run on Apify's hosted gateway, requires the caller's own APIFY_TOKEN, spends the caller's Apify account credits, and returns dataset rows plus run/dataset IDs for paging. It does not describe run latency or whether the call blocks until the run completes.

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 capability, then segmented into When to use / Returns / Behavior / Docs, so an agent can scan the decision-relevant part first. No sentence is filler; the only redundancy is the title echoed as the opening line, which is minor.

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 12-parameter actor with no output schema, the definition still covers what comes back (one JSON row per result, plus run/dataset IDs for paging), the auth model, cost implications, and read-only safety. It leaves the mechanics of paging a dataset with those IDs unstated and gives no sense of run duration.

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 per-parameter descriptions are unusually rich (billing events, caps, defaults, interactions between flags), so the schema already carries the semantics. The prose names no parameter and adds no syntax, only loosely implying that optional flags exist for inventory, videos and subscription plans. Baseline 3 is appropriate when the schema does this much work.

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

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

The description opens with a specific verb+resource ("A Shopify product scraper for any public Shopify store") and enumerates the payload (variant price, SKU, stock, barcodes, inventory counts, videos, subscription plans) plus the four supported crawl modes. Because every sibling in the list is tied to a different marketplace (Amazon, eBay, Walmart, AliExpress, Etsy, Google Shopping), naming Shopify alone is sufficient 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?

It provides an explicit "When to use" clause scoped to public Shopify stores and need for catalog/pricing/stock data, and it clarifies the input modes (whole catalog, collection, single product URL, keyword search). It stops short of stating when NOT to use it or naming an alternative tool for private/admin APIs or non-Shopify stores.

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 non-idempotent, so that ground is covered; the description still adds real value by disclosing that each call starts one run of a specific Apify Actor via mcp.apify.com, requires the caller's own APIFY_TOKEN, and runs against the caller's Apify account. It also notes the run/dataset IDs used to page through the full dataset, though it does not state that runs consume paid Apify credits.

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?

Sectioned as When to use / Returns / Behavior, with scope stated first, so it is easy to scan. The opening sentence redundantly repeats the title and the field list slightly overlaps the Returns paragraph, but there is no filler prose.

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 20-parameter scraper with no output schema, the description covers the essentials: what it returns (one row per result plus run/dataset IDs for paging), where it executes, and what credentials are needed. It is only marginally thin on pagination semantics and cost implications, which the maxPages and splitByPrice schema fields partially cover.

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 carries enum value explanations, so the schema already does the heavy lifting. The description adds only a summary list of filter families (keywords, category, price, condition, seller, location) and no new meaning beyond it, which is the baseline case for 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?

States a specific verb and resource ('scrape eBay search results, filtered listings and category pages across 8 marketplaces') and enumerates the returned fields, which makes it immediately distinguishable from the Amazon, Walmart, AliExpress and Etsy scrapers in the sibling list.

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

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

There is a labeled 'When to use' line, but it largely restates the capability ('active eBay search results or category listings') rather than giving discriminating conditions. It never says when not to use it, nor when to prefer the keyword-filter path over pasting listing URLs, which is the main decision an agent faces with this tool.

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

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

Annotations already declare readOnly/openWorld/non-idempotent/non-destructive, but the description adds genuinely new context: it starts a run of a named Apify Actor through the mcp.apify.com gateway, requires the caller's own APIFY_TOKEN, consumes the caller's Apify account, and creates run and dataset records. It also clarifies that 'read-only' refers to the source site, resolving what would otherwise look like a tension with the account-side writes. It does not mention rate limits, run duration, or cost.

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 and segmented with When to use / Returns / Behavior / Docs, which is easy to scan. Minor waste: the leading 'Walmart Fast Product Scraper.' restates the title, and the marketing line 'Export data, run via API, schedule and monitor runs, or integrate with other tools' does not help an agent decide or call correctly.

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 and no output schema, the description covers everything an agent needs: input expectation (search/category URLs), return shape (one JSON row per result plus run and dataset IDs for paging), execution model, and auth requirement. Nothing material is left for the caller to guess.

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 startUrls and maxProductsPerStartUrl documented in the schema including an example URL and the listing-order collection rule. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: scrape Walmart.com and Walmart.ca search and category pages, and enumerates the extracted fields (name, priceInfo, availability, averageRating, sellerName). The marketplace domain alone separates it from every listed sibling (Amazon, eBay, AliExpress, Etsy, Google Shopping, Shopify).

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?

An explicit 'When to use' line scopes it to Walmart search or category results with price, availability, rating and seller. It gives no when-not conditions or named alternatives among the sibling marketplace scrapers, so the agent must infer that other retailers are out of scope.

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, non-idempotent, non-destructive, so credit goes to what the description adds: the tool launches a run of the 'epctex/google-shopping-scraper' Actor via Apify's mcp.apify.com gateway, requires the caller's own APIFY_TOKEN, and bills the caller's Apify account. It also explains that the response carries run and dataset IDs for paging the full dataset. It does not quantify cost or latency beyond the schema's 'resource consumption' notes.

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?

Well front-loaded with labeled 'When to use', 'Returns', and 'Behavior' sections and a docs link, so an agent can scan it quickly. The 'Unlock valuable insights from Google Shopping with our Data Extractor' sentence largely restates the title and could be cut.

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, no-output-schema scraping tool the description covers the essentials: what it returns (one row per result plus paging IDs), that it is a hosted Actor run requiring auth, and that it is read-only. Nothing critical is missing, though the absence of an output schema means field-level expectations rely on the summary sentence.

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 (queries, startUrls, countryCode, maxItems, maxItemsPerQuery, and the three include* toggles) is already documented, including precedence rules and enum semantics. The description adds nothing param-specific — it describes output fields rather than how to drive queries, URL vs. query precedence, or country selection. Baseline 3 applies.

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

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

States a concrete verb and resource: extracts Google Shopping results containing reviews, descriptions, prices, merchant details, and affiliation links, and the 'When to use' line narrows it to product/price/merchant/review queries across stores. The resource itself (Google Shopping) differentiates it from the Amazon/eBay/Walmart/AliExpress/Shopify/Etsy siblings without needing to name them. The opening 'Unlock valuable insights' is marketing filler, but the substance behind it is specific.

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 explicit 'When to use' clause gives a clear trigger condition (need Google Shopping results for a query across stores). It stops short of exclusions or naming an alternative sibling scraper for non-Google sources, so the agent still has to infer routing from the resource name.

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

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

Annotations already cover readOnly, openWorld, non-idempotent, and non-destructive behavior, and the description adds meaningful context beyond them: each call starts one run of the Apify Actor through the mcp.apify.com gateway, consumes the caller's own APIFY_TOKEN and Apify account, and only reads public data. It does not mention cost/credit consumption or run duration, so it stops 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?

The description is front-loaded into 'When to use', 'Returns', and 'Behavior' sections, making it easy to scan. The opening sentence partially duplicates the title, and the docs URL at the end is filler but harmless.

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 14-parameter scraper with no output schema, the description explains what comes back (dataset rows as JSON, one per result, plus run and dataset IDs for paging), how the run is executed, and the auth requirement. It does not say how the caller should page the full dataset or what happens on long runs, so it is strong but not exhaustive.

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 14 parameters, including enums and their defaults; the baseline of 3 applies. The description only echoes 'URL and country' and adds no guidance on interplay between options such as maxOffers, scrapeProductDetails, or proxyCountry.

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: scrape Amazon product, search, or category URLs and extract reviews, prices, descriptions, and ASINs without the Amazon API. The title plus the enumeration of extractable fields clearly separates it from siblings like the eBay, Walmart, and AliExpress scrapers. It loses a point only because the opening sentence ('collect data based on URL and country') is vaguer than the details that follow.

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?

An explicit 'When to use' section names the exact trigger: needing Amazon product details or search/category results from product, search, or category URLs. It gives a clear context but never names an alternative tool or states when NOT to use this one, which keeps it from 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 flag read-only, open-world, non-destructive, non-idempotent, but the description adds material context: it starts a run of a specific Apify Actor via mcp.apify.com using the caller's own APIFY_TOKEN and Apify account, and returns dataset rows plus run/dataset IDs for paging. That auth/account/cost-bearing detail is exactly the kind of behavior an agent cannot infer from structured hints.

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

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

Front-loaded and clearly structured with 'When to use', 'Returns' and 'Behavior' labels, making it skimmable. Minor waste: the opening sentence restates the tool title verbatim, and the 'When to use' line repeats the field list from the purpose sentence.

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 12-parameter scraping tool with no output schema, the description supplies the missing return-shape information and the auth/execution model, which is what an agent most needs. It stops short of noting run cost/credits or runtime expectations, but nothing essential for correct invocation 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% and the per-parameter docs are unusually thorough (e.g. minOrders references totalSoldCount and recommends pairing with 'orders' sort; maxResults explains 60-per-page pagination). The description only restates the ship-to/currency dimension already covered by the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search AliExpress by keyword or paste search URLs') and enumerates the returned fields (price, original price, discount, rating, sales volume) scoped to ship-to country and currency. Sibling tools are other marketplaces (Amazon, eBay, Walmart, Etsy), so the AliExpress specificity alone differentiates it cleanly.

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 dedicated 'When to use' block gives clear triggering context: you need AliExpress search results with price/discount/rating/sales volume for a ship-to country. It lacks explicit exclusions or named alternatives (e.g. when to prefer a product-detail scraper or a different marketplace scraper), 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?

Beyond the annotations (readOnly, openWorld, non-idempotent, non-destructive), the description discloses that the call starts a run on Apify's hosted MCP gateway using the caller's own APIFY_TOKEN and Apify account, that it is read-only against public data, and that run/dataset IDs are returned for paging. It even flags the docs URL and the account/billing implication, which is the kind of context an agent cannot get from 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?

Labelled sections (When to use / Returns / Behavior) with the intended question front-loaded and zero filler; the docs link is the only non-essential element and it is short. Every sentence carries either selection guidance or behavioral fact.

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 21-parameter, no-output-schema scraping tool, the description supplies what an agent most needs: what the result set is, that rows come back as JSON with run/dataset IDs for paging the full set, that auth/billing ride on the caller's Apify account, and that it is read-only. Remaining specifics (sort, caps, cache age, proxy) are fully documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by naming the three input modes (keywords, category URLs, market phrases) that the 21 parameters split into — something not obvious from a flat parameter list. Filter semantics, caching and truncation are left to the schema text.

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

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

The description states a specific verb and resource — scrape Etsy search results by keyword, category or market page — and enumerates the fields returned (title, price, rating, reviews, badges, ad flag, rank). It doesn't explicitly distinguish itself from the one same-platform sibling (publicrecords--etsy-shop-velocity), so an agent must infer the split from titles alone.

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

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

A dedicated 'When to use' line states the intended question — what ranks on Etsy for a keyword/category/market page and with what position, price, rating and badges. There are no explicit exclusions or named alternatives (e.g. when to prefer the shop-velocity tool instead).

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