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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, but the description adds substantive behavior beyond them: no network calls, local milliseconds, max 10,000 addresses, and the precise verdict vocabulary (invalid|risky|unknown, never valid). It does not discuss rate limits or concurrency, but for a pure local function that is minor.

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/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE blocks. Every sentence carries a distinct fact: no filler, no repetition, and the most decision-relevant scoping (no DNS) appears early.

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?

Even though an output schema exists, the description documents verdict values, reason enums, dns_checked:false, paging fields, and the summary counts — everything an agent needs to interpret results and to decide whether this tool or the paid sibling is appropriate. 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. The description goes beyond the schema by restating emails/limit/offset semantics and adding the EXAMPLE transformation, which clarifies how verdicts and did_you_mean are produced. It adds useful interpretation rather than repeating field docs.

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 and resource (offline email checks) and enumerates the exact checks: RFC-style syntax, typo suggestion, disposable domains, role accounts, free webmail. It clearly distinguishes itself from sibling email_validate_deliverability by stating it does not do DNS/MX.

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 sections explicitly state the pre-filtering use case and name the paid alternative email_validate_deliverability for MX/SPF/DMARC. The agent has a clear routing decision with 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, openWorld, and non-destructive, but the description goes far beyond them: it discloses the paid cost model ($0.002/email billed to the caller's APIFY_TOKEN), error codes, network-call latency (seconds to minutes, 300 s timeout), the fact that no email is sent, and that idempotency is only broken by live DNS changes. This is unusually rich 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 WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE structure is front-loaded and easy to scan, with no wasted preamble. The PARAMETERS section is somewhat redundant with the 100%-covered input schema, which keeps it short of a perfect conciseness 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 paid external-actor tool with 7 parameters, the description gives everything an agent needs: cost, required token, error taxonomy, paging behavior, latency, return shape, and the no-SMTP-probe limitation. An output schema exists, but the extra return-value detail is harmless and the description is complete without relying on it.

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. The description adds genuine semantic value beyond the schema by explaining the intended use case for allowFreeProviders ('set false for B2B lists') and illustrating the required emails array with a concrete JSON example. The remaining parameter text largely mirrors the schema, so it does not reach 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 opens with a precise verb+resource (runs email deliverability validation) and enumerates the specific checks performed (syntax, MX, disposable, SPF/DMARC, mail provider, verdict). It explicitly distinguishes itself from the free sibling email_check_syntax, so an agent can route correctly 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?

A dedicated WHEN section names concrete scenarios (cleaning lists before a send, verifying a lead's domain), and WHEN NOT explicitly excludes offline format/typo checks, pointing to the free email_check_syntax as the pre-filter alternative. The cost warning ('Pre-filter with free email_check_syntax to avoid paying for obviously bad rows') gives a clear decision rule.

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, so the safety profile is covered, yet the description adds substantial context they cannot carry: the paid billing model with per-package/per-vuln rates, a concrete cost example, network/latency characteristics with a 300s timeout, input caps (1000 packages, 2M chars), and a full tool-error taxonomy for remediation.

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 layout is scannable and front-loads purpose, cost and routing before details. It is long, and BEHAVIOR restates the read-only/idempotent traits already supplied by annotations, so a small amount of text 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 paid, network-bound, paged audit tool this covers everything an agent needs: cost exposure, timeouts, input limits, filter parameters, error codes and paging. Since an output schema exists, the RETURN rows summary is bonus rather than a necessary substitute.

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 meaning beyond it: it states that packages or manifestText is required (the schema declares zero required properties, so this cross-field constraint exists only in prose), and it clarifies offset paging via nextOffset from the prior response.

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 the concrete verb and resource ('parses package.json ... checks OSV ... returns per-package max severity/CVSS, fixed versions, recommended upgrade') and names the underlying actor. It explicitly distinguishes itself from the two OSV siblings, so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Has explicit WHEN and WHEN NOT sections that name the exact alternatives (osv_query_packages for a few exact versions, osv_get_vulnerability for one advisory) and the condition that selects each. This is textbook routing guidance.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, but the description adds operationally significant detail the annotations cannot: one HTTPS call per ID to api.osv.dev, no token, max 25 IDs per call, 20 s per-ID timeout, typical <2 s latency, and structured error codes (VULN_NOT_FOUND vs OSV_FETCH_FAILED) with a retryable flag.

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 labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) that make scanning trivial, and every section carries signal. It loses a point for internal redundancy: 'Free' appears three times and the 25-ID cap is stated three times.

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?

Even though an output schema exists, the RETURNS line gives the item shape and error variants, and the behavioral sections cover cost, auth, rate limits, timeouts, and paging via nextOffset. Nothing needed to call this tool 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 the baseline is 3 and the description largely restates the parameter docs (ids 1-25, limit default/max 25, offset paging). It does add a worked end-to-end example and reiterates the accepted ID prefixes (GHSA-/CVE-/PYSEC-), which gives the agent an invocation template beyond the raw 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 (Fetch) and resource (full OSV records) and enumerates exactly what each record contains (summary, severity vectors, affected ranges, fixed versions). It is immediately distinguishable from osv_query_packages (which finds vulns for a package version) and osv_audit_dependencies.

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 already have IDs from osv_query_packages or a report and need details or the fixed version) and WHEN NOT (finding vulns for a package version or manifest), with both alternatives named. This is exactly the routing information an agent needs to choose among the osv_* siblings.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, yet the description still adds material context beyond them: free vs paid, direct HTTPS to Google's public API with no token and nothing sent to the vendor, a 20 s timeout with typical <2 s latency, the 200-package cap, and a retryable error code (OSV_FETCH_FAILED). It also explains why results change (OSV publishing advisories), which is genuinely useful for a cacheable read.

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 front-loaded and skimmable. It is slightly verbose and repeats facts across sections (the 200-package cap and the free/no-key claim each appear more than once, and PARAMETERS largely restates the schema).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists, the description's RETURNS line still tells the agent the item shape, the error item type, meta.vulnerable_count, and the tool-level error code, and it covers cost, timeout, and paging. For a network-backed read tool with three parameters, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes further by restating each parameter's role (exact {ecosystem,name,version} entries, limit as page size, offset for paging) and giving a worked request example. It does not add much beyond the schema on ecosystem aliases or version-range restrictions, which 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 line names a specific verb (query), resource (OSV.dev database via api.osv.dev querybatch), and scope (exact package versions, returns vulnerable flags plus advisory IDs). It also names the two sibling tools it must be distinguished from, osv_get_vulnerability 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?

