Screen leads: email deliverability + sanctions (paid)

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

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

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

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

The description is front-loaded with labeled sections (WHAT, WHEN, WHEN NOT, COST, RETURNS, BEHAVIOR, PARAMETERS, EXAMPLE) that scan quickly. It is dense but every sentence carries actionable information; the main detractor is that the PARAMETERS and COST sections are somewhat terse and interleaved, requiring the reader to parse a dense block to extract billing edge cases. It's not bloated, but the heavy density prevents a 5.

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

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

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

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

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

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

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

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

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

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

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

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

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