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

Annotations already cover read-only/idempotent/no-open-world, yet the description adds substantial non-structural behavior: no DNS/SMTP network calls, synchronous CPU-bound execution, no rate limits, sub-second throughput at the 10,000-address cap, and the crucial limitation that dns_checked is always false. It also flags duplicate non-merging and the fact that meta.summary counts all rows rather than the page.

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/BEHAVIOR/PARAMETERS/EXAMPLE structure is well front-loaded and scannable, and each block carries real information. It is long, with mild restatement ('never valid' and dns_checked appear in both WHEN NOT and RETURNS), so it stops just short of maximal 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?

For a three-parameter, high-throughput batch tool with an output schema, the description supplies everything the schema and annotations cannot: verdict vocabulary, normalization semantics, paging interplay with meta.summary, and cost/latency expectations. Nothing needed to call it correctly is left unstated.

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 goes well beyond it with normalization rules (Name <addr> reduction, mailto: stripping, domain lowercasing with local-part case preserved, trailing-dot removal, punycode), the fact that a comma-separated list inside one element is INVALID_SYNTAX rather than split, +tag-insensitive role detection, and disposable matching on subdomains. This is exactly the kind of input-shape detail the schema cannot express.

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 (check) and enumerates the four concrete checks performed (RFC syntax/normalization, domain typo, disposable, role/free-webmail), and the WHEN NOT line names the sibling email_validate_deliverability as the differing case. An agent can distinguish this tool from every sibling 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 (fast pre-filtering of signups/lead lists before paying for deliverability) and WHEN NOT (cannot verify MX/DNS; verdict is never "valid"), plus a named paid alternative for that case. Routing is fully determined by the text.

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/idempotent; the description adds materially: no email is sent, live-DNS dependence, network calls via an Apify Actor in the caller's account, seconds-to-minutes latency with a 300s timeout, consolidated error codes (APIFY_TOKEN_MISSING, PAYMENT_REQUIRED, etc.), and repeated billing on every call including offset-only changes. Nothing here contradicts readOnlyHint/idempotentHint.

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/BEHAVIOR/PARAMETERS/EXAMPLE layout is strongly front-loaded and scannable. It is long, but the length is justified by seven parameters, paid billing, and error semantics; only minor repetition (a few restated 'free'/'paid' points) could be trimmed.

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 values need not be spelled out, yet the RETURNS line still orients the agent on paged 'email' rows versus 'error' rows. Combined with cost, latency, timeout, and paging/billing caveats, an agent has everything needed 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 already 100%, so the baseline is 3, but the description goes well beyond it: it explains that list/"Name <addr>" forms are split and deduplicated so you pay once per unique address, that allow* flags only downgrade to 'risky' and can never rescue a truly invalid address, that reason codes appear in reasons[] regardless of flags, gives typical B2B/consumer presets, and clarifies checkSpfDmarc affects fields but not verdict or price.

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 the exact Actor (email-validator-mx-disposable), enumerates every check performed, and states the output verdict set. It is immediately distinguishable from siblings like email_check_syntax and trust_screen_lead, which it explicitly names and contrasts.

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 gives the selecting condition (only when MX/DNS matters, e.g. list cleaning or lead-domain verification) and WHEN NOT names the alternatives, email_check_syntax for offline format/typo work and trust_screen_lead for leads needing sanctions screening. It also prescribes pre-filtering to avoid paying for obviously bad rows.

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 declare readOnly/idempotent/openWorld, and the description adds substantial context beyond them: full pricing model ($0.0005/pkg + $0.0015/vuln + $0.00005/run) billed to the caller's Apify account, network calls to an Apify Actor, seconds-to-minutes latency with a 300s timeout, input caps (1000 packages / 2M chars), and an enumerated error-code list. This is exactly the extra burden a cost-incurring tool requires.

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 structured with WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE labels and the key purpose front-loaded. It is long, but for a paid multi-mode tool nearly every line carries decision-relevant information; minor trimming is possible but nothing is wasted.

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 description still summarizes the row types and error codes, covers cost, latency, and limits, and clarifies mode selection. Nothing an agent needs to invoke this correctly and safely 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 the baseline is 3. The description nonetheless adds billing-relevant semantics not obvious from the schema (e.g. 'Use minSeverity=HIGH to cut vuln rows' and that only matching rows are billed), plus a worked EXAMPLE and the packages-or-manifestText mutual-requirement.

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 ('parses package.json/requirements.txt/go.mod... checks OSV... returns per-package max severity/CVSS, fixed versions, recommended upgrade'), and explicitly distinguishes the manifest-based audit from the single/lookup siblings. An agent can tell exactly what this does versus osv_query_packages.

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 ('full project audits from a pasted manifest, CI-style reports') and WHEN NOT ('quick checks of a few exact versions or one advisory') sections, each naming the specific free alternative (osv_query_packages, osv_get_vulnerability). 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 cover read-only/idempotent/open-world/destructive, but the description goes well beyond them: one parallel HTTPS call per ID, <2s typical and 20s timeout, 25-ID cap, two distinct error classes with different retryability (VULN_NOT_FOUND non-retryable vs OSV_FETCH_FAILED retryable per-ID), and the fact that pagination re-fetches every ID.

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?