Explicit WHEN ('quick is lodash 4.17.20 vulnerable? checks for up to 200 packages'), explicit WHEN NOT (manifest/lockfile parsing, severity filtering, fixed-version resolution), and the alternative for that case is named with its tradeoff (osv_audit_dependencies, paid). This is a complete routing decision.

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 readOnlyHint/idempotentHint annotations: it discloses the exact cost model ($0.003/doc + $0.0005/finding billed to the caller's APIFY_TOKEN), that network calls occur to an Apify Actor and to documentUrls, latency (seconds to minutes, 300 s timeout), volume caps, and the concrete error codes returned (APIFY_TOKEN_MISSING, APIFY_PAYMENT_REQUIRED, etc.). This is exactly the paid-side-effect context an agent needs to decide whether to invoke.

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 WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE structure is well front-loaded and scannable. It is long, and the PARAMETERS block partially duplicates a 100%-covered schema, so a few lines do not fully earn their 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 13-parameter, nested-object, paid, open-world tool, the description covers inputs, alternatives, cost, latency, limits, error surface, and return shape (even though an output schema exists). An agent has everything needed to call it correctly and predict the consequences.

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 PARAMETERS block adds genuinely new information: the constraint that one of texts/documentUrls is required (the schema declares no required fields), the detect/redact/restore semantics including how placeholderMap is consumed, and an end-to-end EXAMPLE. It slightly restates defaults already in the schema, keeping it 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?

The WHAT line states a specific capability (PII/secret guarding) and explicitly positions it relative to a sibling: 'everything pii_scan_text does PLUS' NER names/locations, addresses, URL/PDF scanning, and restore mode. An agent can 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?

Dedicated WHEN and WHEN NOT sections name the selecting conditions (need NER names/addresses, need URL/PDF scanning, want the hosted pipeline) and explicitly route plain-text regex cases to the free pii_scan_text / pii_redact_text, while excluding images and email deliverability. 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 read-only, idempotent, non-destructive and closed-world, so those restatements add no credit. What the description adds beyond them is latency ('instant, <10 ms'), no network calls, local static data, and no rate limits — genuinely useful operational context, though it partially repeats the annotation hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Strongly front-loaded with labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR) and an example. Slightly over-structured: the RETURNS block restates an output schema that already exists, so a touch of the text 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?

