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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive), so the description carries the rest and does so richly: User-Agent, 15s timeout, 1.5 MB body cap, max 5 redirects, no JS rendering, SSRF guard refusing private/loopback addresses, and 3 requests per site. Error codes and retryable flags are also disclosed.

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 strictly sectioned (purpose, WHEN TO USE, Fetching, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE), with the core statement front-loaded. Each block is purposeful — the parameter details are needed given the matching subtleties, and the returns list compensates for the absent output schema.

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?

Covers everything an agent needs: what it returns (full object shape), the error taxonomy, cost/model, fetching constraints, and origin-scoping behavior. With no output schema, the explicit RETURNS list and EXAMPLE fill the gap completely.

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%, yet the description still adds real meaning beyond the schema: only the URL origin is used, www vs non-www are distinct origins, and 'bots' replaces rather than extends the default list. It also explains the prefix-match/fallback matching semantics and that status is reported under the exact token passed.

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 precise verb and resource — 'Report whether AI crawlers may access a site, from its robots.txt' — then names the secondary capability (llms.txt / llms-full.txt checks). It distinguishes itself from siblings by explicitly routing to web_seo_audit, web_sitemap_info, and web_batch_audit.

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 explicit WHEN TO USE ('can ChatGPT/Claude/Perplexity crawl this site?', GEO/AI-visibility checks, llms.txt adoption) and WHEN NOT TO USE with named alternatives for each case. Nothing about tool selection 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.

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, but the description goes far beyond them: run-sync execution model, GET-only, no JS rendering, robots.txt compliance, APIFY_TOKEN requirement (with 'never logged'), 2-10s per site parallel timing, full pay-per-event cost breakdown with a worked 50-site example, and enumerated site-level and tool-level error codes. Nothing here contradicts 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?

Labeled sections (WHEN TO USE, BEHAVIOR, COST, RETURNS, WHEN NOT TO USE, PARAMETERS, EXAMPLE) keep a long description scannable and front-loaded with purpose. Slight redundancy remains — the WHEN NOT TO USE line repeats the 1-20 site / free-tools guidance already given — so it is dense but not maximal.

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 paid, external-Actor tool with 6 parameters, the description covers cost, auth, timing, failure modes, output shape, and flag interactions; the output schema covers return structure and the description still sketches the row/error shapes an agent needs to reason about spend and retries. Nothing required for a correct call is missing.

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 description adds real semantics: bare domains default to https, dedupe/billing per unique URL, maxSites as the effective spend cap with free overflow rows, how each check* flag nulls specific field groups and breaks seo_score comparability across settings, and how respectRobotsTxt is independent of checkRobots. This is well beyond what the schema conveys.

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 — bulk audit of websites via a named Apify Actor — and enumerates exactly what is checked (tech, SEO, security headers, robots.txt AI rules, sitemap, llms.txt, scores). It also names the sibling free tools it is distinct from, so an agent can route between bulk and single-site checks without opening a 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 (lists of 20+ sites, parallelism, dataset output) and WHEN NOT TO USE (1-20 sites or interactive questions use the free tools), with the alternative tools named by name. The threshold and the reason for choosing each path are both given.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond that: exactly one of three argument combinations is accepted or INVALID_ARGUMENTS is returned without fetching, live modes fetch like web_seo_audit, the live side uses checkRobots=true, snapshots must be passed unmodified, missing fields compare as null, and the tool is free with no APIFY_TOKEN.

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 with the core diff and the three modes, then cleanly sectioned into WHEN TO USE / RETURNS / WHEN NOT / COST / PARAMETERS / EXAMPLE. It is long, and the EXAMPLE plus the mode list duplicate some of the PARAMETERS bullets, but every section carries usable routing or invocation detail.

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?

No output schema exists, yet the description spells out the full return shape (summary deltas, changes array with change/issue_added/issue_resolved entries, echoed snapshots) and enumerates the error codes. For a zero-required-parameter, multi-mode tool this is complete enough to invoke correctly without guessing.

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, and the description earns extra credit by explaining combination validity, that before/after must be whole unmodified snapshots (with null for missing fields), and the delta direction in url+compareUrl mode (compareUrl minus url). The one gap is that the PARAMETERS prose partly restates the schema rather than adding new distinctions for each field.

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 (diff) over a specific resource (SEO/AI-readiness snapshots) and enumerates the exact fields compared. It also distinguishes itself from web_seo_audit by framing this as comparison rather than single audit work.

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?

