Fairquery Agent Trust & Data Safety

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

The description adds substantial behavioral context beyond annotations: it runs on a hosted Worker, inputs leave the client, it is designed not to store inputs/results/tokens, makes no DNS/SMTP network calls, is synchronous and CPU-bound, and has no rate limits with 10,000 addresses returning quickly. It also discloses that verdicts never include valid because DNS is not checked. These details are consistent with readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false.

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 long but front-loaded and organized under clear labels (WHAT, WHEN, WHEN NOT, COST, RETURNS, BEHAVIOR, PARAMETERS, EXAMPLE). Each section carries operational value for a tool with several edge cases, so the length is justified rather than redundant.

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, the schema, annotations, and output schema, the description is complete enough for an agent to call it correctly. It covers purpose, exclusions, normalization edge cases, paging behavior, cost, execution environment, and expected return semantics.

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 important semantics: each array element is parsed independently, comma-separated lists in one element are invalid, normalization rules are specified, duplicates are not merged, rows preserve input order, and limit/offset page rows while meta.summary always counts all rows. This meaningfully extends 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 description states specific offline email checks: syntax/normalization, typo suggestions, disposable domains, role accounts, and free webmail. It explicitly distinguishes this pre-filter from the paid delivery-validation sibling, 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?

It provides explicit WHEN and WHEN NOT guidance, naming email_validate_deliverability as the alternative for DNS/MX/SPF/DMARC checks. The use case is framed clearly as fast pre-filtering of signups or lead lists before paying for delivery validation.

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 read-only/open-world/idempotent, but the description adds the traits that actually change agent behavior: paid with exact per-1,000 pricing billed to the caller's Apify account, a 20-second wait, an enumerated set of APIFY_* error codes, and the fact that no SMTP probe or email send occurs. It also discloses the Worker-to-Apify forwarding path and that results vary only with live DNS.

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 a WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE skeleton, so an agent can stop reading at any level of detail. Length is justified by 7 parameters, live billing, and timeout semantics; the only mild redundancy is the pricing restated as an arithmetic example, which still aids cost estimation.

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 everything needed to invoke correctly: cost model, timeout ceiling, error taxonomy, output row shapes, and the billing trap around paging. Even though an output schema exists, the description of "email" vs "error" rows and the reasons[] field is a useful complement rather than padding.

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 description adds semantics the schema cannot express: input splitting/dedup so you pay once per unique address, the rule that allow* flags can only downgrade to "risky" and never upgrade an invalid address, that POSSIBLE_TYPO and IMPLICIT_MX_ONLY are unconditional, and that offset re-bills the whole list. These are genuinely decision-changing details absent from the property descriptions.

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

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

States a specific verb+resource (deliverability validation via a named Actor) and enumerates the exact checks performed and the four possible verdicts. It explicitly separates itself from email_check_syntax (offline checks) and trust_screen_lead (merged decision), so an agent can route 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?

Has explicit WHEN and WHEN NOT sections naming the alternative tools and the deciding condition ("only when MX/DNS matters", "pre-filter with email_check_syntax"). It also gives concrete preset configurations (B2B list vs consumer signups), which removes most remaining 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, the description discloses that execution occurs on a Fairquery-hosted Cloudflare Worker, inputs leave the client, and the Worker is designed not to store inputs or results. It also explains ATS-specific request behavior, 404 handling, Ashby/Personio board-listing fallbacks, retryable errors, and the precise meaning of 'open'.

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 long but strongly structured with WHAT, WHEN, WHEN NOT, BEHAVIOR, COST, RETURNS, PARAMETERS, and EXAMPLE sections. Most content earns its place for a complex, multi-ATS tool, though some ATS-specific details are repeated and make it denser than strictly necessary.

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

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