Given an output schema already documents the return shape and annotations cover the safety profile, the description nonetheless supplies example input, cost, latency and routing guidance. An agent has everything needed to call it correctly and to route to it (or away) appropriately.

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 confirms this explicitly ('PARAMETERS: None; call with {}') and shows the empty-object call in the example, which is the maximum value possible for a no-arg tool.

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 and precise scope ('Catalog of every PII and secret entity type'), including what varies (local-free vs paid Actor). It explicitly contrasts itself against pii_scan_text and pii_redact_text, so an agent can distinguish it from 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?

Provides explicit WHEN ('before pii_scan_text / pii_redact_text to pick entityTypes') and WHEN NOT ('to actually scan text or redact it'), each naming the alternative tool. 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 beyond annotations: discloses the hash-style random salt caveat, consistency of placeholders across documents in one call, local/no-network/millisecond execution, size limits (50 texts, 200K each, 500K total), the INPUT_TOO_LARGE error, and paging behavior. Annotations already cover read-only/idempotent, and the description adds the nuance that idempotency breaks under hash style.

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?

Sectioned with labeled headers (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) and front-loaded. Dense but every labeled block carries distinct, useful information – no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, routing, cost, return shape (even with an output schema present it clarifies placeholder_map risk and page structure), limits, errors, and a concrete example. For a 9-param tool with a sensitive-data use case, it is fully self-sufficient.

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. The description adds value by grouping params, defaulting notes, the limit/offset paging relationship (nextOffset), and referencing sibling pii_scan_text for the shared entityTypes/allowList/entropyScan params. Minor: doesn't fully restate enum semantics already in 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 states a specific verb and resource ('Return sanitized copies of texts') and immediately names the mechanism (every PII/secret finding replaced) plus output styles. It is clearly distinguishable from pii_scan_text (report-only) and pii_guard_documents (NER/PDFs) by naming them directly.

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 ('right before sending user data to an LLM/third party') and WHEN NOT sections that name the exact alternatives (pii_scan_text for findings, pii_guard_documents for names/addresses/PDFs). It even explains the returnPlaceholderMap workflow.

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

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

Annotations already declare read-only, idempotent, closed-world, non-destructive, so the bar is met structurally; the description goes further by disclosing local-only execution with no network or token, hard input limits (50 texts / 200k chars each / 500k total), the INPUT_TOO_LARGE error, and the guarantee that raw values are never returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but strongly front-loaded with WHAT/WHEN/WHEN NOT labels and no filler prose. It is long, and the PARAMETERS section partially restates the schema, but every block 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 an 8-field, 7-parameter scan tool with an output schema, the description covers purpose, exclusions, cost, limits, error, and paging contract. The RETURN section is mild duplication of the output schema but no required context 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 adds value beyond the schema by noting allowList matching is case-insensitive, that entityTypes names come from pii_list_detectors, and by summarizing defaults and paging semantics in one place.

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 (detect/scan) and resource (PII and secrets in text) with an explicit enumeration of detector families. It also delineates scope against siblings by naming pii_redact_text and pii_guard_documents in the WHEN NOT block.

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 sending prompts/logs to an LLM or third party, auditing leaked credentials) and WHEN NOT (redaction, NER names/addresses, public URLs, PDFs, images) with the correct alternative tool named for each exclusion. 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 readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: no network calls, static local data, instant response, no rate limits, and no freshness reporting. It partially restates idempotency, which the annotation already carries, keeping it short of a 5.

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-block structure (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR) front-loads the decision-relevant content and is easy to scan. Slight redundancy between COST ('Free') and RETURNS (pricing) and a fairly verbose EXAMPLE keep it from being maximally tight.

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 spelled out, yet the description still sketches the shape. Cost, behavior, prerequisites, and an example call are all present, leaving nothing an agent needs to invoke 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?

