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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: User-Agent string, 15s per-request timeout, 1.5 MB body cap, 5-redirect limit, SSRF guard on private/loopback/link-local addresses, request count per site, and no JS rendering. It also enumerates the error taxonomy with a JSON error 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?

Front-loaded with the core question answered, then organized under clear WHEN TO USE / RETURNS / WHEN NOT TO USE headers, and it ends with a concrete example. There is mild redundancy, e.g. 'Free, no token' restated in the COST line, but it is dense rather than padded.

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 enumerates every field of the returned object, the two llms.txt sub-objects, and the complete error set. Nothing an agent needs to call and interpret the tool 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 100%, so both parameters are already documented, but the description adds the concrete default bot list (GPTBot, ClaudeBot, etc.) and clarifies that only the URL origin is used, which the schema does not state. This goes beyond the baseline 3 without fully defining format nuances.

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 ('Report whether AI crawlers may access a site, from its robots.txt') and immediately defines the output vocabulary (allowed/partial/blocked). It also explicitly names sibling tools for adjacent jobs, so an agent can distinguish it 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?

Gives a dedicated WHEN TO USE ('can ChatGPT/Claude/Perplexity crawl this site?', GEO checks, llms.txt adoption) and WHEN NOT TO USE that routes to three specific siblings (web_seo_audit, web_sitemap_info, web_batch_audit). Both inclusion and exclusion conditions are explicit.

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 well beyond the annotations by disclosing cost model ($0.002/site, error rows free), auth requirement (APIFY_TOKEN, never logged), rate/politeness behavior, no-JS rendering, robots.txt respect, and per-site latency, all of which an agent needs before invoking a paid bulk 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?

Labeled sections (WHEN TO USE, BEHAVIOR, COST, RETURNS, WHEN NOT TO USE, EXAMPLE) front-load the routing decision, and every line carries actionable information despite the length.

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 routing, cost, auth, error taxonomy (INPUT_EMPTY through BLOCKED_OR_RATE_LIMITED plus APIFY_TOKEN_MISSING), and even the return shape, leaving nothing an agent needs to call 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 description adds the concrete example invocation (urls + checkLlmsTxt) and ties parameters to outcomes like MAX_SITES_EXCEEDED error rows, giving marginal value above 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 (bulk audit) and resource (websites) with explicit scope ('up to thousands in one call') and names the underlying Actor, making it unmistakable what it does versus the single-site 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?

Explicit WHEN TO USE (20+ sites, lead enrichment, portfolio scans) and WHEN NOT TO USE (1-20 sites or interactive questions) naming six alternative free tools by name, plus the snapshot-diff sibling for follow-up.

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, but the description adds far more: fetch semantics (read-only GETs, User-Agent, 15s timeout, 1.5MB cap, 5 redirects), SSRF guard, no JS rendering, and a full error-code list. This is rich behavioral disclosure well beyond the 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?

Dense but well-organized with front-loaded mode list and labeled sections (WHEN TO USE, RETURNS, WHEN NOT TO USE, COST, EXAMPLE). Slightly long, but every section carries distinct 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?

No output schema exists, so the description carries the return-shape burden and does so thoroughly with the summary/changes/before/after structure and error codes. For a 4-param, mode-driven comparison tool, an agent has everything needed to invoke 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 100%, so the baseline is 3, but the description adds value beyond the schema by explaining how the four params combine into three modes (before+after, before+url, url+compareUrl). It clarifies the interaction of params that the schema documents only individually.

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) and resource (SEO/AI-readiness snapshots) plus the enumerated dimensions compared (score deltas, issues, title, meta, JSON-LD, etc.). The three numbered modes make it trivially distinguishable from siblings like 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?

Explicit WHEN TO USE (track regressions, verify a fix, compare competitors) and WHEN NOT TO USE with a named alternative (web_seo_audit for a single audit). Nothing is left to inference about selection.

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, no destruction), but the description adds substantial operational detail annotations cannot: User-Agent string, 15s timeout, 1.5MB body cap, 300KB read limit, max 5 redirects, SSRF guard refusing private/loopback addresses, parallel execution, and free/no-token/no-JS. This is exactly what behavioral disclosure should add beyond structured hints.

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, then cleanly sectioned into WHEN TO USE / Fetching / RETURNS / WHEN NOT TO USE / COST. Every block earns its place, though the RETURNS field-by-field enumeration is slightly redundant given the output schema exists.

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?

Given an output schema exists, the description needn't explain return values, yet it does so concisely while also covering the SSRF constraint, per-URL error isolation ('never fail the whole call'), and cost model. Nothing an agent needs to call it correctly 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 100% and the single `urls` param is well-documented in the schema itself. The description restates the 1-20 range and bare-domain-uses-https rule, but adds no syntax beyond what the schema already says. Baseline 3 when 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?