The definition covers purpose, alternatives, behavioral constraints, costs, return shape, error modes, and parameter implications. With annotations and an output schema also present, an agent has enough information 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 schema already defines each parameter thoroughly. The description still adds meaningful operational semantics: malformed jobKey or incomplete ats+slug+jobId returns INVALID_INPUT without a request, includeDescription affects Ashby/Personio board downloads, and description_text has specific processing limits.

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: re-check ONE job on the employer's ATS now and report open or closed. It also distinguishes this tool from sibling tools such as jobs_get_job, jobs_get_board, and jobs_search_companies.

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 and WHEN NOT sections are explicit, naming the exact alternatives for full detail, board listing, and bulk checking. The conditions for selecting this tool versus its siblings are unambiguous.

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

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

Annotations already cover read-only, open-world and idempotent, yet the description adds substantial undisclosed behavior: inputs leave the client, the lookup pipeline order, robots.txt and private-IP refusal, at most 6 ATS GETs, retry/backoff, and a 403/429 kill switch that degrades to a HOST_BLOCKED meta note rather than an error. The only real gap is that the rate-limit and backoff numbers are more operational detail than decision-relevant, diluting rather than informing.

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/BEHAVIOR/COST/RETURNS/PARAMETERS/EXAMPLE headings make it scannable and front-loaded, and the routing information comes first. But for a one-parameter tool it is roughly 400 words, with low-value specifics (0.5–1.6 s backoff, 15 s timeout, exact probe count) that an agent cannot act on.

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 explained, yet the description still clarifies the row shape, the NO_BOARD_FOUND error row, and the confidence semantics of slug_probe hits. Nothing an agent needs in order to call this correctly and interpret the result is missing.

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

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

Schema coverage is 100% and the schema already gives the three example forms, but the description goes well beyond it: board URL and personio:account are parsed with no network call, a domain enables the careers-page step, a plain name only uses the starter list and slug probes. It also documents suffix stripping and the Greenhouse→Lever→Ashby probe order, so the agent can predict which form to pass for the result it wants.

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: resolve a company name/domain/URL to its public job board on Greenhouse, Lever or Ashby. It immediately delimits scope against siblings by naming jobs_get_board and jobs_search_companies and by listing unsupported ATSes (Workday, Workable, Recruitee, Rippling, LinkedIn).

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 / WHEN NOT block is explicit: use it before jobs_get_board when you only know the company name or have a Personio URL; skip it when you already have ats + slug or want companies plus jobs in one step. It also states a negative capability set so the agent does not waste a call.

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, it discloses hosted Worker execution, input egress, no-storage design, per-host request behavior, Personio lane throttling, Lever Crawl-delay spacing, 403/429 kill-switch behavior, no-history semantics, and cost. These details materially help an agent understand safety, latency, 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?

The description is dense but well-structured with WHAT, WHEN, WHEN NOT, BEHAVIOR, COST, RETURNS, PARAMETERS, and EXAMPLE sections. For a 12-parameter tool with multiple ATS backends and operational caveats, the length is justified and front-loaded.

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?

It covers purpose, usage routing, supported and unsupported providers, behavioral constraints, request patterns, cost, return semantics, filter semantics, and an example. With annotations and an output schema already present, the description supplies everything an agent needs to select and call 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 description coverage is 100%, but the description still adds meaningful semantics beyond the schema: filters are AND-ed while values within one filter are OR-ed, title matching uses whole words, country filtering can drop unknown-country rows, and postedWithinDays drops null posted_at rows. It also explains paging drift because pages re-fetch the board.

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: fetch every currently published job from one named board via an official ATS API or Personio feed, normalize, and filter it. It explicitly covers supported ATS types and distinguishes itself from siblings such as jobs_get_job, jobs_find_board, and jobs_search_companies.

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 provides explicit WHEN and WHEN NOT guidance, including the prerequisite that the ats and slug are already known. It names alternatives for single-job detail, multi-company/history search, unknown boards, and Personio discovery, and lists unsupported ATS providers.

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 annotations, it discloses the hosted-worker execution model, that inputs leave the client, no storage design, which hosts receive which identifiers, rate-limit behavior, kill-switch behavior on 403/429, and precise error mappings. This is unusually strong behavioral disclosure for an open-world 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?

