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

Annotations already declare readOnlyHint/idempotent/openWorld, and the description goes well beyond them: robots.txt respected, per-site politeness delay, 2-10s per domain, a 280s wait cap with the waitForFinish=false escape hatch and get_enrichment_results polling path, plus an explicit price model ($0.003 per enriched domain, free for unreachable/blocked/invalid domains, ~1000-domain cap with free MAX_DOMAINS_EXCEEDED rows). That cost and long-running-operation disclosure is exactly the kind of context an agent cannot get from structured fields.

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 WHAT/WHEN/COST/RETURNS/PARAMETERS/EXAMPLE structure is strongly front-loaded with the decision-relevant content first, and the example anchors the call shape. It is long, and the PARAMETERS block restates several descriptions already present in the schema verbatim, which is the only real redundancy.

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 7-parameter, paid, long-running open-world crawl, this covers everything an agent needs: cost exposure, runtime expectations, async polling behavior, null-vs-error row semantics, and the free preview path via normalize_domains. The presence of an output schema is complemented rather than duplicated.

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 would be 3, but the description adds real semantics: hostname reduction rules (leading www removed, subdomains kept as separate billable domains, email local part discarded), dedup/billing consequences, the unparseable-entry INVALID_DOMAIN behavior, the undocumented 1000-domain run cap, and tuning heuristics ('1 = homepage only, 3-5 usually finds the contact/imprint page'). It also clarifies cross-parameter dependencies (checkSpfDmarc inert when validateEmails=false) and the lawful-basis guidance for emailScope.

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 WHAT block gives a specific verb (crawl homepage + contact/about/imprint pages) and resource (company domains), then enumerates the exact output fields returned. An agent knows precisely what this tool produces and can distinguish it from get_enrichment_results and normalize_domains 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 has explicit WHEN TO USE (lead/CRM lists, finding official contact email or address) and WHEN NOT TO USE (call normalize_domains to clean/preview first; not for personal emails, LinkedIn people search, or JS-only sites). The named alternative and the condition that selects it are both stated, leaving nothing 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/idempotentHint/non-destructive, and the description adds substantial context beyond them: GET-only calls, never starts/aborts/re-bills, sub-second typical latency, poll cadence of 10-30 s, processing throughput (5 domains at a time, ~2-10 s each), token/auth requirements, cost model, and the full error-code list including which failures are retryable.

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?

Long but fully front-loaded and labeled (WHAT/WHEN/BEHAVIOR/COST/RETURNS/PARAMETERS/EXAMPLE). Every section carries distinct information for a polling tool, and the one-line JSON example compactly conveys the response shape.

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?

Despite an output schema existing, the description still covers status/finished semantics, that FAILED or TIMED-OUT runs return partial rows, and the error taxonomy. Combined with annotations, schema, and output schema, an agent has everything needed to call and interpret this tool 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 baseline is 3, but the description adds real meaning: runId comes from enrich_domains run.run_id (or the console URL), offset/limit page rows in write order, and the caller should loop with nextOffset until it is null while finished is true. That paging contract is not derivable from the schema alone.

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?

Starts with a precise verb+resource+scope: 'Read the status and result rows of an enrich_domains run started with waitForFinish=false, one page at a time.' It explicitly distinguishes itself from siblings enrich_domains (starting a run) and normalize_domains (cost preview), so an agent can route without opening another 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?

Has dedicated WHEN TO USE and WHEN NOT TO USE sections: use after enrich_domains returns run.run_id to poll until finished and page rows; do not use to start an enrichment or preview cost, and cannot read runs of other Actors. Both the trigger condition and the exclusions are stated explicitly.

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/idempotent/non-destructive/closed-world, but the description adds substantial context beyond them: free/local, no network, no APIFY_TOKEN, no DNS lookup, and the billing-preview semantics (billable_count, estimated_max_cost_usd formula, invalid entries only producing free error rows). Rich disclosure that goes well past 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?

Well-organized with labeled WHAT/WHEN/COST/RETURNS/PARAMETERS/EXAMPLE sections and the core purpose front-loaded. Slightly verbose: the RETURNS and cost-formula details partly restate the output schema, and the PARAMETERS block is long, but almost every line carries actionable 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?

Complete for a complex normalization tool: inputs, normalization rules, validity criteria, ordering, billing preview, an end-to-end EXAMPLE with concrete outputs, and cost model are all covered. An agent has everything needed to call it correctly and reason about downstream 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 already 100%, yet the PARAMETERS section adds real meaning beyond it: newline/comma/semicolon list handling, trimming, lowercasing, hostname reduction, www/scheme/path/port stripping, email @-splitting, subdomain retention, the dot+2-letter-TLD validity rule, punycode acceptance, first-seen ordering, and empty-array acceptance. This far exceeds the schema's single-sentence item description.

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+resource ('Turn URLs, email addresses and messy strings into bare registrable hostnames') and immediately distinguishes scope from the sibling enrich_domains. An agent can tell exactly what this does and how it differs from enrichment 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?

Explicit WHEN TO USE ('before enrich_domains, to clean an input list') and WHEN NOT TO USE ('to get contacts, company names or check that a site is reachable - use enrich_domains'), naming the alternative directly. Nothing 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.