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

Annotations already cover read-only, open-world, non-destructive and non-idempotent, so the description earns credit for what they can't say: the call starts a run of a specific Apify Actor via mcp.apify.com using the caller's own APIFY_TOKEN and account, and returns run/dataset IDs for paging. Cost, concurrency and latency implications of the run are left implicit.

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 sectioned as Purpose / When to use / Returns / Behavior / Docs, so an agent can scan the essentials fast. The opening sentence largely restates the title, which is the only real waste in an otherwise tight block.

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 scraper with no output schema, the definition covers purpose, trigger, return shape (one row per result plus paging IDs), auth/ownership and read-only safety. It stops short of describing row fields or what a partial or failed run looks like, which keeps it just under fully complete.

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

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

Schema description coverage is 100% across all 21 parameters, including enums, defaults and deprecation notes, so the description only needs to reinforce the headline axes (keyword, marketplace, date range). It does that accurately but adds no syntax or edge-case detail beyond what the schema already provides, making 3 the correct baseline.

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

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

Opens with a specific verb and resource ('Get confirmed eBay sold prices') and scopes it to keyword, marketplace and date range. A reader can immediately separate this from the Amazon/TikTok/Etsy siblings because the platform and the sold-price angle are stated 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?

The 'When to use' line gives a concrete trigger: needing what items actually sold for (sold comps) for a keyword, marketplace and date range. It doesn't name an alternative tool or state when not to use it, but no direct eBay competitor exists among the siblings, so the guidance is practically complete.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, so the description earns credit for going beyond them: it discloses that a call starts one Apify Actor run via mcp.apify.com using the caller's own APIFY_TOKEN and account, and that run/dataset IDs are returned for paging. It does not mention credit consumption or expected run duration, which are the remaining operational unknowns for a paid, non-idempotent run.

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 purpose, then 'When to use', 'Returns' and 'Behavior', which is easy to scan. Minor waste: the marketing line about HTML/JSON/CSV/Excel export with 'and more' is vague and slightly conflicts with the 'Returns: structured JSON' statement, since the MCP surface only returns 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?

For a six-parameter, no-output-schema ingestion tool it covers the essentials: inputs to supply, what comes back (dataset rows plus IDs), execution model, and account/token requirements. Missing only cost/credit implications and whether the call blocks until the run finishes, which matter for a non-idempotent run-starter.

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 six parameters (category URL format, depth of crawl, captcha solver caveats, max items) are already documented in the schema; the description adds only the domain-support hint (.com/.co.uk/.de/.fr/.es/.it) and the top-100 ceiling. Baseline 3 applies because the schema does the heavy lifting.

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

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

Names a specific verb and resource ('Scrape the Amazon Best Sellers categories') plus the scope ('top 100 most popular items') and the extracted fields (name, price, URL, thumbnail). An agent can tell it apart from the sibling amazon-reviews-scraper or the eBay/Etsy tools purely from the resource named.

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

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

The 'When to use' line gives a concrete trigger condition ('you need the top 100 Amazon Best Sellers for a category URL') and the supported domains are listed. It stops short of naming when NOT to use it or pointing to the reviews scraper as the alternative for non-bestseller data, so it is clear but not fully 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?

Beyond the supplied annotations, the description discloses that each call starts a run of the 'junglee/amazon-reviews-scraper' Actor through Apify's hosted MCP gateway, requires the caller's own APIFY_TOKEN, and consumes the caller's Apify account — operationally critical context not implied by readOnlyHint/openWorldHint. It also explains the return shape (dataset rows plus run and dataset IDs for paging the full dataset) and the read-only nature of the scrape, with no conflict against destructiveHint=false or idempotentHint=false.

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 labeled 'When to use / Returns / Behavior' structure is front-loaded and easy to scan. There is minor waste: the first sentence restates the title, and the 'download as HTML, JSON, CSV, Excel, XML' export list is irrelevant noise for an MCP call that returns JSON dataset rows.

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 covers purpose, selection criteria, return shape, auth requirement, and account impact — enough to invoke it correctly. What remains thin is how long a run takes or whether the caller must poll using the returned run/dataset IDs, which an agent running this tool would want to know.

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

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