The description is long but tightly structured with WHAT, WHEN, WHEN NOT, BEHAVIOR, COST, RETURNS, PARAMETERS, and EXAMPLE. It is front-loaded with the key distinction and every section carries operational information relevant to correct invocation.

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 open-world complexity, multiple supported ATS providers, output schema, and annotations, the description is complete: it covers return shape, error taxonomy, retryability, sanitization, and provider-specific request behavior. An agent should be able to call this correctly without extra documentation.

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 100%, the description adds substantive semantics: jobKey malformed or incomplete ats + slug + jobId returns INVALID_INPUT with no request, Ashby and Personio ids trigger board/feed downloads rather than per-job endpoints, and descriptions are capped and sanitized. These details go 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 description states a specific verb and resource: fetching the full detail of ONE currently published job from supported ATS sources, including its description. It clearly distinguishes this from listing all openings or checking open/closed status, so an agent can select it 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?

It gives explicit WHEN and WHEN NOT sections, naming jobs_check_open, jobs_get_board, and jobs_search_companies as alternatives with the conditions that select them. It also lists unsupported ATS providers to prevent misselection.

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, and openWorld=false (offline), so the safety profile is largely pre-declared. The description still adds real value beyond that: hosted Worker execution, inputs leaving the client, no storage of inputs or results, no further network call, no APIFY_TOKEN/billing, and staleness of jobs_at_verification. It stops short of describing the response envelope or pagination mechanics in prose, which keeps it at a solid but not exceptional level for an annotated 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?

Labeled sections (WHAT/WHEN/WHEN NOT/BEHAVIOR/COST/RETURNS/PARAMETERS/EXAMPLE) make it front-loaded and skimmable, and every block targets a real decision. It is longer than necessary for a 3-parameter read tool, with the Personio exclusion stated twice and a COST section that overlaps the offline claim.

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 no prose explanation, and the description still flags the stale snapshot field and the paged ordering. Combined with annotations and full schema coverage, an agent has everything needed to call this correctly and chain into jobs_get_board with ats + slug.

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 exceeds it by explaining that ats narrows the list, that omitting it yields all three ATSs, and critically that meta.by_ats ignores ats so paging totals must come from total. That by_ats caveat is non-obvious semantics the schema cannot express. The Personio exclusion is repeated from the schema, costing a little.

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 gives a specific verb (list) and resource (bundled starter list of company job boards) plus the exact fields returned. It explicitly distances itself from jobs_get_board (live data) and jobs_find_board (off-list companies), so an agent can pick it without opening a schema.

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

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

Dedicated WHEN and WHEN NOT blocks name the two sibling alternatives and the exact condition that selects each. It also scopes expectations ('a starting point, not a global index of employers'), which prevents misuse as a full employer index.

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?

Adds substantial behavior beyond annotations: APIFY_TOKEN requirement, Worker forwarding and 20-second wait with APIFY_TIMEOUT, actor execution in the caller's Apify account, history stored in a named key-value store, politeness rules, and output being that run's rows rather than a public directory. It also discloses billing structure and that every call starts a new billed run, which is important for a non-idempotent paid operation.

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?

Despite being long, it is tightly structured with WHAT, WHEN, WHEN NOT, BEHAVIOR, COST, RETURNS, PARAMETERS, and EXAMPLE headings. The most decision-relevant information is front-loaded, and the length is justified by the 18-parameter paid tool's complexity.

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?

Complete for a complex paid, non-idempotent, open-world tool: it covers authentication, timeout behavior, state storage, pricing examples, legal/robots constraints, return row types, pagination semantics, and a concrete example. No material gap remains for an agent 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?

