score_leads

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

Discloses side effects beyond the annotations: it is a background operation that returns a count immediately, consumes AI credits, may bill again if rescoring, and requires an API key. The annotation readOnlyHint:false is consistent, and the description transparently explains the non-read-only, asynchronous, and potentially costly nature.

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 thorough but well-structured, using clear sentences and sections (purpose, usage, background, credits, cap). Each sentence provides essential info without redundancy, making it appropriately concise for the 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?

Covers all necessary context: mode selection, background behavior, return value (count), how to get results later, credit consumption, API key requirement, and the 200-id cap. It leaves no major gaps for a tool with these side effects and asynchronous behavior.

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?

Both parameters (jobId and leadIds) are described in the schema and further elaborated in the description: jobId scores every unscored lead in a search job, leadIds scores specific leads. The description adds critical details like the mutual exclusivity, the 200-id cap, and the rescoring/billing consequences, enriching the schema's meaning.

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?

Clearly states the tool queues AI qualification scoring for leads, distinguishing between scoring all unscored leads in a search job (jobId) or a specific set of leads (leadIds). The verb 'queue' and resource 'leads' are specific, and the two modes are explicitly contrasted.

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 usage instructions: pass jobId OR leadIds (not both), explains the background execution and that results are retrieved later via list_leads, warns about credit consumption and rescoring implications, and mentions the 200-id cap and API key requirement. This fully guides when and how to use the tool.

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