PostAgent — Print and Mail

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

Annotations already indicate readOnly and idempotent. Description adds context on safe repeated calling and how to interpret response for updates, enhancing transparency.

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 with high information density. No extraneous 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?

Provides complete guidance for usage and response interpretation. No gaps given simplicity of 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 covers both parameters fully (100%). Description doesn't add meaning beyond schema, but does not detract.

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 it fetches the live PostAgent agent manifest to check for updates. Distinguishes from siblings by specific domain.

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 call: before using PostAgent in a new session, after reconnecting, or when skill may be stale. Also provides conditional actions based on response fields.

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 context beyond annotations: KYC requirement, 15-minute lock, x402 payment, address validation after payment, refund process. 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?

Front-loaded with key purpose and constraints. Could be slightly more concise, but well-organized with clear sections.

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?

Lacks output schema and doesn't describe successful return value (e.g., quote ID). Adequate for usage but incomplete for expected response.

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 meaning beyond schema: explains documentId source, recipient mergeVariables for templates, payerWallet KYC requirement. Schema coverage is high (83%), so baseline is met.

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 gets a locked price quote for a bulk mail campaign. It distinguishes from siblings like create_mail_quote for individual sends and references related 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?

Explicitly describes when to use (bulk send, after template/letter) and when not (if wallet not KYC'd, use individual mailing). Includes alternative action and contact URL.

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?

Describes critical behaviors: literal treatment of {{...}}, reserved address zone with page handling details for different formats, potential extra page/cost implications, and exact bytes printed. Annotations add less context.

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?

Although lengthy, each sentence provides necessary detail. Structured logically: purpose, usage, technical constraints. Could be slightly more concise but justified 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?

Thoroughly covers input constraints, output (documentId, page count, etc.), free usage, error conditions, and refers to additional resource for format details. No output schema but description compensates.

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 parameter descriptions, but the description adds value by explaining the 'exactly one source' constraint, maximum upload size, output page size, and format inference.

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 uploads and normalizes a finished, ready-to-mail document to PDF, specifies identical content for all recipients, and distinguishes from create_template for variable content.

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 not (use create_template for varied content). Provides detailed instructions on providing exactly one source and mentions free of charge.

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 declare readOnlyHint=false and destructiveHint=false, meaning the tool is not read-only and not destructive. The description adds that it does not charge or mail, locks a 15-minute price, and returns a paymentUrl. It also explains the fulfillment block and warnings behavior, which goes 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 lengthy but every sentence adds value; it is front-loaded with the main purpose and then provides necessary details. It could be slightly more concise, but the structure is logical and informative.

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, the description thoroughly explains the response structure (fulfillment, design, paymentUrl) and provides critical safety steps (confirm warnings, inspect design, user confirmation). It covers all necessary context for correct 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?

Schema coverage is 80%, with most parameters already well-described in the schema. The description adds context about mergeVariables for templates and the need to inspect fulfillment.warnings, but does not significantly enhance parameter 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's purpose: it verifies addresses, locks a 15-minute USDC price, and does not charge or mail. It distinguishes from sibling tools like submit_paid_mail_job and pay_mail_with_shared_payment_token, and specifies it returns a paymentUrl for x402 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: prefer x402 payment via wallet, use submit_paid_mail_job as fallback, and require user confirmation before paying, especially if warnings exist. It also advises inspecting design and preview 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 critical behaviors beyond annotations: file is stored verbatim with no page normalization or reserved address zone, required trim sizes with bleed, that the delivery method prints over the back, and that text-based formats are rejected. This provides necessary context beyond the annotation hints (readOnlyHint false, 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?

The description is comprehensive yet concise, front-loading the core action and then providing necessary details (trim sizes, bleed, address zone) in a structured manner. 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?

Given the tool has 4 parameters, no output schema, and moderate complexity, the description covers the return value (documentId with kind 'postcard_art'), the overall workflow (upload then quote), and detailed specifications for artwork dimensions and address area. It is sufficiently complete for an AI agent to use 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?

With 75% schema description coverage, the description adds value by clarifying that contentBase64 must be base64-encoded pdf/png/jpeg, url must be publicly reachable, and format can be inferred. The filename parameter lacks a schema description but the tool description does not elaborate, so the score is slightly above baseline due to useful extra 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 it uploads one side of a postcard (front or back) as single-page PDF/PNG/JPEG artwork. It differentiates from sibling tools by mentioning that uploading front and back separately is followed by create_postcard_quote, making its role distinct.

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 gives explicit usage instructions: upload one side at a time, use exactly one of contentBase64 or url, then quote with create_postcard_quote. It also notes that the tool is free. However, it could be more explicit about when not to use it or alternatives, but it's still 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?

The description discloses multiple behavioral traits beyond annotations: 15-minute price lock, address verification, size restrictions, payment flow, service-level downgrade warnings, and the need for explicit user confirmation. This adds significant value beyond the readOnlyHint and openWorldHint 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 front-loaded with the core purpose and efficiently structures details. Every sentence adds value, though some repetition (e.g., payment flow) could be streamlined. Still well-organized 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?

Given the tool's complexity (nested objects, no output schema), the description covers all essential aspects: address verification, size options, international rules, payment mechanisms, service level downgrade warnings, and user confirmation instructions. It enables correct agent 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?

Schema coverage is 80%, and the description adds critical meaning: distinguishes front/back document IDs, explains default size, constrains international to 4x6, and clarifies that sender must be US. This compensates well for any schema gaps.

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 a specific verb-resource combination: it verifies addresses and locks a 15-minute USDC price for mailing a postcard. It clearly distinguishes from sibling tools like create_letter by focusing on postcards and requiring two postcard_art documents.

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 the tool (after creating postcard_art) and includes constraints (e.g., international only on 4x6). It does not explicitly name alternatives, but the specificity makes usage 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?

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?

Description states polling advances the campaign, contradicting annotations readOnlyHint=true and idempotentHint=true. This is a serious inconsistency as the tool modifies state despite being marked read-only.

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, no fluff. The first sentence packs multiple details but remains readable. Could slightly improve structure by splitting status and polling effects.

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?

Describes return fields (status, counts, failures URL) despite no output schema. Lacks details on error conditions or status interpretation, but sufficient for basic 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?

Single parameter with schema description. Description adds value by explaining where to find the campaign ID (on quote's job status). Schema coverage is 100%, so baseline 3, plus extra context for +1.

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 it returns campaign validation/sending progress with specific statuses and counts. Distinguishes from sibling get_mail_job_status by referencing where to find campaign ID.

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 polling behavior (advances campaign) and where to get campaign ID. Implicitly suggests use for tracking campaign progress, but does not explicitly list when not to use.

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 non-destructive. The description adds valuable context about what data is returned (normalized status, carrier/tracking/proof data, tracking events) beyond the annotations. No missing behavioral traits are critical given the safety profile.

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 redundant words. It efficiently communicates the tool's purpose and return data.

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-only query with no output schema, the description covers the return data components. It could specify response format or example statuses, but the listed data types provide adequate context.

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% and the description does not elaborate on the jobId parameter beyond implying it identifies a previous job. The parameter name is self-explanatory, but with zero schema documentation, the description should add format or source guidance.

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 that the tool returns normalized status and related data for a previously created mail job. The verb 'returns' and the resource 'job' are specific, and the tool name implies the function. Among sibling tools, it is distinct as the only status retrieval tool for mail 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 by referencing 'previously created job', but it does not explicitly state when to use this tool versus alternatives like get_campaign_status. No when-not-to-use guidance is provided.

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.