Even with 100% schema coverage, the description adds critical cross-parameter semantics the schema cannot express: at least one of companies, boards, or useSeedList is required despite all being schema-optional, onlyNew compares against the last run for the same stateStoreName, and limit/offset page the current result on the Worker rather than triggering new runs. These details materially improve correct invocation.

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: run the Fairquery Apify Actor over many companies or boards, including discovery, filters, history, and re-checks. It explicitly distinguishes itself from sibling tools in WHEN NOT (jobs_get_board, jobs_get_job, jobs_check_open), so an agent can route correctly without opening schemas.

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

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

Gives explicit WHEN and WHEN NOT conditions, naming the exact alternatives for one board, one job detail, and one re-check. It also clarifies the monitoring use case and the scale threshold where this tool is appropriate.

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?

Far beyond the annotations: it discloses that the scan is free, runs on a hosted Cloudflare Worker rather than the caller's machine, that tool names and descriptions leave the client, that the Worker is designed not to store or forward them to Apify, and that durable scans elsewhere are paid ($0.50/1,000 packages). It also discloses the no-disk constraint that makes path/packageName fail and that no network call or process spawn occurs at defaults — consistent with openWorldHint=true.

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 WHAT/WHEN/WHEN NOT and scannable section labels, and each section earns its place. It loses a point for repetition — the 'path and packageName refused, no disk' point is restated in COST, BEHAVIOR and PARAMETERS, and the paid-pricing detail appears twice.

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 9 optional parameters, a hostile-input domain and a real output shape, the description covers preconditions, cost, data handling, error codes, return-row structure, risk_level values and paging. An output schema exists, so leaving return-value detail light is appropriate and it still summarizes the finding rows and meta fields.

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

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

Schema coverage is 100% and the schema already documents per-parameter refusals, so the baseline is 3. The description adds genuine cross-parameter semantics not in the schema: tools/toolsListJson mutual exclusion yielding INPUT_EMPTY, the 20,000-char per-field and 500,000-char total scan caps, minSeverity and includeDevDependencies being inert on this Worker, and the example payload.

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 ('pre-install check for one MCP server') and enumerates exactly what it scans: tool names, descriptions, parameter text, for injection phrasing, concealed characters, hidden markup and cross-server shadowing. It explicitly distinguishes itself from osv_audit_dependencies and osv_query_packages, 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?

WHEN names the precondition (before installing/enabling, once you have a tools/list result) and WHEN NOT names two concrete alternatives with their selecting conditions (dependency audit with no tool list, a few exact versions). It also states a hard boundary: it does not install, start or execute the package.

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, idempotent, non-destructive); the description adds substantial context beyond that: per-package/per-vulnerability pricing billed to the caller's Apify account, a 20 s timeout with APIFY_TIMEOUT as the failure mode, a concrete cost example, an enumerated error-code list (APIFY_PAYMENT_REQUIRED, APIFY_TOKEN_MISSING, etc.), and input size ceilings. The privacy note about token forwarding is hedged ('designed not to store') but is volunteered rather than omitted.

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 purpose and routing before cost and mechanics. Dense but every block carries information an agent needs for a paid, third-party-hosted call; 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?

