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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: it is a pure local function with no network and no token, it is free, and the verdict can never be 'valid' because DNS is not checked. That is useful behavioral disclosure, though it partly overlaps openWorldHint.

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/WHEN NOT/COST/RETURNS/EXAMPLE labeling is well front-loaded and skimmable. However, the RETURNS block enumerates the full response field list even though an output schema exists, which is mild redundancy against the conciseness goal.

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 read-only local batch checker with an output schema present, everything an agent needs is supplied: scope, exclusions, cost, and verdict semantics. Nothing required 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 limit/offset/emails are already documented including accepted forms and paging. The description's EXAMPLE restates the input shape without adding format or semantic detail beyond the schema; 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?

The WHAT line names a specific verb set and resource (offline email checks: syntax, typo, disposable, role, free provider) and explicitly frames scope as local/offline. It contrasts itself cleanly against the sibling email_validate_deliverability, so an agent can distinguish the two without opening either 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 (fast pre-filtering of signups or lead lists, before paying for validation), WHEN NOT (no DNS/MX, verdicts never 'valid'), and a named alternative (email_validate_deliverability). Routing is fully determined.

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 supply the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds substantial context beyond them: exact pricing ($0.002/email), token-based billing to the caller's Apify account, enumerated error codes, and the negative scope (no SMTP probing). These are genuinely valuable operational disclosures, though the return-field list partly duplicates 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 labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE) make it scannable and each block carries non-redundant information. It is dense and the RETURNS enumeration slightly overlaps the existing output schema, keeping it just short of 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?

For a paid, networked, multi-check tool this covers everything an agent needs: cost model, auth requirements, error taxonomy, usage routing, and a worked example. With an output schema present, the return enumeration is a bonus rather than a required burden, and nothing essential 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 every parameter is already fully documented including defaults, ranges, and the nextOffset paging hint. The description's example reinforces the emails shape but adds nothing to individual parameter semantics beyond the schema, making the baseline 3 correct.

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 line states a specific verb+resource (email deliverability validation) and enumerates the exact checks performed (syntax, MX, disposable, SPF/DMARC, etc.), plus the final verdict vocabulary. It is clearly distinguishable from siblings like email_check_syntax, which it names explicitly.

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?

WHEN, WHEN NOT, and an explicit alternative with a cost predicate are all given: 'Pre-filter with free email_check_syntax to avoid paying for obviously bad rows' and 'It does not SMTP-probe mailboxes.' The agent knows exactly when to pick this tool versus the free sibling.

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 only the safety profile (readOnly, idempotent, openWorld, non-destructive); the description goes well beyond by disclosing the billing model ($0.0009/package + $0.0028/vulnerability + per-run fee, with a worked lodash+django example), the required APIFY_TOKEN and account-charging behavior, the paged row types, and the full enumerated error taxonomy. That is exactly the additional context an agent needs before committing to a paid call.

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 label-prefixed structure (WHAT / WHEN / WHEN NOT / COST / RETURNS / EXAMPLE) front-loads the identifying information and makes the routing and cost facts scannable. Despite its length, every section is functional — there is no filler or restatement of the tool 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?

For a 7-parameter, paid, open-world tool with 0 required parameters, the description covers inputs, cost, auth prerequisites, output row types, paging, and failure modes. Because an output schema exists it is not obligated to describe returns, yet the summary of row types still aids invocation.

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 decision value: it tells the agent to set minSeverity="HIGH" specifically to cut vulnerability rows and therefore cost, and the EXAMPLE shows manifestText combined with minSeverity in practice. It does not, however, clarify manifestText-vs-packages precedence or the dev-dependency default beyond what the schema already states.

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 names a specific verb (runs an audit), the exact resource (OSV database against a pasted manifest or package list), and the concrete output shape (per-package severity/CVSS, fixed versions, one row per vuln). It explicitly differentiates itself from the two sibling tools osv_query_packages and osv_get_vulnerability, 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?