Schema description coverage is 100% and all 11 parameters carry titles, defaults, enums, and explanatory text (maxReviews limits, reviewsCutoffDate formats, keyword duplication behavior). The description adds no parameter-level guidance of its own, so the baseline 3 applies — the schema is doing nearly all the work.

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

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

The description names a specific verb and resource ('extract reviews from Amazon products') and enumerates the extracted fields (rating score, review description, reactions, images). Against the nearest sibling, junglee--amazon-bestsellers, the resource distinction (reviews vs. bestseller rankings) is obvious, so an agent can route correctly 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?

It provides an explicit 'When to use' line scoped to 'customer reviews of specific Amazon products', which is clear positive guidance. It stops short of naming alternatives or exclusions (e.g., when to prefer the bestsellers tool or the product-details option), so it earns a 4 rather than 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?

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.

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 adds genuinely new operational facts: the call starts a run of the Apify Actor publicrecords/etsy-shop-velocity via mcp.apify.com, requires the caller's own APIFY_TOKEN, consumes the caller's Apify account, and is non-mutating on the source site. It also discloses the run/dataset ID paging model and links to docs, so the agent knows the call is an accountable, billed run rather than a plain 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?

The definition is front-loaded with purpose and then cleanly sectioned into When to use, Returns and Behavior, so an agent can scan it. There is mild redundancy: the opening sentence repeats the title verbatim and the phrase "with this Etsy shop scraper" is keyword padding rather than 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 correctly compensates by describing the returned rows and the run/dataset IDs, and it covers the auth and account-cost model that an async Actor wrapper requires. It could go further on how to page the dataset with those IDs and on the fact that an unfiltered call samples an arbitrary set of shops up to maxShops, but nothing essential is missing for a correct invocation.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented with titles, defaults and constraints; baseline is 3. The prose only restates the filter axes (shop name, title keyword, category, change date) already present in the schema, adding no interpretation such as how filters combine or precedence between shops and keywords.

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: tracking/measuring Etsy shop sales counters and the date each counter was read, one row per shop. An agent immediately knows what data comes back. It does not, however, distinguish itself from the sibling publicrecords--etsy-search-scraper, which an agent could plausibly confuse with a sales-counter tool.

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

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

"When to use: Use when you need how many sales an Etsy shop has made, or how fast shops are selling" gives explicit trigger conditions, reinforced by naming the four filter axes (shop name, title keyword, category, change date). It stops short of exclusions or pointing to an alternative tool when the intent is listing search rather than sales measurement.

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 non-destructive, and the description reinforces this while adding genuinely new behavior: it starts a run of the Apify Actor through mcp.apify.com, requires the caller's own APIFY_TOKEN, and bills against the caller's Apify account. It also explains the return contract (dataset rows plus run/dataset IDs for paging). It omits run latency and the asynchronous nature of Actor runs, which matters for a scraper that can take minutes.

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 capability, then a 'When to use / Returns / Behavior' block, which is easy to scan. Some of the framing ('Built for dropshippers, e-commerce sellers, and DTC brands hunting trending products before they go viral') is marketing copy that does not help invocation.

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

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

For a 10-parameter, mode-driven scraper with no output schema, the description covers return shape, execution model, and auth. The main omission is that it never signals expected run duration or polling, and its 'country (US, UK)' claim is incomplete relative to the schema's broader, explicitly unsupported region enum.

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

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

The description advertises filtering by 'category, price range, and country (US, UK)', but the schema has no category or price-range parameters at all, and the region parameter explicitly warns that only US is tested while other markets are unreliable. That directly misleads an agent into setting region=GB, and the parameter details the description does provide are already fully covered by a 100% schema 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 set: extract product data, reviews, seller info, creator affiliates, and GMV/sales estimates from TikTok Shop. The platform is named explicitly, which cleanly separates it from the Amazon, eBay, and Etsy 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?

The 'When to use' line enumerates the supported intents (products, reviews, sellers, creator affiliates, GMV estimates) and the input shapes (category, keyword, shop, product URL). It lacks explicit when-not-to-use guidance and never routes the agent to a named alternative, but the context is clear enough to select this tool.

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