For a 7-parameter, paid, open-world tool with an output schema, the definition covers invocation requirements (token), cost model, failure modes, size limits and paging. The RETURNS block duplicates the output schema but the duplication is harmless and the rest leaves no ambiguity about how 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 coverage is already 100%, so the description's parameter block is largely restatement; however it does add decision-relevant meaning, notably that minSeverity also suppresses vulnerability rows for billing purposes and that limit/offset drive paging (offset maps to nextOffset). It doesn't document the packages-vs-manifestText precedence beyond 'one required', which the schema already handles.

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 concrete verb and resource (parses manifests, checks OSV, returns per-package max severity/CVSS and fixed versions) and enumerates the exact manifest formats handled. It also names the sibling tools it is not (osv_query_packages, osv_get_vulnerability), so an agent can route 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 and WHEN NOT sections: use this for full project audits / CI-style reports, use osv_query_packages for a few exact versions, osv_get_vulnerability for one advisory. The cost trade-off is stated as the deciding factor, which is exactly what an agent needs to choose between a paid and 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 already declare readOnly/idempotent/openWorld, so the bar is lower, yet the description adds substantial non-structured context: execution location (Cloudflare Worker, not caller's machine), data flow to api.osv.dev with nothing sent to Apify, no-storage design, one HTTPS call per ID in parallel, <2s typical with 20s per-call timeout. It also discloses partial-failure semantics (per-ID error rows, retryability) that annotations cannot express. No contradiction with any 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?

Strongly front-loaded with labeled sections (WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE) and dense with information. Minor redundancy: 'no token' and the 'designed not to store inputs/results' claim appear in both COST and BEHAVIOR, which slightly dilutes an otherwise tightly packed definition.

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-parameter, partial-failure-prone network tool the description covers everything an agent needs: routing, cost/privacy posture, error taxonomy with retry guidance, pagination mechanics, and a concrete input/output example. An output schema also exists, so return-value detail is a bonus rather than a 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% (baseline 3), but the description goes well beyond the schema: each ID yields exactly one row in input order, unknown IDs produce a non-retryable VULN_NOT_FOUND versus a retryable OSV_FETCH_FAILED, IDs are matched verbatim with no URL/prefix trimming, duplicates are fetched twice, and pagination requires resending the same ids with the returned nextOffset. These are operational semantics the schema cannot convey.

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 the fields returned (summary, details, aliases, severity vectors, fixed versions, references). It is unambiguously distinguishable from osv_query_packages and osv_audit_dependencies, which the 'WHEN NOT' line names 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 two-sided routing: 'WHEN: You have IDs (from osv_query_packages or a report)' and 'WHEN NOT: To find which vulns affect a package version (osv_query_packages) or a whole manifest (osv_audit_dependencies, paid).' Both alternatives are named with the condition that selects them, 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?

Annotations already declare readOnly/idempotent/openWorld, and the description goes well beyond them: data-flow disclosure, single HTTPS request to api.osv.dev, <2s typical / 20s timeout, retryable OSV_FETCH_FAILED error code, and the fact that results change only when OSV publishes advisories. That is exactly the extra context the lower bar for annotated tools asks for.

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 labeling makes it skimmable and front-loaded. It loses a point for redundancy between COST and BEHAVIOR, which both restate that inputs leave the client and that the Worker does not store inputs or results.

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-format detail is optional, yet the description still summarizes row shapes and error rows. Latency, failure modes, paging caveats, and the false-safe pitfall on version ranges are all covered, leaving nothing an agent needs to call this correctly.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds semantics the schema cannot express: each entry is checked independently and returns exactly one row in input order, unknown ecosystems yield per-entry INVALID_ECOSYSTEM rows without failing the batch, ranges like '^4.17.0' silently return a false 'safe', duplicates are returned twice, and meta.vulnerable_count is not page-scoped.

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 (query the OSV.dev database for exact package versions) plus the concrete return payload (vulnerable flag and advisory IDs). It explicitly names the two sibling tools it is not: osv_get_vulnerability for details and osv_audit_dependencies for manifest parsing.

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 positive trigger (quick 'is lodash 4.17.20 vulnerable?' for up to 200 packages), the explicit exclusions (manifest/lockfile parsing, severity filtering, fixed versions) and route those cases to 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?

Goes far beyond the annotations: per-document and per-finding pricing with a worked example, billing routed to the caller's Apify account via APIFY_TOKEN, 20s wait with APIFY_TIMEOUT, enumerated tool error codes, data-handling note about the hosted Worker, input caps, and the critical warning that every call re-processes and re-bills the whole input even when only offset changes. Annotations only say readOnly/idempotent/openWorld; the cost and re-billing behavior is the real risk and the description discloses it.

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 essentials with no filler. Slightly penalized because the cost-scaling point appears twice (COST and PARAMETERS) and the PARAMETERS block is a single dense run-on that is harder to scan than the rest.

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, paid, open-world tool this covers everything an agent needs: cost model, auth prerequisites, timeouts, error codes, size/count limits, paging pitfalls, and a concrete example. An output schema exists, so the brief RETURNS note 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 coverage is 100% (baseline 3), but the description adds semantics the schema cannot: texts and documentUrls are individually optional yet at least one is required (INPUT_EMPTY, not billed), both may be combined with one billed row each, mode="restore" ignores all detector flags, and unmapped placeholders pass through unchanged. The limit/offset paging warning is a genuine behavioral constraint tied to parameters.

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 the exact Actor (llm-data-guard-pii-secrets) and frames it as a superset of pii_scan_text: NER names/locations, street addresses, URL/PDF documents, and restore mode. That explicitly delineates it from the free sibling tools rather than restating the title.

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 (need NER names/addresses, URLs/PDFs, hosted pipeline) and WHEN NOT sections naming the specific alternatives (pii_scan_text, pii_redact_text, pii_restore_text, plus out-of-scope images and email deliverability). An agent can pick correctly without opening any schema.

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, closed-world, non-destructive, so the bar is lower — yet the description adds substantial context: it runs on a Cloudflare Worker, inputs leave the client, no inputs/results/token are stored, no further network call, <10 ms latency, no rate limits. This is exactly the kind of operational detail annotations cannot 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 WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE sections make it scannable and front-loaded, with no filler sentences. It is on the long side for a zero-parameter catalog call — the BEHAVIOR block is dense — which keeps 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?

Output schema exists, so return values need not be spelled out, yet the description still summarizes the return shape and explains the meaning of local:true and the redaction_styles keys. Combined with the cost and latency notes, an agent has everything needed to call this correctly and use its 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-parameter tool (baseline 4), but the description goes beyond: it states the call must use an empty object {}, that the catalog is complete and cannot be filtered, and how output values map into other tools' parameters (detector 'type' into entityTypes, redaction_styles keys into redactionStyle). That directly reduces downstream invocation errors.

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 (catalog of every PII and secret entity type) and enumerates the extra dimensions it covers: local vs paid-Actor coverage, redaction styles, and per-tool pricing. 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' (before pii_scan_text / pii_redact_text to pick entityTypes, or to explain coverage and costs) and 'WHEN NOT' (to actually scan or redact), each naming the sibling tool that should be used instead. The selection rule 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?

Goes well past the annotations: discloses determinism (identical output except hash style with per-call random salt), where computation happens (Fairquery-hosted Cloudflare Worker, inputs leave the client), the no-storage/no-forwarding guarantee, latency, and the INPUT_TOO_LARGE error. One small tension: idempotentHint=true while hash output varies between calls — the description explains this, so it is disambiguation rather than a contradiction, but it slightly undercuts the annotation's guarantee.

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), so an agent can stop reading early. It is long for a description, but nearly every line carries decision-relevant information; the COST and hosting lines are the least essential.

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?

