PostAgent

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

Beyond annotations (which indicate a write operation), the description reveals the KYC wall returning 403, 15-minute price lock, x402 payment requirement, post-payment address validation, and manual refunds. No contradiction with annotations.

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 lengthy but well-organized: core action first, then critical KYC warning in block, then usage details. Front-loaded and clear, though some redundancy could be trimmed.

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?

While the description covers many behavioral aspects and mentions tracking via get_campaign_status, it omits details about the successful response format (e.g., total price, quote ID, expiry timestamp). Given no output schema, this is 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 83%, and the description adds meaning: documentId can be template or letter, recipients require US addresses and mergeVariables for templates, payerWallet must be KYC-verified. This complements the schema definitions well.

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 creates a locked price quote for a bulk campaign (up to 500 recipients), using a template or static document via the campaign pipeline. It distinguishes from sibling tools like create_mail_quote by specifying the bulk nature and 15-minute lock.

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 guidance: use this tool only when KYC is available; currently KYC is not ready, so do not retry and instead use create_mail_quote individually. It also outlines prerequisites (upload template/letter first) and the process after payment.

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 indicate it is not read-only, not idempotent, not destructive, and open-world. The description adds that payment is asynchronous, the letter is created by Stripe webhook, no charge until human completes, and returns an error if Stripe Checkout is not enabled. This exceeds annotation coverage.

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 comprehensive but somewhat long. It is front-loaded with the core purpose and return values, and each sentence adds meaningful information. Could be slightly tightened, but overall well-structured.

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?

Despite lacking an output schema, the description thoroughly explains the return values (checkoutUrl, statusUrl) and how to use the statusUrl to track job creation. Given the complexity of the async payment flow and webhook, the description is 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 coverage is 50%; the description adds context for quoteId (must be a locked quote) and explains webhookUrl as optional for receiving status updates. This adds value beyond the schema, though the schema could also be improved.

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 it creates a Stripe-hosted checkout page for a locked quote and returns checkoutUrl and statusUrl. It distinguishes from sibling payment tools by specifying it is for credit card payments by humans, contrasting with x402/MPP for autonomous agents.

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?

Explicitly says to use as a last-resort payment rail when the payer is a human paying by credit card, and to prefer x402 or MPP for autonomous agent payment. Provides clear guidance on when to use and alternatives.

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?

Describes upload size limit, page size, literal handling of {{...}}, reserved address zone behavior (page pushing or prepending), and page count increase. Adds context beyond annotations.

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?

Structured in clear sections but verbose. Every sentence adds value, yet could be tightened. Appropriate 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 input constraints, format behavior, output fields (documentId, page count, byte size, source format), and edge cases like address zone. No output schema, so description compensates well.

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. Description adds value by explaining each source option's format applicability and the error condition for none or multiple sources.

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 uploads and normalizes a finished, identical letter to PDF. It contrasts with create_template for personalized mail merge, distinguishing it from siblings.

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?

Explicitly says when to use (final identical content) and when to use create_template (varied content via merge fields). Also specifies to provide exactly one source, else error.

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 indicate `readOnlyHint: false` and `openWorldHint: true`, and the description adds behavioral context: it verifies addresses (side effect), locks a price for 15 minutes (time-bound state), does not charge or mail, and returns a paymentUrl. This goes beyond the annotations to explain the non-read-only, non-destructive behavior and the time-bound 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 front-loaded with the core purpose and clearly structured. It briefly explains the action, what it does not do, the return value, two payment paths, and user confirmation. Though somewhat wordy, it remains clear and each sentence serves a purpose.

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 complexity (5 parameters, nested objects, no output schema), the description provides sufficient context: it names the return value (`paymentUrl`), explains the two subsequent paths, and gives user confirmation instructions. It lacks details on error handling or the full response structure, but overall it is complete enough for an agent to use.

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 80%, with the schema itself providing detailed descriptions for most parameters (e.g., address fields, documentId, options). The description does not add significant extra meaning beyond what the schema already offers, aside from implicitly connecting address verification to the `to` and `from` parameters. Baseline 3 is appropriate.

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 it verifies sender/recipient addresses and locks a 15-minute USDC price for a documentId. It explicitly says what it does and does not do (no charge or mail), and distinguishes the tool from the sibling `submit_paid_mail_job` by noting the preferred payment flow versus fallback.

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 description provides guidance on when to use this tool (as a prerequisite to mailing) and explains the preferred payment method (wallet x402) versus the fallback `submit_paid_mail_job`. It also instructs to show and get explicit user confirmation before paying. However, it does not explicitly compare this to other quote tools like `create_postcard_quote` or `create_campaign_quote`.

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?

Discloses verbatim storage, no normalization, trim size with bleed requirements, clearance on back for address, free pricing, and return value with documentId; annotations confirm read/write 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?

Well-structured with front-loaded action and detailed requirements, but slightly verbose; every sentence adds value.

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 upload mechanics, format constraints, sizing requirements, next steps, and payment info; sufficient for complex tool despite no output schema.

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?

