PostAgent — Print and Mail

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

Beyond annotations, the description reveals critical behaviors: price locked for 15 minutes, payment via x402 only, KYC requirement resulting in a 403 error, post-payment validation of recipient addresses, manual refund processing for failed recipients. These details are essential for an AI agent to understand side effects and constraints.

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 with a brief upfront summary, a highlighted important section (KYC wall), and detailed usage instructions. It is slightly lengthy due to the necessary complexity but every sentence adds value. Minor redundancy (repeating 'IMPORTANT — KYC WALL') does not detract significantly.

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 aspects including prerequisite workflow, error states, and tracking, it lacks an explicit description of the return value (e.g., quote ID, total price, expiry timestamp). Since there is no output schema, the description should indicate what the tool returns to allow the agent to process the response correctly.

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?

The description adds significant meaning beyond the input schema: it explains that documentId can be a template or finished letter, that recipients require US addresses and mergeVariables for templates, and that payerWallet must be KYC-verified. It also clarifies the from address is optional if the server has a fallback. With 83% schema coverage, the description enriches rather than repeats the 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 identifies the tool as creating a locked price quote for a bulk mail campaign (up to 500 recipients) using a template or static document. It distinguishes from sibling tools like create_mail_quote (individual mail) and pay_mail_with_shared_payment_token (payment) by specifying the bulk campaign context and the pricing mechanism (per-letter unit price x recipient count).

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 guidance on when to use this tool (after creating a template or letter) and when not to (due to KYC unavailability), and even names an alternative tool (create_mail_quote) and advises waiting for KYC onboarding. It also outlines the prerequisites (upload template/letter) and post-usage actions (track via get_campaign_status).

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 discloses key behavioral traits beyond annotations: payment is asynchronous, letter created via webhook, tracking via statusUrl, error if Stripe not enabled, no charge until human completes. These details are not present in the annotations (readOnlyHint=false, openWorldHint=true, etc.) and provide essential transparency for an agent using this tool.

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 with the main purpose. Each sentence serves a purpose: explaining the output, usage guidelines, asynchronous flow, tracking, errors, and alternatives. Despite length, it is efficient and contains 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 tool's complexity (human payment, asynchronous, webhook, tracking), the description covers all necessary aspects: what it does, how to use, expected behavior, error conditions, and tracking mechanism. No output schema exists, but the description explicitly states return values and what the statusUrl returns, 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?

Schema coverage is 50% (only webhookUrl has a description). The description adds that quoteId must be a locked quote, which is useful but not a full description of the parameter. It does not elaborate on webhookUrl beyond what the schema provides. While it adds some meaning, it doesn't fully compensate for the missing 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 creates a Stripe-hosted Checkout page for a locked quote and returns checkoutUrl and statusUrl. It distinguishes from siblings by explicitly labeling it as a last-resort payment rail for human credit card payments, contrasting with autonomous agent payment methods like x402 or MPP.

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 usage guidance: 'Use this as the LAST-RESORT payment rail, when the payer is a human paying by credit card' and 'Prefer x402 (or MPP, if available) for autonomous agent payment.' It also explains the asynchronous flow and how to track payment, giving clear when-to-use and when-not-to-use criteria.

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?

Description discloses key behaviors beyond annotations: exact bytes printed, maximum upload size, reserved address zone behavior (pushing content or prepending blank page for PDF/images), literal treatment of {{...}}, and page count increase. Annotations provide little behavioral info; description compensates richly. 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?

Well-structured with front-loaded purpose and detailed sections, but slightly verbose. Could be tightened without losing meaning. Still, every sentence serves a purpose and the structure aids comprehension.

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 (source alternatives, format handling, address zone, page count return), the description covers all essential aspects: return values (documentId, page count, bytes, format), error conditions, and cost (free). No output schema, but description adequately explains 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?

Schema coverage is 100%, but description adds significant value: explains mutual exclusivity of content/url/contentBase64, details format inference, and ties parameters to the address zone and page count effects. This goes well 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 starts by stating 'Upload and normalize a FINISHED, ready-to-mail document to PDF.' It clearly specifies the tool's purpose and distinguishes it from sibling tool create_template, which handles variable content via merge fields.

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?

Explicit guidance on when to use this tool ('when the content is final and IDENTICAL for every recipient') and when to use create_template instead. Also provides clear instructions on providing exactly one document source, error conditions, and highlights that no payment is needed.

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 address verification, 15-minute price lock, non-charging/non-mailing nature, and the return of a paymentUrl. Adds context about x402 payment and fallback, going beyond annotations (readOnlyHint, openWorldHint, etc.).

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 is efficient and front-loaded with purpose and constraints. Could be slightly more structured (e.g., separate sections for behavior vs workflow), but no unnecessary content.

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 core behavior, return value (paymentUrl), workflow, and parameter specifics. No output schema, but description explains what is returned. Sufficient for a quoting tool with moderate 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?