Nine parameters, an enum, and an output schema are all accounted for: return shape, placeholder_map location, error case, and the restore path via pii_restore_text are documented. Nothing an agent needs to call this correctly on the first try 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 already 100%, yet the description still adds non-obvious semantics: placeholder numbering is stable across documents within a call but restarts per call, hash values must not be compared across calls, returnPlaceholderMap is silently ignored for mask/hash and contains ORIGINAL values that must be kept out of the prompt, and limit/offset page documents not findings.

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+output: 'Return sanitized copies of texts with every local PII/secret finding replaced', and names the exact placeholder/mask/hash forms. It is unambiguously distinguishable from pii_scan_text (findings report) and pii_guard_documents (NER/URLs/PDFs) which are called out by name.

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') plus an explicit WHEN NOT that routes to two named siblings with the conditions that select each. It also gives an internal usage decision (returnPlaceholderMap=true when you need to restore later).

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses that execution happens on a hosted Cloudflare Worker so inputs leave the client, that the Worker is designed not to store inputs/results/tokens, that no further network call occurs and the map isn't forwarded, plus latency, size caps (50 texts, 200k chars each, 10k map entries) and the INPUT_TOO_LARGE error. It also flags the sensitive nature of the output and warns not to send it 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?

Strongly front-loaded with WHAT/WHEN/WHEN NOT/COST/RETURNS labels that make it scannable despite its length. It is dense and repeats a few facts already in the schema (size limits, example map), so it is a touch longer than strictly necessary, 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?