It gives explicit WHEN (full project audits from a pasted manifest, CI-style reports, severity-filtered output) and WHEN NOT (quick checks of a few exact versions via osv_query_packages, or a single advisory via osv_get_vulnerability), naming both alternatives by name. The condition that selects each path is fully 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?

Beyond the annotations (readOnly/idempotent/openWorld), the description discloses cost (free, no token), the endpoint (api.osv.dev over HTTPS), a rate/shape limit (max 25 IDs, 20s timeout each), and the structured error codes with retryable flag. This is meaningful operational context that annotations alone do not 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?

Labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE) make it scannable and front-loaded, with the scope and alternative-routing stated before operational detail. Every sentence 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?

With an output schema present and 100% param coverage, the description fills the remaining gaps: cost, transport, limits, error codes, and a concrete worked example. An agent has everything needed 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 description coverage is 100%, so the schema already fully documents ids/limit/offset. The description only restates the 25-ID cap, which duplicates maxItems, and gives no added semantics for paging or ID formatting. Baseline 3 is appropriate.

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 clause gives a specific verb (Fetch) and resource (full OSV records for advisory IDs), enumerating exactly which fields are returned. It distinguishes itself from siblings osv_query_packages and osv_audit_dependencies by scope (lookup by ID vs. discovery by package/manifest).

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 ('You have IDs ... and need details or the fixed version') and WHEN NOT clauses name the two alternatives with their cost tiers, so the agent can route without opening other schemas. 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 well past the annotations (readOnly, idempotent, openWorld, non-destructive) by disclosing cost (free), network path (direct HTTPS to api.osv.dev, no token, nothing sent to Fairquery/Apify), a 20s timeout, and retryable error code OSV_FETCH_FAILED. That operational detail is exactly the kind of context annotations cannot express.

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/WHEN NOT/COST/RETURNS/EXAMPLE labeling is highly scannable and front-loads the purpose. The RETURNS block partially duplicates the existing output schema, which is mild redundancy, but every other 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 a rich output schema and strong annotations, the description supplies everything else an agent needs — cost, privacy posture, timeout, error semantics, and routing to alternatives. Nothing required 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 description coverage is 100%, so all three parameters are already documented in the schema, including the ecosystems list, the exact-version constraint, and the paging fields. The description's EXAMPLE merely repeats the schema's own example, adding no new parameter syntax or format detail. Baseline 3 applies 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 and resource (query the OSV.dev database for exact package versions) and names the two siblings it is not — osv_get_vulnerability for details and osv_audit_dependencies for manifest-level auditing. An agent can distinguish it from its siblings 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 (quick 'is lodash 4.17.20 vulnerable?' checks for up to 200 packages) and WHEN NOT (manifest/lockfile parsing, severity filtering, fixed versions -> use the paid sibling), with each alternative named. 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them with billing mechanics ($0.003/doc + $0.0005/finding charged to the caller's Apify account), file size/type constraints, and a concrete error-code taxonomy. This is exactly the extra context the 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?

Labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE) front-load the decisive routing information, and each block carries distinct, non-redundant content. Dense but 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 an output schema present, the description need not explain return values, yet it still sketches paged row shape and error types. Combined with cost, limits, and mode guidance, nothing needed to call this 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%, so all 13 parameters are already documented in the schema, including the mode enum and restore semantics via placeholderMap. The description adds only a single example invocation, which is marginally useful but does not extend parameter meaning 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?

The WHAT line names a specific verb+resource and enumerates the superset of capabilities (NER names/locations, street addresses, URL/PDF scanning, restore mode) relative to the sibling pii_scan_text. An agent can distinguish this from pii_scan_text/pii_redact_text 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 and WHEN NOT sections, naming the free alternatives (pii_scan_text / pii_redact_text) for plain-text regex-detectable PII, and ruling out images (no OCR) and email deliverability. This is the full when/when-not/alternative triad.

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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real value beyond them by disclosing that this is static local data with no network and no token/cost, plus that paid coverage is gated behind the Actor — context annotations do not 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?

