Verify many addresses, emails, or phone numbers in one call

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool checks a local cache before calling Melissa and is subject to the same per-session call budget as the single-record tools. This adds meaningful context beyond a simple 'verify' action, though it does not mention return format or error behavior.

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 two sentences, tightly packed with actionable guidance. The primary usage directive is front-loaded, and the constraints (cache, budget, mutual exclusivity) follow logically. No filler or redundancy; every sentence earns 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 the tool's complexity (batch verification, three mutually exclusive parameters, no annotations, no output schema), the description covers the essential context: when to use it, the mutual exclusivity rule, and key behavioral constraints. However, it omits the return structure, any batch size limits beyond the budget, and error semantics, so it is not fully complete.

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 0%, so the description must compensate for parameter documentation. It clarifies that exactly one of the three arrays must be provided, which is a crucial semantic not encoded in the schema. However, it does not describe the structure of address objects or the format of email/phone strings, leaving much to the schema. This partially compensates for the coverage gap.

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 clearly states the tool verifies addresses, emails, or phone numbers in batch, and explicitly contrasts it with the single-record siblings by saying 'Use this instead of calling verify_postal_address, verify_email, or verify_phone in a loop.' This distinguishes it from related tools and conveys a specific verb-resource pair.

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 an explicit directive: 'Use this instead of calling ... in a loop,' which tells the agent exactly when to choose this tool over the single-record ones. It also states the cardinality constraint, 'Provide exactly one of addresses, emails, or phoneNumbers,' covering a key usage rule that the schema does not enforce.

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