States a specific verb+resource ('Lightweight reachability check for 1-20 URLs') and enumerates the exact returned fields, distinguishing it from SEO/security siblings by function. An agent can tell it apart from web_seo_audit and web_security_headers 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 with example queries ('is this site up?'), named alternatives (web_seo_audit for SEO details, web_batch_audit for >20 URLs), and a WHEN NOT TO USE section listing three siblings and their scopes. Fully routes the agent.

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 well beyond the readOnly/openWorld/idempotent annotations by disclosing the User-Agent, 15 s per-request timeout, 1.5 MB body cap, 5-redirect limit, single-request semantics, and an SSRF guard refusing private/loopback/link-local addresses. This is exactly the kind of operational context annotations cannot carry.

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, then cleanly sectioned (WHEN TO USE / Fetching / RETURNS / WHEN NOT TO USE / COST / EXAMPLE). Some redundancy: COST restates 'free' already implied earlier, and 'not a vulnerability scanner' appears twice, so it is slightly longer than strictly necessary.

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 fully specifies the return shape ('security_headers' object with headers, missing, info_disclosure_headers, score, grade, checked_at) and enumerates every error code (INVALID_URL, BLOCKED_PRIVATE_ADDRESS, DNS_FAILED, etc.). Nothing an agent needs to call or interpret results 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 description coverage is 100% and the single 'url' parameter is already documented in the schema (examples, bare-domain-over-https, private-host refusal). The description's EXAMPLE adds marginal framing but no new parameter meaning, so the baseline 3 applies.

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 and the scoring model (0-100, grade A-F). It is immediately distinguishable from siblings like web_seo_audit and any OSV/dependency 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?

Gives an explicit WHEN TO USE ('quick security posture / hygiene check'), an explicit WHEN NOT TO USE ('not a vulnerability/penetration scan'), and names concrete alternatives (OSV tools for CVEs, web_seo_audit for SEO). Routing is unambiguous.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds substantial context beyond them: fetching behavior, User-Agent, 15s timeout, body cap, redirect limit, SSRF guard, no JavaScript rendering, number of requests, and full error codes. This is unusually thorough behavioral disclosure for a read-only audit tool.

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 description is front-loaded with purpose, issue codes, usage, fetching, returns, and costs, and the structure makes it easy to scan. However, some content is repeated: 'free' is stated in the title, the fetching section, and the COST section, and the EXAMPLE duplicates the URL format already in the schema, so it falls short of perfect conciseness.

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?

Given the tool's complexity, lack of output schema, and many output fields, the description is complete: it enumerates returned fields, snapshot schema, error shapes, and operational constraints. Together with annotations and the fully described input schema, an agent has everything needed to invoke and interpret the tool.

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 both parameters are already documented in the input schema. The description adds only a minor detail about request count when checkRobots=false; otherwise it does not extend parameter meaning beyond the schema, matching the baseline of 3 for fully covered schemas.

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: a full on-page audit of ONE URL, enumerating the exact fields and scores produced. It clearly distinguishes itself from sibling tools by naming the narrower alternatives and the batch alternative.

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 and WHEN NOT TO USE sections, naming each sibling (web_ai_crawler_access, web_tech_stack, web_sitemap_info, web_security_headers, web_quick_check, web_batch_audit) and the condition that selects it. It also explains the snapshot-then-compare workflow with web_compare_snapshots.

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, and the description exceeds them with concrete operational detail: User-Agent string, 15s timeout, 1.5MB body cap, max 5 redirects, SSRF guard refusing private/loopback addresses, 10MB per-sitemap cap with meta.truncated flag, 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?

Front-loads purpose then groups content under WHEN TO USE / RETURNS / WHEN NOT TO USE / COST / EXAMPLE, so navigation is easy. It is somewhat long, and the RETURNS block partially duplicates the existing output schema, but nearly every sentence 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?

Covers discovery order, index handling, paging semantics, limits, SSRF/timeout behavior, error conditions, cost/auth, and a concrete example. With an output schema present it did not need to restate return shape, yet nothing an agent needs to invoke it correctly 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: explains that for an index only the first maxChildSitemaps children are expanded, that contains/sort drive filtering, and shows a worked example combining url, contains, sort, and limit.

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 specific verbs and resource: find a site's XML sitemap, report whether it is an index, list child sitemaps, page through URLs with lastmod. It explicitly differentiates from siblings by declaring 'Not a crawler' and routing to web_seo_audit and web_ai_crawler_access.

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 (count/inspect indexed pages, find recently modified URLs, feed into web_seo_audit) and WHEN NOT TO USE (not a crawler, not an auditor; use web_seo_audit for pages, web_ai_crawler_access for robots.txt AI rules). Alternatives and conditions are named outright.

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, and the description still adds substantial behavioral context: signature-based detection with no JS execution (so client-injected tools may be missed), identifying User-Agent, 15 s timeout, 1.5 MB body cap, max 5 redirects, SSRF refusal of private/loopback addresses, and free/no-token cost. This is well beyond what the annotations convey.

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 sectioned (WHEN TO USE / Fetching / RETURNS / WHEN NOT TO USE / COST / EXAMPLE), so an agent can skim to the needed part. Every block carries operational information with no filler.

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 summarizes the return shape and error taxonomy (INVALID_URL, BLOCKED_PRIVATE_ADDRESS, DNS_FAILED, FETCH_FAILED, TIMEOUT, TOO_MANY_REDIRECTS) with the isError/retryable contract. For a single-request fetch tool with SSRF guard and pagination, nothing an agent needs 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 description coverage is 100%, so the baseline is 3, but the description adds value: it explains the category filter's role, documents the pagination contract via nextOffset, and provides a worked EXAMPLE showing url+category producing a filtered item. It does not, however, add syntax beyond what the schema states for url/limit/offset.

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+resource ("Detect technologies used by one page from its HTML and HTTP headers") and enumerates the detectable categories (frameworks, CMS, hosting/CDN, analytics), making the scope concrete. It also names the sibling tools it is NOT (web_seo_audit, web_security_headers, web_batch_audit), so an agent can disambiguate without opening schemas.

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 with concrete scenarios (lead enrichment, competitor research) plus routing to web_batch_audit for many sites, and a WHEN NOT TO USE section routing to web_seo_audit and web_security_headers. Both inclusion and exclusion conditions are stated.

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