PostAgent

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds context on conditional behavior (what to do based on version comparison and updateRequired flag), which goes beyond the annotations and aligns with them. No contradiction.

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?

Two sentences: first states core action, second provides critical conditional logic. No redundant words; all sentences earn their 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?

Without an output schema, the description compensates by explaining how to use the response fields (latestSkillVersion, latestSkillUrl, updateRequired). However, it does not explicitly list the return fields, relying on implied knowledge of the manifest structure. Still fairly complete for the purpose.

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 are fully described in the schema (100% coverage). The description adds context on why to provide these versions (to check against latest), enhancing semantic understanding beyond schema alone.

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 fetches the PostAgent manifest and is used to check for updates. It distinguishes itself from sibling tools which are all about mail/postcard operations, not PostAgent updates.

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 provides when to call (before new session, after reconnect, when skill may be stale) and conditional actions based on response fields (if older, update; if updateRequired true, avoid paid actions). No ambiguity or missing guidance.

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?

Beyond annotations, description discloses KYC checks returning kyc_required (403), price lock for 15 minutes, x402-only payment, manual refunds for failed recipients, and tracking via get_campaign_status. No contradictions 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?

Well-structured with front-loaded purpose, followed by preconditions, usage steps, and post-payment behavior. Slightly verbose but each sentence adds information.

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 covers preconditions, workflow, edge cases (KYC failure, address validation, refunds), and follow-up via get_campaign_status. Highly complete for a tool of this complexity.

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%, so base is 3. Description adds meaning: explains documentId refers to template or letter, recipients require US addresses, mergeVariables for templates, and payerWallet must be KYC-verified. This adds value 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 states the tool provides a locked price quote for bulk mail campaigns (up to 500 recipients, single template/static document, x402 payment). It distinguishes from sibling tools like create_mail_quote by specifying campaign workflow vs individual mails.

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 (for campaigns) vs not (individual mails via create_mail_quote), preconditions (KYC-verified wallet), and provides alternatives (contact URL). It also outlines the workflow: create template/letter first, then call this tool.

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?

Adds extensive behavioral details beyond annotations: normalization to PDF, how the reserved address zone adds pages, that {{...}} is literal, and the effect on page count and cost. 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?

Relatively long but well-structured, with clear sections for overall purpose, input options, merge field clarification, and address zone behavior. Every sentence adds value, though slightly verbose.

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?

Comprehensive for a tool without output schema: details returned fields (documentId, page count, byte size, source format), address zone behavior per format, and cost implications. No gaps identified.

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 descriptions cover all 5 parameters (100% coverage). Description adds extra context: provides exactly one source, max size 30 MB, output page size US Letter, and clarifies format inference. Marginally exceeds baseline.

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, ready-to-mail document to PDF, and distinguishes it from create_template for mail merge. The verb 'upload' and resource 'document' are specific and the scope is clearly defined.

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 advises when to use this tool ('content is final and IDENTICAL for every recipient') and when to use the sibling create_template ('content must vary per recipient via {{fields}}'). Also notes it is free and no payment required.

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?

Beyond annotations (readOnlyHint=false, etc.), the description adds significant context: quote lock duration, x402 payment URL, fulfillment warnings, and design block inspection. It discloses that no charge or mail occurs, aligning with non-destructive 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 well-structured: core function first, then payment mechanism, warnings, and design. It is fairly long but justified by the tool's complexity. Could be slightly more concise, but no wasted sentences.

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 no output schema, the description covers response structure (fulfillment block, design block, paymentUrl), warnings, and user confirmation workflow. It is complete enough for an agent to safely invoke the 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 80%, so baseline is 3. The description adds some high-level context (e.g., documentId from create_letter/template, mergeVariables for templates) but does not significantly enhance individual parameter meaning beyond the schemas's own 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 it 'Verifies the recipient and sender US addresses and locks a 15-minute USDC price for a documentId' and explicitly says 'Does not charge or mail anything.' This distinguishes it from sibling tools like submit_paid_mail_job and create_campaign_quote.

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 provides explicit when-to-use guidance, mentioning that submit_paid_mail_job is a fallback for certain clients, and instructs to show warnings and get user confirmation before paying. It also implies not to use this tool for actual mailing.

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 write operation; description adds that file is stored verbatim with no normalization, explains bleed requirements, and notes the return of documentId. 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 detailed but front-loaded with purpose. It could be slightly more concise, but each 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?