With 80% schema coverage, baseline is 3. Description adds value by explaining documentId origin, options details (certified vs extraService), and mergeVariables behavior. Does not repeat schema but 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 title and description clearly state the tool creates a locked price quote (not a charge or mailing), specifies the verb (verifies, locks), resource (mail quote for a documentId), and distinguishes from siblings like 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?

Explicitly states it does not charge or mail, provides preferred payment method (x402 via paymentUrl) and fallback (submit_paid_mail_job), and instructs agent to show details and get user confirmation before paying.

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 discloses important behavioral details beyond annotations: file stored verbatim, no page-size normalization, no reserved address zone, responsibility for correct trim size with bleed, and that Lob prints recipient address block over part of back. Annotations only provide readOnlyHint, etc., so this adds substantial value.

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, front-loading the tool's purpose and key constraints. It is somewhat verbose with detailed bleed sizes, but each sentence adds value. Could be slightly more concise, but overall efficient.

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 4 parameters with no nested objects or output schema, the description covers file types, size requirements, upload method, return value (documentId), and integration with create_postcard_quote. It is complete for the tool's 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?

With 75% schema coverage, the description adds meaning beyond the schema: specifies that exactly one of contentBase64 or url should be used, format can be inferred when omitted, and text-based formats are rejected. The schema already describes parameters, but the description clarifies usage constraints.

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. It distinguishes from sibling tools like create_postcard_quote, which is used after uploading both sides.

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: upload front and back separately, then use create_postcard_quote. It doesn't explicitly state when not to use this tool or list alternatives, but the guidance is sufficient for most cases.

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 show readOnlyHint=false and openWorldHint=true, but the description adds valuable behavioral context: it verifies addresses, locks a 15-minute price, and describes the payment mechanism. 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 well-structured and front-loaded with the key action. Although it is longer than the calibration high example, each sentence provides necessary guidance. It could be slightly more concise but is not 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?

With no output schema, the description should explicitly define what the tool returns. It implies the output includes a paymentUrl and price but does not formally list all return fields, leaving some ambiguity for the 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?

Schema coverage is 80%, so baseline is 3. The description adds meaning by explaining that front/back documents are postcard art, that postcards print in full color, and that international recipients are limited to 4x6, which is not fully detailed in the 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 it creates a quote for printing and mailing a postcard, specifying that it uses two postcard_art documents and includes size options. It distinguishes from letter quotes by mentioning postcard-specific constraints like full color and size options, but does not explicitly name sibling tools like create_mail_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 provides clear usage conditions: only 4x6 for international, sender must be US, and payment flow guidance. It tells when to use this tool for postcard quotes but lacks explicit when-not instructions compared to other sibling 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?

Discloses key behaviors beyond annotations: rejection if no {{field}}, error for multiple or no sources, reserved address zone, server fetching behavior, maximum upload size, and return values. 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?

Well-structured with clear sections and front-loaded key decision points. Though slightly verbose, every sentence adds value and 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?

Thorough coverage of input constraints, output fields, error conditions, and special behaviors (address zone). References external resource for deeper detail, making it complete for agent usage.

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?

Adding value beyond 100% schema coverage by explaining mutual exclusivity of sources, default format inference, and usage rules. Schema already covers each parameter well, so the description enhances rather than compensates.

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: uploading reusable templates with {{field}} placeholders for mail merge. It explicitly distinguishes from sibling tool create_letter by specifying when to use each.

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 when-to-use and when-not-to-use guidance, naming the alternative (create_letter) and explaining that content without merge fields should use that tool. Also covers input source constraints and reuse instructions.

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: it reveals that polling advances the campaign by releasing it for mailing. This is a side effect not implied by the readOnlyHint annotation, and the description fully discloses it.

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, concise, and front-loaded with the return value. It includes necessary detail without redundancy, but could be slightly more structured for rapid scanning.

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 sufficiently describes the return fields (status, counts, failures URL) and the side effect of polling. It also provides context on where to find the campaign ID, making it complete for a status polling 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 100% with description for campaignId. The tool description adds practical guidance on how to obtain the campaign ID (from jobStatusUrl after payment), which enhances understanding beyond the 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 returns campaign validation/sending progress, including status, recipient counts, and a failures report URL. It uniquely identifies its purpose among sibling tools, which focus on creation, checkout, payment, and address verification.

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 indicates polling is used to check status and advances the campaign, and it references finding the campaign ID from the job status URL after payment. This implies when to use it, but does not explicitly state when not to use or list 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by specifying the exact return items (status, provider letter id, tracking events) and the context 'previously created job', which is beyond what annotations provide.

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 concise sentence with no extraneous information, efficiently conveying the tool's 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 tool's simplicity and rich annotations, the description provides sufficient detail about return values and preconditions. It lacks error handling info but is adequate for a read-only retrieval 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 0% so description bears full burden. It adds context that jobId refers to a previously created job, providing meaning beyond the schema, but does not explain format or how to obtain the id.

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 normalized status, provider letter id, and tracking events for a previously created job, using a specific verb and resource. It effectively distinguishes from sibling tools which are creation-oriented.

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 creating a job but does not explicitly state when to use or not use this tool, nor does it mention alternatives. Given siblings are mostly creation, it's minimally adequate.

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?