For a nested-object, security-sensitive tool it covers everything an agent needs: source of the map, reversibility limits, replacement semantics, pagination, error case, output shape (restored_document rows with output_text, replacements, unknown_placeholders) and a worked example — even though an output schema exists.

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%, yet the description adds real semantics: placeholderMap should be passed as meta.placeholder_map unchanged, keys are matched exactly/case-sensitively with longest-key-first in a single pass so restored values are never re-replaced, and it explains what unknown_placeholders means and why an LLM-rewritten placeholder won't restore. It also clarifies that limit/offset page whole documents (default 10), which the schema only partially conveys.

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: putting original values back into texts containing placeholders like [EMAIL_1]. It explicitly names the source of the map (pii_redact_text / pii_guard_documents) and its inverse siblings (pii_redact_text, pii_scan_text), so an agent can distinguish it from every other PII tool 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 (after an LLM answered a sanitized prompt, before showing the user) and WHEN NOT (not for redacting or scanning; masked/hashed values are not reversible — only placeholder style is). It names the concrete preconditions (redactionStyle "placeholder", returnPlaceholderMap=true), 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?

Goes well past the annotations: states the tool runs on a third-party hosted Worker (Cloudflare), that inputs leave the client, that no storage or Apify token is used, that there is no further network call, and that latency is milliseconds. It also names the failure mode INPUT_TOO_LARGE. This is exactly the context readOnlyHint/idempotentHint cannot 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/BEHAVIOR/PARAMETERS/EXAMPLE) front-load the essentials and the long detector list is bullet-like rather than prose, so density is justified. It is on the long side, but nearly every clause carries non-redundant 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?

For a 7-param, 3rd-party-hosted scanning tool this covers everything an agent needs: privacy posture, paging semantics (offset = nextOffset until hasMore false, meta.documents always summarizes all documents), error handling, and a worked example. The output schema exists, yet the description adds the paging/masking context it wouldn't otherwise carry.

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%, yet the description adds genuine meaning: doc_index maps findings to 0-based array positions, the 500k cap applies to the SUM of elements (schema only shows per-item 200k/maxItems 50), entityTypes filters post-detection and silently no-matches unknown or NER-only names, allowList is whole-value case-insensitive, entropyScan only adds findings, and defaultPhoneRegion only affects national-format numbers.

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 (emails, SSNs, Luhn cards, mod-97 IBANs, JWT, cloud keys), so the scope is unambiguous. It is clearly separable from pii_redact_text and pii_guard_documents, which are named.

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/tickets/logs to an LLM or third party; auditing leaks), WHEN NOT with named alternatives (pii_redact_text for sanitized text; pii_guard_documents for NER/public URLs/PDFs), plus an explicit exclusion (no images/OCR) and cost note. 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 annotations, it discloses execution context (Fairquery-hosted Cloudflare Worker), data handling (inputs leave the client but are designed not to be stored), network behavior (no further network call), latency (instant), cost/token requirements, and rate limits. These are exactly the behavioral traits an agent needs beyond readOnly/idempotent 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?

The WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE structure is front-loaded and easy to scan. It is somewhat long and repeats the free/disclaimer point across sections, but the density is justified by the need to prevent misfires.

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 static zero-parameter tool with rich annotations and an output schema, the definition is complete: it covers purpose, invocation, output shape, disclaimer handling, and how the result relates to the sibling screening 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?