Labelled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) make a long description scannable and front-loaded. It is slightly verbose, with minor repetition (the free/no-token cost is stated in the title, COST line and WHEN NOT).

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 3-param, single-resource fetch tool with rich annotations and an output schema, the description covers everything an agent needs: scope, cost, timing, error taxonomy, ID format guidance, and pagination mechanics. No material gap remains.

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 real semantics: IDs are fetched individually and yield one row in input order, matching is literal with no URL/prefix trimming, duplicates are fetched twice, ecosystem/GHSA IDs are preferred over CVE IDs, and next-page calls must resend the same ids with offset=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 WHAT line names a specific verb (Fetch) and resource (full OSV records for advisory IDs from api.osv.dev), and even enumerates the fields returned. It explicitly distinguishes itself from osv_query_packages and osv_audit_dependencies, 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?

WHEN states the precondition ('you have IDs... and need details or the fixed version') and WHEN NOT names both alternatives with their selection condition (query by package version vs whole manifest) plus their cost model. 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 safety (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: one HTTPS request to api.osv.dev, free/no token, typical latency and 20s timeout, retryable OSV_FETCH_FAILED, per-entry INVALID_ECOSYSTEM rows, and that results only change when OSV publishes advisories. This is a rich disclosure of cost, network behavior, and failure modes.

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/BEHAVIOR/PARAMETERS/EXAMPLE) make it easy to scan and the most important routing information is front-loaded. It is longer than necessary, with the PARAMETERS section partly restating schema descriptions, but every section still carries useful 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?

Given a 3-parameter tool with 100% schema coverage, rich annotations, and an output schema, the description covers the remaining gaps an agent needs: cost, endpoint behavior, error semantics, paging quirks, and a concrete example. Nothing material 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 the baseline is 3, but the description adds real meaning: duplicate entries are queried twice, each entry produces exactly one row in input order, limit/offset page rows while all packages still go to OSV in one request, and meta.vulnerable_count counts all packages. Some content (ecosystem aliases, exact-version requirement) duplicates the schema, keeping it from 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?

The WHAT line names a specific verb (query), resource (OSV.dev package versions), and output (vulnerable flags and advisory IDs). It explicitly distinguishes itself from osv_get_vulnerability (detail lookup) and osv_audit_dependencies (manifest parsing/severity), so an agent can select it 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?

WHEN and WHEN NOT are both stated with named alternatives and the exact conditions that select them: quick version checks up to 200 packages here, manifest/lockfile auditing or severity filtering in osv_audit_dependencies. 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 cover the safety profile (readOnly/openWorld/idempotent/non-destructive) and no auth or cost information; the description adds the pricing model and billing target ($0.0015/doc + $0.0002/finding, billed to your Apify account), network/Actor-run behavior, latency and 300s timeout, input caps, and a full error-code list. It also discloses the non-obvious billing trap that limit/offset only page results while every call re-processes and re-bills the whole input.

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 front-loaded with WHAT/WHEN/WHEN NOT before the dense detail, and every block is relevant to a 13-parameter paid tool. It is nevertheless long and repeats some material already in the schema (e.g., mode semantics, allowList semantics), which costs it the top score.

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 13-parameter, nested-schema, network-calling paid tool with an output schema, the description covers cost, latency, caps, error codes, paging/billing behavior, and mode-field interactions. An agent has everything needed to call it correctly and to avoid unexpected charges.

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 interaction semantics the schema does not: which fields each mode consumes or ignores, that detectNames/detectAddresses must be enabled before PERSON/LOCATION/STREET_ADDRESS are usable in entityTypes, that returnPlaceholderMap only applies to redact+placeholder, that a missing placeholder is left untouched in restore mode, and that narrowing entityTypes reduces finding charges.

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 (runs the llm-data-guard-pii-secrets Actor for PII/secret scanning of text and documents/URLs) and immediately scopes it as a superset of pii_scan_text. It explicitly distinguishes the tool from named siblings (pii_scan_text, pii_redact_text, pii_restore_text), so an agent can pick it 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?

