run_scraper

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

Adds substantial context the annotations do not carry: every record is billed, the call blocks up to 45 seconds, and on timeout it returns snapshot_id with status 'running'. The async lifecycle and the 'error' field on failed inputs are exactly the behavioral facts an agent needs. readOnlyHint=true is compatible with a billed read-style operation, so no contradiction.

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 sentences, each carrying distinct information (input shape, per-method cardinality/billing, timeout and async handoff, error semantics), with the core action stated first. No filler or restatement of the name.

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

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

With no output schema, the description still explains what comes back (one record per input, error records, snapshot_id/status on timeout) and routes to the correct follow-up tools. For a complex, billed, async four-parameter tool this covers everything an agent needs before invoking it.

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 input array is opaque in the schema (additionalProperties: {} with no description), and the description fills that gap by pointing to sample_input from get_scraper_details and specifying one object per URL or query. It also clarifies limit_per_input's role and its billing implication for discover_by_* methods, going well beyond 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 ('Run a scraper method') and ties it to a dataset via the input shape reference from get_scraper_details. It distinguishes itself reasonably from the progress/results siblings it names, but does not differentiate from near-neighbours like scrape_batch or discover, so an agent still has to infer when this is the right entry point.

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 procedural guidance: input comes from get_scraper_details, then poll get_scraper_progress and call get_scraper_results when ready, plus the collect_by_url vs discover_by_* distinction for output cardinality. What's missing is explicit when-not-to-use guidance against sibling scraping tools such as scrape_batch or scrape_as_markdown.

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