Provides explicit WHEN TO USE (track regressions, verify a fix, compare competitors), three concrete modes with which arguments select each, and an explicit WHEN NOT TO USE naming web_seo_audit for single audits. 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.

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

Goes far beyond the readOnly/idempotent annotations: it discloses User-Agent, 15 s timeout, 1.5 MB body cap, 5-redirect limit, no JS rendering, SSRF refusal of private/loopback addresses, parallel fetching, and that per-URL errors do not fail the whole call. That is exactly the operational context an agent needs before invoking.

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-labeled, front-loaded sections make a long description scannable and almost every sentence carries distinct information. There is minor redundancy (the free/local nature is restated as 'no APIFY_TOKEN, no Apify billing', and the SSRF guard is touched twice), which keeps it just short of a 5 for a one-parameter tool.

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?

Covers purpose, routing, fetch constraints, per-URL error taxonomy, cost model, parameter normalization and an example call. With an output schema also present, there is no gap an agent would need filled before calling 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 coverage is 100%, but the description adds real semantics on top: whitespace trimming, implicit https:// with explicit http:// to force plain-HTTP testing, fragment dropping, path/query retention, duplicate handling (fetched twice), and which entries become INVALID_URL / BLOCKED_PRIVATE_ADDRESS rows. These rules are 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?

States a specific verb and resource ('lightweight reachability check for 1-20 URLs') plus the exact outputs (status, redirect chain, response time, content type, Server header, title). It also distinguishes itself from web_seo_audit and web_batch_audit by name, so an agent can route 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?

Gives explicit WHEN TO USE triggers ('is this site up?', 'where does this domain redirect?', pre-filtering leads), a WHEN NOT TO USE section naming the correct siblings (web_seo_audit, web_security_headers, web_batch_audit), and the threshold (>20 URLs) that switches tools. 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.

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

Annotations only declare readOnly/openWorld/idempotent/non-destructive; the description adds substantial context beyond that: User-Agent, 15 s timeout, body cap, max 5 redirects, no JS rendering, SSRF refusal of private/loopback hosts, headers read from the final response, and a full error taxonomy. The only blemish is an internal inconsistency between the '1.5 MB HTML' and '100 KB' body caps.

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 front-loaded and cleanly sectioned (WHEN TO USE, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE), with each block earning its place. Minor redundancy and the conflicting body-cap figures keep it from a 5.

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?

No output schema, but RETURNS fully specifies the returned object shape and the error payloads, and the fetch/SSRF constraints are covered. An agent has everything needed to call and interpret this 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 coverage is 100% so the baseline is 3, but the PARAMETERS section adds real meaning: redirecting hop is not graded, path-level differences matter, bare domains use https, and passing http:// explicitly reveals redirect behavior with a plain-HTTP score cap of 40.

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 ('Check HTTP security response headers of one URL') and enumerates exactly which headers are evaluated. It explicitly differentiates from siblings in WHEN NOT TO USE, routing CVE work to an OSV tool and SEO to web_seo_audit.

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 an explicit WHEN TO USE ('quick security posture / hygiene check') and a WHEN NOT TO USE naming the alternatives and the reason. The agent knows both when to pick this tool and which sibling to pick 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 only declare the generic safety profile (readOnly, idempotent, openWorld, non-destructive); the description adds concrete operational behavior far beyond them: GET with a named User-Agent, 15s timeout, 1.5 MB body cap, max 5 redirects, no JS rendering, SSRF refusal of private/loopback addresses, ~5 outbound requests, and the free/local cost model. It also enumerates the error codes and the isError JSON shape.

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?