Dedicated WHEN and WHEN NOT sections give the selecting conditions and the free alternatives for each excluded case (plain text -> pii_scan_text/pii_redact_text, placeholder restoration -> pii_restore_text, no OCR for images). This is textbook routing guidance with explicit exclusions, not just implied usage.

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 readOnly/idempotent/openWorld, and the description adds genuinely new behavioral context: no network calls, static local catalog, instant (<10 ms), no rate limits, and free with no token. This exceeds what the annotations provide.

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 blocks (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) front-load the routing decision, and each line carries distinct information. Length is justified by the cross-tool dependency it documents.

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-param, free, read-only catalog with an output schema, the description covers purpose, routing, cost, latency, and how its output maps into sibling parameters. An agent has everything needed to call it and use 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?

Zero parameters, so the baseline is 4. The description still adds value by stating the call must use an empty object {} and, importantly, how the returned 'type' and 'redaction_styles' keys feed other tools' parameters — but that is output semantics more than input semantics.

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: a catalog of every PII/secret entity type, plus which run locally for free vs only in the paid Actor, redaction styles, and pricing. It clearly distinguishes itself from the scan/redact siblings it names.

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 pii_scan_text / pii_redact_text to pick entityTypes') and WHEN NOT ('To actually scan text... or redact it'), naming the alternatives by tool name. 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 readOnly/idempotent/non-destructive/local, yet the description adds real operational facts: no network calls, millisecond latency, deterministic output except the hash style whose salt is random per call, the INPUT_TOO_LARGE error, and the 50-doc / 200k-per-doc / 500k-total limits. It also warns that the placeholder map contains originals and must be kept out of the LLM prompt, which is exactly the kind of risk an annotation 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 labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) make it skimmable and front-loaded with the decision-relevant parts. It is long and mildly repetitive — the size limits appear in both BEHAVIOR and PARAMETERS, and 'free/local' is restated from the title — but nothing 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 9 parameters, a mutation-adjacent redaction result, and an output schema, this is the level of detail needed: limits, error code, determinism guarantees, restoration path via pii_restore_text, and a concrete input-to-output example. An agent has everything required to call it correctly and to interpret the response.

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 PARAMETERS block adds semantics the schema does not: placeholder consistency across documents in one call with numbering restarting per call, 'hash' being non-comparable across calls, returnPlaceholderMap being silently ignored for mask/hash, and limit/offset paging whole documents rather than findings. These are non-obvious interaction rules between parameters, not restatements.

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 and resource ('Return sanitized copies of texts with every local PII/secret finding replaced') plus the three replacement styles, and the WHEN NOT line names the two siblings it is not (pii_scan_text for reports, pii_guard_documents for NER/URLs/PDFs). An agent can distinguish the three text-PII tools 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?

WHEN gives the trigger ('right before sending user data to an LLM/third party') and adds a conditional hint for returnPlaceholderMap when restoration is needed. WHEN NOT explicitly routes findings-only work to pii_scan_text and NER/URL/PDF cases to pii_guard_documents, so both the use case and the exclusions 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 readOnlyHint/idempotentHint/non-destructive/no-open-world, but the description adds substantial context beyond them: it runs 100% locally with no network and the map never leaves the machine, states hard input limits (50 texts, 200k chars each, 500k total, 10k map entries), and warns that the output contains ORIGINAL sensitive values so it must be shown to the user and not sent back to the LLM.

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?