The labeled WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE structure is front-loaded and scannable, with each section carrying distinct information. Slightly verbose in aggregate, but no section is 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?

With an output schema present, return-value detail is not strictly required, yet the RETURNS line and EXAMPLE still orient the agent. Cost, coverage tiers, and routing to alternatives are all covered, so nothing an agent needs to call this 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?

The tool takes zero parameters, so the baseline is 4; there is no input schema semantics for the description to add. It does clarify what entityTypes the output enumerates, which is useful framing though not strictly a parameter concern.

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 section names a specific resource (catalog of PII/secret entity types) and precisely scopes it: which run locally vs only in the paid Actor, redaction styles, and pricing. An agent can immediately distinguish this from pii_scan_text and pii_redact_text 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 (before scanning/redacting to pick entityTypes, or to explain coverage and costs) and WHEN NOT (not to scan or redact), naming the exact sibling tools to use instead. 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?

Beyond the read-only/idempotent/non-destructive annotations, it discloses local-only execution, no network/token usage, placeholder consistency across documents in one call, the sensitive nature of placeholder_map, possible entropy-scan false positives, and the INPUT_TOO_LARGE error. The random per-call salt for hash mode is also noted, which is important behavioral context.

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 structured WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE format is front-loaded and easy to scan. Despite covering many details, every section provides actionable information for invoking the tool 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?

For a 9-parameter tool with an output schema and rich annotations, the description covers purpose, alternatives, cost, return shape, errors, and an example. It gives an agent everything needed to select and invoke 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 baseline is 3, but the description adds practical meaning: placeholder consistency within a call, the security caveat to omit placeholder_map unless needed, and paging behavior of one item per document. It does not add much beyond the schema for every parameter, so it is not a full 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?

The description states a specific verb and resource: redact PII/secrets from texts, returning sanitized copies. It explicitly distinguishes itself from siblings by naming pii_scan_text for findings-only and pii_guard_documents for NER/URL/PDF cases.

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 explicit when-to-use guidance ('right before sending user data to an LLM/third party') and when-not guidance with named alternative tools. It also clarifies the returnPlaceholderMap workflow and cost/local constraints.

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/openWorld=false, but the description adds substantial context beyond them: 100% local execution, no network or APIFY_TOKEN, raw values never returned, findings paged across documents, and the INPUT_TOO_LARGE error. This is materially richer than the annotation set.

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/WHEN NOT/COST/RETURNS/EXAMPLE labeling makes it well front-loaded and skimmable. It is somewhat long, and the RETURNS block partially restates the existing output schema, which is a minor redundancy rather than a clarity problem.

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 idempotent local read tool with an output schema, no annotations gaps, and complete parameter docs, this definition covers purpose, alternatives, cost/privacy posture, paging, and error handling. An agent has everything needed 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 description coverage is 100%, so the schema already documents all seven parameters and the baseline would be 3. The description adds an end-to-end input/output example and cross-references pii_list_detectors for valid entityTypes names, giving modest extra value 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?

Names a precise verb (detect/scan) and resource (text) and enumerates the concrete detector families (emails, SSNs, Luhn cards, AWS/GitHub/etc. keys, JWTs), so the agent knows exactly what is covered. It explicitly differentiates from siblings by naming pii_redact_text for sanitization and pii_guard_documents for NER/PDFs.

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?

A dedicated WHEN clause covers the intended scenarios (pre-LLM/third-party sending, credential auditing) and a WHEN NOT clause routes the agent to specific alternatives (pii_redact_text, pii_guard_documents) with the condition that selects them. No inference required.

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 behavior. The description adds value beyond them: it is a static local dataset with no network and no token, and it explicitly does not download lists or report freshness — a meaningful limitation an agent must know.

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-structured with labeled WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE blocks and strong front-loading. However, the RETURNS block and the JSON example partially restate the already-provided output schema, so a small amount of content does not earn 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?