Description reinforces annotations (destructiveHint=true) by stating 'CHARGES MONEY AND IS IRREVERSIBLE'. Adds details on flow (authorize, print, capture), error conditions (MPP not enabled), and constraints (US-only, $0.50 min cards). 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?

Front-loaded with purpose and then detailed guidance. Every sentence adds value (minting instructions, constraints, alternatives, return format). Slightly long but necessary for 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?

Completely covers all aspects: input parameters, prerequisite steps (minting SPT, user confirmation), constraints, error scenarios, and return behavior (inline job, no polling). No gaps given the presence of annotations.

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 context beyond 75% schema coverage: explains how to mint sharedPaymentToken, scope to stripeProfileId, and that userConfirmed requires explicit approval. The quoteId and webhookUrl are schema-covered, but the description provides integration context.

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 pays a locked quote autonomously by card/wallet using a Stripe Shared Payment Token. It specifies the action ('pay'), the method ('autonomous, no-browser FIAT'), and distinguishes from the x402 alternative.

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: when agent can mint SPT and wants FIAT payment without browser. Provides clear exclusion ('prefer x402 first') and prerequisite: only after user confirms from 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds context: 'No payment is taken' and 'Probes the canonical per-quote pay URL', which are useful 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?

Three sentences, front-loaded with key info. Every sentence adds value. No redundancy or wordiness.

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 simple input (1 param, no output schema) and annotations covering safety, the description fully explains purpose, flow, and alternatives.

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%, but the single required parameter (quoteId) is implied by 'a locked quote'. No explicit parameter description, but context is sufficient for a single param.

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?

Description clearly states the tool returns the x402 payment challenge for a locked quote, using specific verb 'Returns' and resource. It distinguishes from sibling tools by mentioning inspection or detached-signature flow versus in-band handshake.

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 use cases: inspection or detached-signature flow. Notes the preferred alternative (in-band handshake) and sibling submit_paid_mail_job. Clarifies 'No payment is taken at this step.'

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 destructiveHint=true, and the description reinforces that the tool is irreversible and charges the agent. It adds context about the fallback nature and prerequisite steps. However, it could be more specific about response behavior or error cases, but overall it is transparent.

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 with the key fallback context. It contains necessary details without being overly verbose. A minor point: the irreversibility warning is in caps, which adds emphasis but slightly reduces conciseness.

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 should explain what happens after calling (e.g., returns a job ID) and mention post-call actions (e.g., checking status). It provides good prerequisite context but lacks details on the response or next steps, making it somewhat incomplete.

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 75% (3 of 4 parameters have descriptions). The description adds context for the tool's flow but does not significantly enhance the meaning of individual parameters beyond what the schema provides. Baseline score of 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 the tool's purpose as a fallback for submitting a signed x402 payment to create and mail a letter. It distinguishes from sibling tools by explicitly contrasting with the primary payment path and referencing related tools like create_mail_quote and prepare_mail_payment.

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 usage guidance: use this tool only if the wallet client cannot pay in-band via the primary path. It also lists preconditions: user confirmation of details and obtaining the signed payment header. This clearly tells the agent when and when not to use it.

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?

Disclosures go beyond annotations by describing the x402 payment flow, cost, address requirements per country, and the fact that it returns standardized addresses. Annotations indicate idempotent and non-destructive, which aligns with description.

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 a clear first sentence, two distinct paragraphs for flow and requirements, and a note about alternatives. 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 (paid, two-step, international) and no output schema, the description covers return value, payment mechanism, conditions for use, and alternatives, making it fully informative for correct invocation.

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 coverage, the description adds value by explaining the payment flow (omit/include paymentSignature) and address requirements (US vs international), which the schema alone does not provide.

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 is a standalone paid address verification tool that checks deliverability and returns standardized form, distinguishing it from sibling tools like create_mail_quote which includes free verification as part of quoting.

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 explains when to use (standalone verification) and when not to (for mailing, use create_mail_quote), and provides detailed steps for the two-step payment flow, including preferred in-band payment method.

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