Although long, it is densely labeled (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) and front-loaded, so an agent can skim to the needed section. A few limits are restated from the schema, but every sentence carries actionable information and the concrete JSON example seals the call format.

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 mutation-of-text tool with a nested object parameter, the definition covers purpose, prerequisites, cost, return shape, error code (INPUT_TOO_LARGE), safety constraints, parameter edge cases and limits. An output schema exists, yet the RETURNS line still usefully names the fields (output_text, replacements, unknown_placeholders).

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 already 100%, the description adds semantics the schema cannot convey: placeholderMap keys are replaced exactly, case-sensitively, longest key first, in one pass so a restored value is never re-replaced; and unknown_placeholders lists [TYPE_N]-shaped tokens the map lacks and that stay untouched. It also clarifies limit/offset page whole documents.

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 (restore) and resource (original values / placeholders in texts), and explicitly says it consumes the placeholder map from pii_redact_text or pii_guard_documents. It is immediately distinguishable from siblings like pii_redact_text and pii_scan_text, which are called out in the WHEN NOT line.

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 line gives the exact prerequisite workflow (after a sanitized prompt was answered, before showing to the user) and WHEN NOT names the two alternative tools plus the key exclusion that masked/hashed values are not reversible (only placeholder style is). 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?

Goes well beyond the annotations: no network calls, data never leaves the machine, millisecond latency, raw values never returned (masked previews only), and the INPUT_TOO_LARGE failure mode. Annotations already cover readOnly/idempotent/closed-world, so this extra operational context is a genuine addition; it is not quite 5 only because latency/limits are asserted without any guidance on batching strategy beyond the split hint.

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?

Uppercase section labels make it front-loaded and scannable, and most sentences carry unique information. There is some duplication — "Runs 100% on your machine" is restated as "text never leaves your machine", and the 50/200k/500k limits repeat the schema — but the paging and sum-cap nuances justify most of 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?

For a 7-parameter scanner with a complex paging contract, the description covers input sizing, filtering semantics, error handling, cost/auth, and paging continuation. An output schema exists, yet the RETURNS/EXAMPLE lines still give the agent enough to interpret and iterate on 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?

Despite 100% schema coverage, the description adds real semantics the schema lacks: entityTypes filters after detection and applies case-insensitively with silent no-match on unknown names, enttropyScan is purely additive, allowList matches whole values not substrings, defaultPhoneRegion only affects national-format numbers, and limit/offset page a flat cross-document findings list while meta.documents summarises all documents.

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 an explicit verb+resource ("Detect PII ... and secrets ... in text") and enumerates the concrete detector families covered. It also names the sibling tools it is not (pii_redact_text, pii_guard_documents), so an agent can disambiguate 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?

A dedicated WHEN section gives the triggering scenarios (before sending prompts/logs to an LLM, auditing for leaked credentials), and WHEN NOT routes to specific alternatives with the reason (redaction, NER names/addresses, URLs/PDFs, images). No inference is left to 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?

Annotations already declare readOnly/idempotent/no-open-world, and the description still adds non-obvious behavior: no network calls, static local catalog, instant, no rate limits, and explicitly what it does NOT do (no list downloads, no freshness reporting). It also flags the operational obligation to show the disclaimer alongside screening results, which no structured field conveys.

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/BEHAVIOR/PARAMETERS/EXAMPLE) front-load the routing decision and cost before details. Every line carries distinct information; there is no filler 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?

An output schema exists, so return values need not be enumerated, and the sample response plus the note that output feeds sanctions_screen_names completes the picture. Cost, offline behavior, and unsupported capabilities are all covered for this trivial zero-parameter 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?