With zero parameters, the baseline is 4. The description appropriately states that it must be called with an empty object and cannot be filtered, and it adds useful cross-tool semantics by explaining that each sources[].id feeds the lists parameter of sanctions_screen_names.

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 resource (official sanctions lists catalogue) and distinguishes it explicitly from the paid sibling tool sanctions_screen_names. An agent can tell exactly what this tool does 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?

It provides explicit WHEN and WHEN NOT guidance, naming sanctions_screen_names as the alternative and stating the condition that selects it (screening a name). It also clarifies that this tool does not download lists or report freshness.

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, the description discloses paid Apify billing, token requirements, cache re-download timing, the 20 s Worker timeout, partial list failures via lists_unavailable, stable results per snapshot, and false-positive/miss limitations. It also states the Worker is designed not to store credentials/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?

Although long, the definition is front-loaded and organized under WHAT, WHEN, WHEN NOT, COST, RETURNS, BEHAVIOR, PARAMETERS, and EXAMPLE. Every section carries operational information needed to avoid incorrect or costly calls.

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, open-world screening tool with seven parameters and an output schema, the description covers invocation rules, billing, authentication, timeouts, error codes, result stability, and compliance caveats. It is complete enough for an agent to call it correctly and interpret the risks.

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 important semantics: names vs queries billing, dateOfBirth filtering behavior, country never filtering matches, entityType meaning, minScore tuning guidance, maxMatchesPerName capping only matches[], and the critical limit/offset billing caveat.

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 first line states a specific verb and resource: runs fuzzy sanctions screening for people/organisations against OFAC SDN, OFAC Consolidated, EU, UK and UN lists. It explicitly distinguishes itself from nearby tools by naming sanctions_list_sources and trust_screen_lead.

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 section gives concrete use cases (KYC/KYB onboarding, vendor checks, bulk re-screening) and instructs putting all names in one call. The WHEN NOT section names alternatives for PEP/adverse media, list coverage, and email-bearing leads, leaving little 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/idempotent/openWorld, and the description goes well beyond them: exact price model, that billing hits the caller's own Apify account, that pagination does NOT avoid re-running and re-billing, the 20s Worker-side wait with APIFY_TIMEOUT, per-check 'unavailable' degradation with meta.errors, sanctions cache staleness (up to 6h, download may exceed the wait), and that no email is actually sent. Minor tension worth noting: idempotentHint=true while the description says every call incurs new charges, though results are unchanged.

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?

Heavy but well-engineered: labeled WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE headings front-load scope before cost and mechanics, and the worked example anchors the contract. It loses a point because the PARAMETERS block retreads schema-level details (max lengths, enums, defaults) and some sentences pack multiple rules together at the cost of skimmability.

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 supplies the essentials an agent needs to interpret it: row shape (decision + reasons[] + sanctions_matches capped at 3), meta.summary as an all-leads count rather than a page count, and the partial-failure signal. Combined with the stated error codes and the paging re-bill warning, nothing material for correct invocation 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 already 100%, so a 3 would be the floor, but the description adds real decision semantics: ref uniqueness rationale (joins sanctions results back to the lead), that country only annotates and never filters while entityType does filter, that minScore defaults to 88 here versus 85 in sanctions_screen_names, and that allowFreeProviders=false can only produce 'review', never 'block'. It also states the billing consequence of supplying only one of email/name, which 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 section states a specific compound verb (runs two named checks in parallel, merges per lead) on a specific resource (batch of leads/counterparties) and even names the decision vocabulary it produces (block/review/pass). It explicitly distinguishes itself from the three nearest siblings (email_validate_deliverability, sanctions_screen_names, email_check_syntax), so an agent can place 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?

The WHEN / WHEN NOT / COST block is explicit routing guidance: it names the exact condition that selects each alternative ('Email only -> email_validate_deliverability; names only -> sanctions_screen_names') and adds a free pre-filter step. The closing rule 'Use this tool only when a lead needs both checks and one decision' gives a hard boundary rather than an implied one.

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