Though long, it is tightly sectioned (purpose, issue codes, WHEN TO USE, fetching, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE) and front-loads the core purpose. The 18 issue codes are the only place those outputs are documented since no output schema exists, so every line earns its place.

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 carries the full burden and does so: it names the return object ('seo_audit' snapshot, snapshot_schema fairquery-web-snapshot/1), its fields, both scores and their deduction weights, and the error taxonomy. An agent has everything needed to call it and interpret the result.

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% (baseline 3), but the description materially exceeds the schema: it explains that path/query select the exact page, that on-page fields describe the redirect-resolved final_url while robots/sitemap/llms come from that origin, and that checkRobots=false nulls those fields, suppresses MISSING_ROBOTS_TXT/MISSING_SITEMAP, and makes the snapshot incomparable in web_compare_snapshots.

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 ('Full on-page audit of ONE URL') and enumerates the exact fields audited, then names each sibling it is not ('For just one aspect use web_ai_crawler_access, web_tech_stack...; for many sites use web_batch_audit'). An agent can select it correctly 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 and WHEN NOT TO USE sections name the alternatives (web_quick_check, web_ai_crawler_access, web_tech_stack, web_sitemap_info, web_security_headers, web_batch_audit) and the exact condition that selects each. It also explains the snapshot/web_compare_snapshots use case, 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 read-only/idempotent/open-world, but the description adds substantial context beyond them: User-Agent string, 15 s per-request timeout, 1.5 MB HTML cap, max 5 redirects, no JS rendering, an SSRF guard refusing private/loopback addresses, a 10 MB sitemap cap with meta.truncated signaling, the free/no-billing cost model, and a full error-code list.

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?

Heavily but usefully sectioned (WHEN TO USE, Fetching, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE) and front-loaded with purpose. It is on the verbose side and some RETURN/error detail is arguably redundant given an output schema exists, but nearly every sentence carries operational 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?

For a 7-parameter, non-trivial discovery tool, the definition covers discovery behavior, fetch constraints, pagination, filtering, truncation, error taxonomy, cost, and a worked example. An output schema exists, yet no essential calling information is missing.

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?

Although schema coverage is 100%, the description adds semantics the schema does not carry: url uses only its origin for discovery, the candidate order (robots.txt Sitemap: lines, /sitemap.xml, /sitemap_index.xml, max 4) plus a redirect-origin retry, and that sitemapUrl skips discovery entirely. It also explains that maxChildSitemaps bounds the total count, that contains/sort apply before paging, and that pagination continues via nextOffset.

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 opening sentence states a specific verb and resource chain: 'Find a site's XML sitemap', report index status, list child sitemaps, and page through URLs with lastmod. It also explicitly distinguishes itself from web_seo_audit ('not a crawler and does not audit pages') and web_ai_crawler_access, so an agent can route without opening a 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 ('count/inspect indexed pages, find recently modified URLs, feed URLs into web_seo_audit') and WHEN NOT TO USE sections name the alternative tools for the excluded cases. The condition selecting sitemapUrl vs. auto-discovery is also spelled out, 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 readOnly/openWorld/idempotent/non-destructive, so the bar is lower, but the description still adds rich behavior: FairqueryBot User-Agent, 15s timeout, 1.5 MB HTML cap, max 5 redirects, no JS rendering, SSRF guard on private/loopback addresses, and a full error taxonomy (INVALID_URL, BLOCKED_PRIVATE_ADDRESS, TIMEOUT, etc.). Only the paging/return contract is left to the output schema.

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 with purpose and organized under scannable labels (WHEN TO USE, Fetching, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE), so nearly every line earns its place. Minor redundancy: 'free' appears in the title, COST section, and section header, and the Fetching block is dense.

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?

An output schema exists, yet the definition still covers return shape (paged technology rows with evidence, meta.final_url) and error semantics, and it discloses a meaningful limitation (client-injected tools may be missed because detection is signature-based on one response). Complete for an agent to call it 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 coverage is already 100%, yet the description adds real meaning: url fetches exactly that page after redirects so homepage and subpage may differ, category is a pre-paging case-insensitive substring filter with 'cms' also matching 'Headless CMS', and an unmatched category yields an empty page (count 0) rather than an error. This is substantive semantics beyond the schema.

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 ('detect technologies used by one page from its HTML and HTTP headers') and enumerates concrete output categories (frameworks, CMS, hosting/CDN, analytics) with evidence. It explicitly distinguishes itself from siblings like web_seo_audit and web_security_headers.

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?

Provides explicit WHEN TO USE (lead enrichment, competitor research) and WHEN NOT TO USE (SEO metadata -> web_seo_audit; security headers -> web_security_headers), plus routes bulk work to web_batch_audit. Alternatives and selecting conditions are fully spelled out.

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