Adds critical context beyond schema: exact one-way specification (contentBase64 or url), format inference, rejection of text formats, and base64 encoding details.

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 defines the tool as uploading one side of postcard art, distinguishes from sibling tool create_postcard_quote, and specifies accepted formats and purpose.

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 guidance on separate uploads for front/back and subsequent quoting with create_postcard_quote, but lacks explicit when-not-to-use alternatives for similar tools like create_letter.

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?

The description adds significant behavioral context beyond annotations: the 15-minute price lock, address verification, and the requirement for user confirmation before paying. Annotations indicate write operations (readOnlyHint=false) and non-idempotent behavior, which aligns with the description's mention of locking a price and payment 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 a single well-structured paragraph that front-loads the core purpose and then efficiently covers prerequisites, options, international rules, payment, and user confirmation. Every sentence adds necessary information without redundancy.

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 (5 parameters, nested objects, no output schema), the description is thorough. It explains the prerequisite steps (upload art via sibling tool), the options (size, mail class), international constraints, and the payment process. It implies the return of a paymentUrl. Slight lack of detail on exactly what is returned could be improved, but overall it is 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?

With 80% schema coverage, the description adds meaning beyond the schema: it explains that frontDocumentId and backDocumentId must be for postcard_art, that the back artwork gets the address block printed over it, and that postcards always print in full color. It also clarifies the international country parameter and the sender fallback.

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: verifying addresses and locking a 15-minute USDC price for mailing a postcard, built from two postcard_art documents. It specifies the verb ('locks a price'), the resource (postcard mailing), and differentiates from siblings like create_letter and create_mail_quote by mentioning the art documents and size options.

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 description provides explicit context on when to use (after uploading art via create_postcard_art) and how to pay (x402, MPP/checkout fallbacks). It includes international restrictions (only 4x6) and the need for explicit user confirmation. It doesn't explicitly mention alternatives like create_mail_quote, but the sibling list is provided separately.

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?

Discloses that uploads without placeholders are rejected, output is US Letter size, server reserves top 3 inches for address, returns specific fields (documentId, kind, mergeFields, estimatedPageCount). Does not contradict annotations; adds context beyond them.

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?

Well-structured and front-loaded with key purpose. While fairly long, all sections add value; minor redundancy but overall efficient for the 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?

Despite no output schema, description explains return values and the overall workflow (template reuse, per-recipient quoting). Covers reserved address zone, page size, and payment status (free). Very thorough.

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%, but description adds critical nuances: exactly one source required, error if none or more than one, format inference, maximum upload size, and base64 encoding specifics.

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?

Title and description clearly state this tool is for uploading reusable mail-merge templates with {field} placeholders. It explicitly contrasts with create_letter for identical content, and distinguishes itself from siblings.

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?

Directly states when to use (content varies per recipient) and when not (use create_letter for identical content). Provides detailed instructions on providing exactly one source, mentions maximum size, and explains reuse with create_mail_quote.

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?

The description reveals a critical side effect: polling advances the campaign and releases it for mailing. This contradicts the readOnlyHint=true annotation, which implies no state change. The description adds valuable behavioral context but the contradiction reduces trustworthiness.

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 concise: two sentences, front-loaded with return types and characteristics. Every sentence adds essential information, with no redundancy.

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 simple tool (1 param, no output schema), the description fully covers purpose, parameter source, behavioral effect, and return value structure. The annotations provide additional clues, making it 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?

With 100% schema coverage, the description adds value by telling where to find the campaign ID (from jobStatusUrl after payment), which is beyond the schema's basic description. This helps the agent source the parameter correctly.

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 verb 'returns' and specifies the resource as a campaign's validation/sending progress, including specific fields like status, recipient counts, and failures report URL. It distinguishes itself from sibling tools by focusing on campaign-level progress and advancing the campaign, unlike other mail status tools.

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 description provides clear context for when to use: after payment, to check progress and to release the campaign. It mentions finding the campaign ID via job status URL. However, it does not explicitly exclude alternative tools or state when not to use it, which is a minor gap.

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 readOnlyHint, idempotentHint, and destructiveHint as false, indicating safe, repeatable behavior. The description adds value by specifying what is returned (normalized status, provider letter id, tracking events), providing behavioral context beyond the annotations. No contradictions.

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 one sentence (12 words) with no redundancy. It is front-loaded with the key action 'Returns' and specifies the exact outputs concisely. Every word contributes to clarity.

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 is simple (one parameter, no output schema), the description adequately covers the return values (status, provider letter id, tracking events). It does not detail status values or error conditions, but for a status-check tool, this level of detail is sufficient. The annotations cover safety aspects, so the description complements well.

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 0% schema description coverage, the description should compensate for the single parameter 'jobId'. It does not explicitly mention the parameter, but the context 'previously created job' implies the job ID is needed. The parameter name 'jobId' is self-explanatory, but adding guidance on how to obtain it would improve semantics.

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 it returns normalized status, provider letter id, and tracking events for a previously created job. The verb 'Returns' and resource 'mail job status' are specific. It distinguishes from sibling tools like 'get_campaign_status' by mentioning 'mail job', though it could explicitly differentiate from related status tools.

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 description implies usage after a job is created ('previously created job'), but does not explicitly state when to use this tool versus alternatives (e.g., get_campaign_status for campaigns) or provide exclusions. Context signals show siblings are primarily creation tools, so use is implied but not clarified.

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?

