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

Annotations only cover read-only/open-world semantics, while the description adds the operationally decisive facts: per-page pricing at $0.004, spending caps via run_max_charge_usd, unbilled crawler-blocked pages, typical 5-15s runtime with a 300s ceiling, and the runtime backend. That is substantial context an agent cannot get from the annotations or 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-loads purpose, then differentiation, then parameters, then return shape — a sensible order, and nearly every sentence carries information. It is on the long side, and the parameter section partially restates schema text rather than only adding the multiplier/cap interactions.

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 enumerates every returned field plus the JSON envelope, and it covers cost, timeouts, and billing edge cases. An agent has everything needed to invoke it and interpret the result without further probing.

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 genuinely new semantics: crawlInternalLinks multiplies billed pages, run_max_items fills maxPages when unset, and raising maxPages can bill more than is returned. These interaction effects are not derivable from the individual schema descriptions.

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 ('Audit web pages for classic SEO and for AI-search readiness') and enumerates the concrete checks (titles, meta, schema/FAQ markup, llms.txt, crawler blocking) so the agent knows exactly what the output grades. It also explicitly distinguishes itself from both siblings by naming what each of them does instead.

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 positive trigger ('Use when you need an on-page SEO/GEO audit or an llms.txt draft') and explicit exclusions with named alternatives for change tracking and security scanning. Nothing about routing 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 read-only/open-world, but the description adds pricing ($0.002 per domain), the spending cap, timeout behavior and remediation advice (raise run_timeout_secs to 300, or shrink input). It also discloses the non-obvious billing quirk that run_max_items fills maxDomains and therefore limits what is charged, and warns that a missing DKIM result may be a false negative.

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 differentiation before the mechanics, and the return-field list is a compact enumeration rather than prose. It is dense — the behavior paragraph packs pricing, billing interaction, timeouts and output shape into one block — but nearly every sentence carries information an agent needs to call it correctly.

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 compensates by listing the per-item return fields (grade, score, spoofable, spfRecord, dmarcPolicy, fixes, status) and the response envelope {actor, count, items}. Cost, timeout, failure handling for unresolvable domains and the no-charge-for-empty-runs rule are all covered, leaving nothing material an agent would need to guess.

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%, so most parameter meaning is supplied structurally, but the description still adds value: it ties dkimSelectors to the false-negative risk, explains that domains are normalized and de-duplicated across bare domains/emails/URLs, and spells out the cross-parameter interaction between maxDomains and run_max_items that the schema alone does not convey. The remaining parameters are restated rather than deepened.

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 (audit email authentication for a list of domains) and enumerates exactly what is checked: SPF, DKIM, DMARC, MX provider, MTA-STS, TLS-RPT and BIMI, graded A-F. It then explicitly separates itself from company_website_enricher, ai_search_seo_audit and hidden_ai_instructions_scanner, so an agent can pick it out of the sibling set 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 concrete triggers (deliverability or spoofing checks, a security prospect list, a vendor review) and explicit exclusions that route to named alternatives: SEO/AI-readiness goes to ai_search_seo_audit, page-level prompt injection goes to hidden_ai_instructions_scanner. Both when-to-use and when-not-to-use are covered.

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/non-destructive, and the description goes well beyond them: it names the backing Actor, states pricing (free, no per-result charge, uncapped-find runs not billed), the per-call spend cap, runtime expectations (5-15s typical, minutes for crawls), timeout remediation, and the important epistemic caveat that 'findings are leads for review, not proof of intent.' It also discloses the trimming behavior of long output.

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?

Purpose, differentiation, and exclusions are front-loaded in the first two sentences, and the parameter and pricing notes follow logically. It is dense and long for a single paragraph, with several clause-heavy sentences, but essentially every sentence carries operational information rather than 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?

For an 11-parameter tool with no output schema, the description covers the missing return shape explicitly (page-summary items and finding items with technique, location, excerpt, category, severity). Combined with runtime, cost, and timeout guidance, an agent has everything needed to call it correctly and interpret results.

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 genuine cross-parameter meaning: renderJs=true is 'much slower, plus settleSecs per page,' agentUaDiff 'adds three fetches per page,' crawlDepth is capped by maxPages, and run_max_items 'fills maxPages when you leave it unset, so it also limits what is billed.' That billing/limit interaction 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?

States a specific verb and resource ('Scan web pages for text hidden from people but read by AI agents') and immediately enumerates the detection techniques. It explicitly distinguishes itself from both named siblings (ai_search_seo_audit for visible SEO, website_change_monitor for diffs), so an agent can disambiguate 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 ('when an agent or workflow will ingest a page and you need to know whether it carries hidden instructions, or when auditing your own site') and explicit when-not-to-use with the alternative named for each ('Do not use for SEO grading... or for email security'). This is the full when/when-not/alternatives pattern.

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/non-idempotent, but the description adds substantial context beyond them: the first-run-only-saves-baselines state machine, that the webhook posts outside the Apify run and only when something changed, that unreachable pages are free while unchanged pages are still billed at $0.0015/page, the run_max_charge_usd cap, and the 5-15 s / 300 s timeout envelope. It even reconciles with annotations by asserting 'read-only' while disclosing the persistent key-value snapshot store.

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 critical framing (what it is, what it is not, when to use) is front-loaded in the first three sentences, and the return-field list and billing paragraphs are placed after the decision-relevant content. It is long and some parameter prose duplicates the schema verbatim, but for a 13-parameter stateful tool with non-obvious cost semantics the density is largely earned.

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 having no output schema, the description enumerates the returned fields (agentSummary, status, addedLines, priceChanges, keywordsAppeared, titleBefore/After, previousCheckAt) and the envelope shape {actor, count, items}. It also covers cost model, spend cap, timeout remediation, and webhook side effects, leaving no material gap for calling the 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%, so the schema baseline is 3; the description goes further by explaining cross-parameter interactions the schema only states locally, notably that the first run per monitorName only saves a baseline and must be reused for later runs, and that run_max_items fills maxPages when left unset and therefore also bounds billing. It restates some parameters (webhookUrl, onlyReportChanges, ignorePatterns) that the schema already documents well, so it stops short of a 5.

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 ('Check a watch list of web pages against snapshots saved by your previous run') and enumerates the concrete outputs: added/removed text, change percent, price changes, keyword alerts. It explicitly names the two sibling tools it is not (ai_search_seo_audit, hidden_ai_instructions_scanner) and characterizes itself as 'stateful diffing over time', so an agent can discriminate 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 ('track competitor pricing, terms, product or careers pages on a schedule') and explicit when-not ('Do not use for a one-off page read or audit (use ai_search_seo_audit), or for pages behind a login'), naming the alternative to select instead. Exclusions cover both the wrong task shape and an unsupported page class.

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