There are zero parameters, so the baseline is 4; the description confirms this with 'None; call with {}' and an example invocation. No further parameter semantics are possible or needed.

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 covered sanctions lists) and its contents (id, name, authority, download URL), and explicitly contrasts itself with sanctions_screen_names. An agent can distinguish it from every sibling without opening the 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 an explicit WHEN clause (choose the lists parameter, cite sources, explain coverage before paying) and an explicit WHEN NOT clause naming the alternative tool sanctions_screen_names. The routing decision is fully specified.

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 (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial context beyond them: paid billing to the caller's APIFY_TOKEN at $0.005/name, 10-40 s list download and 300 s timeout, a full list of error codes, and the false-positive/miss disclaimer. It also notes idempotence is per list snapshot, which sharpens the annotation's claim.

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 ordering is strongly front-loaded and scannable, with cost and latency surfaced early. The PARAMETERS block largely duplicates the schema's own descriptions, which is the one section that doesn't fully earn its space.

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, network-bound, 7-parameter screening tool this is complete: cost, latency, limits (up to 10,000 names), auth failure modes, and result shape are all covered, and an output schema exists so return-field details are not owed by the description. An agent has everything needed to call it correctly and to set caller expectations.

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 information the schema lacks: the top-level schema has no required fields, and only the description states that names or queries is 'one required'. The worked EXAMPLE with minScore=90 and entityType also clarifies intent. It mostly paraphrases the remaining defaults, so not 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 description opens with a specific verb+resource ('Runs the ... sanctions-watchlist-screener: fuzzy-match people/organisations against OFAC SDN, OFAC Consolidated, EU, UK and UN lists') and names the exact watchlists, so the scope is unambiguous. It also distinguishes itself from the sibling sanctions_list_sources by casting that tool as the free coverage-info alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit WHEN (KYC/KYB onboarding, vendor/counterparty checks, bulk re-screening) and WHEN NOT (PEP/adverse media, certified compliance decisions) sections, plus a routing hint to the free sanctions_list_sources tool. It even states the batching rule ('Put all names in ONE call') and why (lists download once per run).

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, non-destructive, openWorld), but the description adds substantial context beyond them: per-lead pricing billed to the caller's APIFY_TOKEN, 2 Actor runs, 15-45s latency with a 300s timeout, partial-failure semantics ("unavailable" plus meta.errors), and named tool error codes. This is unusually rich disclosure for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Heavily front-loaded with labeled WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE sections that make scanning easy. It is on the long side and repeats the cost model in both COST and BEHAVIOR, but nearly every sentence carries actionable content.

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-Actor, network-bound tool this covers everything an agent needs: cost, latency, timeout, partial-failure and error handling, input shape, paging, and an end-to-end example. An output schema exists, yet the description still orients the agent on return shape without redundancy being harmful.

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 five parameters are already documented in the schema, and the description's PARAMETERS section largely restates them (defaults, ranges, the B2B rationale for allowFreeProviders). It adds little beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (screen a batch of leads by running email deliverability and sanctions screening in parallel, then merging per-lead into a pass/review/block decision). It explicitly names the two sibling tools it composes (email_validate_deliverability, sanctions_screen_names), so an agent can distinguish it from calling those directly.

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 (onboarding, qualifying inbound leads, CRM hygiene) and WHEN NOT (use the single-check tool directly as it is cheaper; email_check_syntax as a free pre-filter). Alternatives and the condition selecting them are 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.