Disclosed that the tool charges money irreversibly, prints the letter, and captures payment. This goes beyond the annotations (destructiveHint) by explaining the flow and noting that a job returns inline.

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?

Description is comprehensive but somewhat lengthy. However, every sentence adds value and it is well-structured with front-loaded purpose. Could be slightly more concise, but overall well-done.

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?

Despite lack of output schema, the description covers behavior, return type (inline job), preconditions, external steps for minting SPT, and constraints. Highly complete for a payment 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?

Adds significant meaning beyond schema: for sharedPaymentToken, explains minting process and required scoping; for userConfirmed, reiterates need for explicit human approval. Schema coverage is high, but description enriches understanding.

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: autonomous FIAT payment for a locked quote using a Stripe Shared Payment Token. It also distinguishes from the x402 alternative, making it unambiguous.

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?

Explicitly states when to use (when agent can mint SPT and wants fiat alternative) and when not (prefer x402 first). Also lists precondition: only call after user confirmation of quote details.

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 indicate readOnlyHint true, idempotentHint true, and destructiveHint false. The description adds context that no payment is taken at this step and that the tool probes a specific URL, which is helpful beyond annotations.

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 sentences with no redundant information. The first sentence states the core purpose, followed by clarifying details, making it efficient and easy to scan.

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 simplicity (single parameter, no output schema) and rich annotations, the description covers the essential workflow. However, it does not describe the return value format of the challenge, which is a minor 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 0%, so the description must compensate. It explains that quoteId identifies a locked quote and that the tool probes the per-quote pay URL, giving enough context to understand the parameter's role despite lacking formal parameter 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 clearly states the tool returns an x402 PAYMENT-REQUIRED challenge for a locked quote. It specifies the action (returns challenge) and resource (per-quote pay URL), distinguishing it from siblings like pay_mail_with_shared_payment_token and submit_paid_mail_job.

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 description explicitly notes the preferred payment method (standard in-band handshake) and that this tool is for inspection or detached-signature flow, providing clear when-to-use and when-not-to-use guidance with alternatives.

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 indicate destructiveHint=true, but the description adds crucial context: 'THIS IS IRREVERSIBLE' and 'Charges the agent in USDC on Base mainnet'. Also details the required preconditions (user confirmation, signed header), which go beyond annotations.

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?

Single paragraph with bolded warnings and clear logical flow: purpose, primary alternative, fallback usage, irreversible warning, and prerequisite steps. Every sentence is necessary and well-placed.

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?

Despite lacking an output schema, the description covers all necessary context: trigger conditions, prerequisites, irreversible nature, cost, and references to related tools. An AI agent can correctly determine when and how to invoke this 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?

Schema coverage is 75% with descriptions for 3 of 4 parameters. The description adds workflow context by specifying that 'userConfirmed' must be set only after explicit human approval and that 'paymentSignature' comes from 'prepare_mail_payment'. This ties parameters to the overall process, adding value beyond 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?

Clear verb-resource pair 'submit a signed x402 payment' and outcome 'create and mail the letter'. The description distinguishes this as a fallback from the primary in-band payment path, setting it apart from siblings like 'pay_mail_with_shared_payment_token'.

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?

Explicitly states the primary/recommended path and specifies 'use this tool only if your wallet client cannot do that'. Provides clear when-to-use and when-not-to-use guidance, and references 'prepare_mail_payment' as prerequisite.

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 indicate idempotent and non-destructive. The description adds significant behavioral context: the paid nature via x402, the two-step verification flow, and the standardization process (CASS, ZIP+4). No contradictions.

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 well-structured and front-loaded: first sentence states purpose and cost, then details flow, then regional notes, and finally a note about alternatives. Every sentence adds value without redundancy.

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 payment, flow, regional requirements, and alternative usage. Without an output schema, the description mentions 'returns the standardized form' but does not detail the response structure. This is a minor gap for a complex 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?

Schema coverage is 75% (6/8 parameters with descriptions). The description adds crucial meaning beyond the schema: explains the role of paymentSignature in the two-step flow, clarifies country usage ('US' omitted vs. other codes), and specifies address requirements (line1+city+state or zip for US, line1+country for international).

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: standalone paid address verification that checks deliverability and returns standardized form. It distinguishes itself from mailing tools by noting that create_mail_quote already includes verification, so this tool is for independent address checks.

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?

Explicitly describes when to use (standalone verification) and when not to use (when mailing, use create_mail_quote). Explains the two-step flow with payment, and gives regional requirements for US vs. international addresses.

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