Zero parameters, so the schema carries nothing to clarify and the baseline is 4. The description usefully states the call convention (empty object {}, static, unfilterable) and even ties sources[].id values to the sibling's lists parameter, which is bonus semantic linkage rather than input documentation.

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 specific resource (the static catalog of official sanctions lists filtered by sanctions_screen_names) and its fields (id, name, authority, download URL), plus the score scale and disclaimer. It is clearly distinguishable from the sibling sanctions_screen_names, which is the paid screener this list serves.

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 (choose the lists parameter, cite sources, explain coverage before paying) and WHEN NOT (to screen a name, use sanctions_screen_names, paid), naming the alternative and the condition that selects it. 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 declare readOnly/openWorld/idempotent, and the description layers on material context they cannot carry: exact cost model ($0.003/name + $0.007/run), cache vs re-download latency bands, the 300 s timeout, that offset-only paging re-screens and re-bills every name, and enumerated INPUT_EMPTY/APIFY_* error codes. It also discloses the reliability caveat (false positives/misses, not a certified service), which is critical for a screening decision.

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 WHAT/WHEN/WHEN NOT and labeled sections make a long definition navigable, and most content is decision-relevant. It is verbose at the edges (exhaustive error-code list, precise dollar examples) where slightly tighter prose would preserve the meaning.

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, networked, non-certified tool, every dimension an agent needs is present: cost, latency, billing pitfalls, filtering semantics, and failure modes. An output schema exists, yet the description still summarizes the returned row shapes (screening/error, status, matches[], lists_unavailable), leaving no material gap.

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 baseline is 3, but the description adds genuine semantics beyond schema: names vs queries selection logic (bare strings vs country/DOB/entityType or id echo), that dateOfBirth drops individuals >1 year apart while country only sets country_match and never filters, entityType 'entity' covering vessels/aircraft, minScore tuning bands, and that maxMatchesPerName caps matches[] only while match_count reports all.

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 ('fuzzy-match people/organisations against OFAC SDN, OFAC Consolidated, EU, UK and UN lists') and names the batch scope (up to 10,000 names). It explicitly distinguishes itself from siblings by routing to sanctions_list_sources for coverage and trust_screen_lead for email-bearing leads, so an agent can tell it apart 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?

The WHEN clause names concrete scenarios (KYC/KYB onboarding, vendor/counterparty checks, bulk re-screening) and the WHEN NOT clause names exclusions (PEP/adverse media, certified compliance decisions) plus the specific alternative tools for those cases. 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses critical behavioral traits: cost model ($0.00079/lead email + $0.003/name + $0.007/call sanctions fee, example pricing), runtime (~5-45s, 300s timeout), parallel Actor execution (2 runs per call in user's account), partial failure semantics ('unavailable' + meta.errors), error codes (INPUT_EMPTY, APIFY_TOKEN_MISSING), billing behavior (identical emails billed once, each check billed separately), caching (sanctions lists at most 6h old), and decision precedence. It also explicitly states 'No email is sent', which is important given the 'email' parameter could suggest sending.

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 labeled sections (WHAT, WHEN, WHEN NOT, COST, RETURNS, BEHAVIOR, PARAMETERS, EXAMPLE) that scan quickly. It is dense but every sentence carries actionable information; the main detractor is that the PARAMETERS and COST sections are somewhat terse and interleaved, requiring the reader to parse a dense block to extract billing edge cases. It's not bloated, but the heavy density prevents 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?

Given the tool's complexity (paid, multi-actor, paged, partial-failure semantics) and the presence of an output schema, the description covers all critical operational details an agent needs: cost awareness, paging and re-billing warnings, partial failure semantics, error codes, decision precedence, and a concrete example. Nothing essential is missing from the call's perspective.

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%, but the description adds substantial value beyond it: it explains the interaction between email and name (if only email given, sanctions_status='not_checked'; if only name, email_verdict='not_checked'), the billing linkage to which checks run, ref uniqueness defaulting to the 0-based index string, country annotation-not-filtering behavior, entityType filtering vs country annotating, minScore default of 88 (stricter than the sibling's 85) with rationale, allowFreeProviders=false mapping to 'review' (never 'block'), and decision precedence rules. This goes well beyond the 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?

The description names a specific verb (screen) and resource (leads) and precisely states the composite operation: email_validate_deliverability + sanctions_screen_names in parallel, merged into a per-lead decision. It explicitly distinguishes itself from the two building-block siblings and clarifies it's for when both checks and one decision are needed.

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 and WHEN NOT sections: 'Onboarding customers/vendors...' for use, and for non-use it routes to email_validate_deliverability for email-only, sanctions_screen_names for names-only, and email_check_syntax as a free pre-filter. It states the condition under which this tool is appropriate ('only when a lead needs both checks and one decision').

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