Amazon Bestsellers Scraper

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.