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

Despite annotations already marking readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral context: a flat USDC fee is charged, the two-step payment flow with challenge and signature, the standardized output, and the advantage of in-band payment. It does not contradict any annotation and fully discloses the tool's side effects and flow.

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 three focused paragraphs: purpose/pricing, detailed flow, and a note about an alternative. Every sentence carries essential information; no filler. It is front-loaded with the core purpose and quickly differentiates from siblings, making it easy for an agent to process.

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 tool is complex (8 params, payment flow, no output schema), but the description fully covers all critical context: it explains the two-step payment protocol, fee implications, required vs. optional fields, US/international behavior, and the relationship to sibling tools. Given no output schema, it still leaves the agent with a clear mental model of how the tool operates and what it returns.

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 75% schema description coverage, the description still adds critical meaning beyond the schema: it explains the paymentSignature flow (omit to get challenge, include to verify), the country field's role in selecting US vs. international verification, and exact address requirements (line1 + city/state/zip for US, line1 + country for international). This enriches the agent's understanding of how parameters interact.

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's purpose: 'Checks whether an address is deliverable and returns the standardized form' with specific details (CASS, ZIP+4, international matching). It also explicitly distinguishes itself from sibling tools, noting that create_mail_quote already verifies addresses for free when mailing.

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 context: standalone verification, no mail is sent, paid via x402. It also gives a clear 'when NOT to use' by stating that within PostAgent you should use create_mail_quote instead. The two-step payment flow and address requirements for US vs. international are clearly explained, giving the agent all necessary decision guidance.

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