Given no output schema, the description explains the return value, the process of uploading both sides, card size specs, and cost. It is complete for the tool's purpose.

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 high (75%), and description adds that artwork must be provided exactly one way (contentBase64 or url) and format is inferred when omitted, but otherwise overlaps with 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?

The description clearly states the tool uploads one side of a postcard (front or back) as single-page PDF, PNG, or JPEG artwork, distinguishing it from siblings like create_postcard_quote.

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 explains to upload front and back separately then quote with create_postcard_quote, and warns about text-based rejection. It provides good context but lacks explicit when-not-to-use or alternative tools.

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 this is not read-only, not idempotent, not destructive. The description adds critical behavioral context: it verifies addresses, locks a price for 15 minutes, and explains payment mechanisms. It also warns about potential service level downgrades with a specific warning message the agent must surface. No contradictions 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 a single, moderately long paragraph. It front-loads the main purpose and then provides detailed constraints and guidance. While it is thorough, it could be broken into shorter sentences or bullet points for easier parsing, but overall it is efficient with no wasted words.

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 (nested objects, 5 parameters, no output schema), the description is remarkably complete. It explains what the response contains (recipient, sender, size, design, price, warnings), the payment flow, and how to handle service level downgrades. It also mentions fallback payment methods. The description fully compensates for the missing 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?

Schema coverage is high (80%), and the description adds meaningful context beyond the schema: front/back are postcard_art documents, size defaults to 4x6, international requires country set and 4x6 only, mailClass is deprecated in favor of serviceLevel. The description clarifies the sender must be a US address and that for US recipients, country is omitted.

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: 'Verifies the recipient and sender addresses and locks a 15-minute USDC price for mailing a postcard.' It specifies the resource (postcard), actions (verify and lock price), and distinguishes from siblings by mentioning postcard-specific details like front/back 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 good usage guidance: prerequisites (two postcard_art documents), constraints (sizes, international only 4x6), and payment flow (x402 or MPP). It also mentions service level warnings and user confirmation before payment. However, it does not explicitly state when not to use this tool versus other quote tools like create_mail_quote, leaving some ambiguity.

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?

Annotations already declare read-only and idempotent. The description adds critical behavior: polling advances the campaign (releases for mailing). Also discloses failures report URL. 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?

Three sentences, each with a distinct purpose: return values, behavioral note, source of parameter. No fluff, 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?

For a simple read tool with one parameter, the description covers the return values, behavioral side-effect, and parameter source. Lacks explicit output schema, but enumeration suffices.

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?

Input schema covers 100% of parameter description (campaignId). Description adds minor context on where to find the id (quote's job status), but does not add meaning 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?

Clearly states the tool returns campaign status with specific status values (validating, sent, partial, failed) and recipient counts. Distinguishes from sibling get_mail_job_status by specifying campaign context.

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 context for when to use: after payment, for checking campaign progress, with polling behavior noted. Lacks explicit exclusions or comparison to alternatives, but the context is clear.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the exact data returned (status, carrier, tracking, proof, events), which is not in 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 a single, front-loaded sentence with no wasted words. It clearly conveys the tool's output without unnecessary detail.

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 low complexity (1 parameter, no nested objects, no output schema), the description covers the purpose and return content adequately. However, it does not document the jobId parameter or provide any return format details, leaving some gaps for an AI agent.

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?

There is one parameter (jobId) with no description in the schema (0% coverage). The description does not explain the parameter or its format. Although the name is self-explanatory, the lack of any parameter documentation with low schema coverage warrants a low score.

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 uses specific verbs ('returns') and resources ('normalized status, carrier/tracking/proof data, and tracking events') and clearly states it is for a previously created job, distinguishing it from sibling tools that create or pay for jobs.

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 job creation but provides no explicit guidance on when to use this tool vs alternatives like get_campaign_status. The sibling list shows many creation tools, but the distinction from other retrieval tools is not explicitly stated.

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.