For a zero-parameter, read-only listing tool with an output schema available, the description covers purpose, usage routing, cost, and behavioral limits completely. No gap remains that would cause an agent to call it incorrectly.

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 tool takes zero parameters, so the baseline is 4. The description's only parameter reference is to a sibling's 'lists' parameter, which adds context but no schema meaning for this tool itself.

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 resource (static list of official sanctions lists sanctioned by sanctions_screen_names) and the exact fields returned (id, name, authority, download URL). Explicitly distinguishes itself from the sibling paid screening tool, so an agent can select it without opening either 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?

Provides explicit WHEN (choose the lists parameter, cite sources, explain coverage before paying) and WHEN NOT (screening a name, which is sanctions_screen_names, paid). Names the alternative and the condition selecting it, including cost implications.

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, open-world), and the description adds substantial context beyond them: per-name billing to the caller's own Apify account ($0.005/name), run duration (~10-40 s, lists downloaded fresh per run), a concrete error-code list, and a false-positive/miss disclaimer with a manual-review requirement. This is exactly the extra behavioral 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?

The WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE labeling makes it skimmable and front-loads the decision-critical parts. It is longer than strictly necessary — the certification caveat appears twice (in WHEN NOT and again at the end) — but nearly every line carries information an agent needs.

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, open-world screening tool with an output schema, the definition covers purpose, cost, timing, paging, error taxonomy, and limitations. Nothing an agent needs to call it correctly or interpret a result is missing, and the return-shape detail is a bonus rather than a gap-filler.

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: the guidance to batch all names into one call because lists download once per run, the note that country/DOB are optional filters, and a worked example pairing queries with minScore=90 to steer threshold choice.

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 (fuzzy-match names against OFAC SDN, OFAC Consolidated, EU, UK and UN watchlists) and names the underlying actor. It also explicitly distinguishes itself from the sibling sanctions_list_sources, so an agent can separate the two without opening either 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?

The WHEN block names concrete scenarios (KYC/KYB onboarding, vendor checks, bulk re-screening) and the WHEN NOT block excludes PEP/adverse media and certified compliance decisions, redirecting to sanctions_list_sources for coverage info. Explicit when, when-not, and alternative — 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 already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description goes further than most: explicit per-lead pricing tied to the caller's APIFY_TOKEN, run count, latency expectation (~15-45 s for sanctions download), partial-failure semantics ('unavailable' plus meta.errors), and concrete tool error codes. That is real added context, though the readOnly/idempotent traits themselves are left to annotations rather than explained.

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 (WHAT/WHEN/WHEN NOT/COST/RETURNS/EXAMPLE) front-load the decision-relevant facts and make the long text scannable. Every block carries information an agent needs — cost and latency in particular are non-redundant with any structured field.

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, multi-second, network-dependent orchestrator with paged output, the description covers cost model, billing identity, timing, pagination, partial-failure handling, and error codes, while the output schema carries the return shape. Nothing an agent needs to decide or invoke 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 schema already documents every parameter including limit/offset/minScore/allowFreeProviders, which the description never mentions. The description does contribute an end-to-end example object showing how a lead entry is shaped and what the decision output looks like, but that is marginal beyond the schema baseline.

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 line names a specific verb (screen), the resource (batch of leads/counterparties), and the exact composed operations (email_validate_deliverability + sanctions_screen_names in parallel) plus the merge logic. It also names sibling tools it orchestrates, so an agent can distinguish it from calling those tools individually 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 (onboarding, lead qualification, CRM hygiene where both checks matter), explicit WHEN NOT ('if you only need one check, call that tool directly (cheaper)'), and a named free alternative (email_check_syntax) as a pre-filter. Routing is fully determined.

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