PostAgent

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

Beyond annotations, describes price lock (15 min), payment method (x402), KYC requirement, address validation after payment, refund process, and tracking via get_campaign_status.

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 summary, warning, and usage details. Slightly long but each section is informative and earns its 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?

Covers current limitation, future usage, post-payment behavior, and references sibling tools. Adequately complete for a complex tool with nested parameters and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds context to parameters (e.g., documentId type, payerWallet KYC requirement, recipients with mergeVariables for templates). Schema coverage is 83%, so description adds value without duplication.

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 generates a locked price quote for a bulk mail campaign to multiple recipients. It distinguishes from sibling tools like create_mail_quote by specifying it's for bulk sends up to 500 recipients.

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 current unavailability due to missing KYC, advises using create_mail_quote instead, and outlines prerequisites (template/letter) and workflow once KYC exists.

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's a write operation (readOnlyHint=false) and not destructive. Description elaborates on asynchronous behavior, automatic letter creation via webhook, tracking via statusUrl, and error condition if Stripe not enabled. It also notes no charge occurs until human completes the page.

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 informative but somewhat lengthy. However, every sentence adds value, and the key information is front-loaded. It could be slightly more concise but remains clear.

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 (asynchronous payment, webhook, user interaction), the description covers all necessary aspects: what it does, how to use, tracking mechanism, fallback, and error handling. Without an output schema, it still explains the return fields adequately.

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%, with only quoteId having a minimal description. The description does not add meaning beyond the schema for the parameters; it mentions the 'locked quote' requirement but does not elaborate on the webhookUrl parameter. The description could provide more context about parameter usage.

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 creates a Stripe-hosted checkout page for a locked quote, returning checkoutUrl and statusUrl. Distinguishes itself from siblings by specifying it's for credit card payments by humans, contrasting with autonomous 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?

Explicitly says 'Use this as the LAST-RESORT payment rail' and specifies when to use (human paying by credit card) and when not to (prefer x402 or MPP for autonomous). Also provides instructions to hand the URL to the user.

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 provide minimal behavioral info (e.g., readOnlyHint=false). The description compensates fully by detailing the write operation, address zone reservation (auto-pushing content or prepending blank page), literal handling of {{...}}, and return fields (documentId, page count, etc.). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose. Each sentence adds essential information. Despite being lengthy, it is concise relative to the complexity. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, no output schema, important behavioral quirks), the description covers all key aspects: usage, parameter constraints, address zone behavior, and return value hints. It lacks a structured list of return fields but mentions them in context, making it complete enough for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds value by explaining mutual exclusivity of content sources, maximum upload size, and output page size. It reinforces proper usage without repeating schema details. Slightly better than baseline 3.

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: 'Upload and normalize a FINISHED, ready-to-mail document to PDF.' It explicitly distinguishes itself from create_template by emphasizing identical content vs. personalized mail merge via {{fields}}. The verb 'Upload' and resource 'finished letter' are specific.

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: use this when content is final and identical for all recipients, and use create_template for variable content. It also warns about providing exactly one source (content, contentBase64, or url), maximum upload size, output page size, and the reserved address zone behavior. It leaves no ambiguity about when or how to use 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?

The description adds behavioral context beyond annotations: it confirms no charge or mail action, specifies the 15-minute lock period, and explains the return of a paymentUrl for x402 payment. Annotations include openWorldHint=true, and the description clarifies that the tool only verifies and locks a price without further side effects. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: 6 sentences covering the key action, non-charge nature, payment method, fallback tool, and user confirmation requirement. Front-loaded with the primary purpose. No extraneous 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?

Given the complexity (5 parameters, nested objects, mergeVariables), the description covers all essential aspects: address verification, price lock, no charge, paymentUrl, preferred payment method, fallback, and user confirmation. It addresses the openWorldHint annotation by clarifying side effects. Completeness is high for effective selection and 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 description coverage is 80%, so baseline is 3. The description adds value by explaining the documentId parameter comes from create_letter or create_template, and elaborates on mergeVariables: 'Values for a template document's {{merge fields}}... The server substitutes these into the template and renders this recipient's personalized PDF'. This goes beyond the schema's description, so a 4 is warranted.

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 'Verifies the recipient and sender US addresses and locks a 15-minute USDC price for a documentId.' It specifies the action (locks a quote) and resource (documentId), and the title further clarifies 'Get a locked price quote for a print-and-mail job'. This distinguishes it from sibling tools like create_letter (which creates the document) and submit_paid_mail_job (which executes the mail).

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 when to use this tool: to get a quote before paying. It states 'Does not charge or mail anything.' It provides explicit guidance on the next steps: 'the preferred way to actually mail the letter is for the agent's wallet to perform an in-band x402 payment' and mentions that 'The MCP submit_paid_mail_job tool is a fallback'. It also instructs to 'show the recipient, sender, options, and price to the user and get explicit confirmation before paying', which guides the workflow.

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: file stored verbatim, no normalization, no reserved address zone, exact bleed dimensions, address block placement on back, return type (documentId). 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 and front-loaded with main action, though slightly verbose. Every sentence adds value, but could be tightened without losing meaning.

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?

Complete for a file upload tool: covers input formats, size requirements, behavioral constraints, and return value (documentId). No output schema, but description sufficiently explains the output.

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 75% of parameters; description adds crucial context: exclusivity of contentBase64/url, rejection of text formats, and filename max length implication. Could provide more detail on filename usage.

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 artwork as single-page PDF/PNG/JPEG, and distinguishes it from sibling tools like create_postcard_quote by explaining the upload-quote workflow.

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 (upload front or back), when not to use (text formats, must use exactly one of contentBase64 or url), and provides an alternative (use create_postcard_quote after uploading).

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 goes beyond minimal annotations (readOnlyHint false, etc.) to explain key behaviors: address verification, 15-minute price lock, full-color printing, and that the recipient address block is printed over part of the back. It also mentions payment flow similar to letters. This provides rich behavioral context for the agent.

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 paragraph but is well-structured and front-loaded with the core action (verifying addresses and locking price). It covers essential details without extraneous information. It could be slightly more structured (e.g., bullet points), but it is concise and 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 the complexity (nested objects, 5 params, no output schema), the description is largely complete. It explains required inputs, special rules (international only 4x6), and payment process. It doesn't describe the response shape (no output schema), but the description implies a paymentUrl and price. Missing error handling info, but overall adequate.

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 description coverage, the baseline is 3. The description adds significant value by clarifying the roles of frontDocumentId and backDocumentId, explaining size options (including default), and describing international address requirements. It doesn't fully describe all parameters (e.g., from address details are mostly in schema), but the added context justifies a 4.

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: getting a locked price quote for printing and mailing a postcard. It specifies the verb 'quotes' and resource 'postcard', and distinguishes from sibling tools like create_letter or create_mail_quote by detailing postcard-specific requirements (front/back art, sizes, international constraints).

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 guidelines: it tells when to use (after uploading postcard_art), what inputs are needed (front/back document IDs, addresses), and notes that international is only for 4x6. It also instructs the agent to show details to the user before payment, giving clear when-to-use and when-not-to-use 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?

Annotations are minimal (only readOnlyHint false, etc.), but the description extensively discloses behavioral traits: template must be text-based with {{field}}, rejection if no fields, exactly one source, max size, output page size, reserved address zone, and that it's free. 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?

Description is long but structured into clear paragraphs with front-loaded key points. However, it could be more concise; some details like 'output page size is US Letter' might be secondary. Still, organization helps readability.

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 adequately covers return fields (documentId, kind, mergeFields, estimatedPageCount). Also covers constraints, error conditions, usage with sibling tools, and free status. Comprehensive 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?

Schema covers all 5 parameters with descriptions (100% coverage). Description adds crucial constraint of exactly one source and explains the rejection rule for missing {{field}} and clarifies source options. However, there is a potential inconsistency between contentBase64 description (binary) and text-based requirement, slightly reducing clarity.

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 uploads a reusable template for mail merge with placeholders. Distinguishes from create_letter for identical content and create_mail_quote for usage.

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 tells when to use (when content varies per recipient) and when not (use create_letter for identical content). Also explains how to use with create_mail_quote per recipient.

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 states that polling 'advances the campaign (it releases the campaign for mailing)', implying a side effect, which contradicts the readOnlyHint annotation (true). This is a serious inconsistency, thus score 1 per guidelines.

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, front-loaded with essential information, and contains no redundant words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity (one parameter, no output schema), the description covers return fields and usage context adequately. The contradiction detracts slightly, but overall completeness is good.

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% (single parameter campaignId fully described). The description does not add any extra meaning beyond what the schema provides, so baseline score of 3 applies.

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 status including validation state, recipient counts, and a failures report URL. It distinguishes itself from sibling tools like get_mail_job_status by specifying the campaign-specific scope.

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 that polling is used to track campaign progress and that it advances the campaign. It also provides context on where to find the campaign ID. However, it does not explicitly state when not to use this tool or mention 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description adds minimal behavioral context. It mentions the returned data shape (normalized status, provider letter id, tracking events) but no additional traits like rate limits or authentication needs.

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 that efficiently conveys the tool's purpose and output. No unnecessary 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?

The description covers the tool's return values but lacks details on response structure, error handling, or any preconditions (e.g., job must exist). For a simple read tool with annotations, it is adequate but not 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?

The description does not explain the `jobId` parameter beyond what the schema provides (string, required). With 0% schema description coverage, the description should compensate but fails to describe how to obtain a jobId or any 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 action ('Returns') and the specific resource ('normalized status, provider letter id, and tracking events for a previously created job'). It distinguishes itself from sibling tools, which are mostly creation tools or campaign-specific.

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 use for checking status of a job but gives no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though the tool's read-only nature is clear from annotations.

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 the operation charges money and is irreversible, matching destructiveHint=true. Describes server flow: authorizes SPT, prints letter, then captures. Adds context about US-only limitation and minimum card amount.

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 not overly verbose. Front-loaded with purpose and usage, then detailed behavioral info. Could be slightly more concise, but structure is good.

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?

No output schema, but description explains job returns inline (no polling). Also covers prerequisites, constraints (US-only, card min $0.50), and references related tools. Complete for this complex 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?

Schema coverage is 75% (webhookUrl not described but has schema description). Description adds meaning for sharedPaymentToken (scoped to seller's Stripe profile, minted by agent) and userConfirmed (must be after human approval). Adds 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?

Description clearly states it is for autonomous FIAT payment for a locked quote using a Stripe SPT, and distinguishes from x402 alternative. Verb 'pay' and resource 'mail with shared payment token' are specific.

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: prefer x402 if agent has USDC-on-Base wallet, else use this as fiat alternative. Also specifies only call after user has confirmed details from create_mail_quote. Provides clear guidance on minting SPT as agent's responsibility.

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, idempotentHint=true, and destructiveHint=false. The description adds crucial behavioral context: 'No payment is taken at this step' and 'Probes the canonical per-quote pay URL'. 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 two sentences with no wasted words. First sentence states core function, second provides usage guidance. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains what is returned (the challenge) and the two flows where this tool is used. It also mentions the URL pattern. For a tool of this complexity, it is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage, but the description implies that quoteId refers to a locked quote. While it doesn't elaborate on format or constraints, the single parameter is adequately contextualized for an agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Returns' and the specific resource ('x402 PAYMENT-REQUIRED challenge for a locked quote'). It distinguishes from siblings by explaining when this tool is appropriate (inspection or detached-signature flow) versus the standard payment flow.

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 says when to use this tool ('for inspection or for the detached-signature flow') and when not to use it ('The preferred way to actually pay is ... standard x402 in-band handshake'). It also mentions it's for locked quotes, providing clear context.

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 and readOnlyHint=false; the description adds that it charges USDC on Base mainnet and is irreversible, providing needed context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, front-loaded with purpose, then usage guidance, then a clear warning. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, prerequisites, and irreversibility. References sibling tools. Lacks success indication (e.g., returns job ID or status), but adequate given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%; description adds meaning by explaining paymentSignature from prepare_mail_payment, userConfirmed as user approval flag, and webhookUrl as optional. However, quoteId lacks additional detail.

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 fallback for x402 wallets to submit payment and create a physical letter, distinguishing it from the primary payment path and sibling tools 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 when to use this fallback ('use this tool only if your wallet client cannot do that'), plus the required prerequisites (user confirmation and signed payment header).

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 paid nature, idempotent payment flow, and that no mail is sent. Adds context beyond annotations: cost, x402 protocol, two-step challenge/response. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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 paragraphs for purpose, payment flow, and address requirements. Each sentence adds value, though slightly verbose. Front-loaded with core 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?

Covers return value (standardized form), payment flow, and address requirements. Lacks mention of error handling or undeliverable cases, but overall adequate for a verification tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant meaning beyond schema: explains address field combinations (city+state vs zip for US; line1+country for international). Clarifies paymentSignature's role. With 75% schema coverage, description fills gaps and provides validation rules.

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 verifies address deliverability and returns standardized form. Distinguishes itself from sibling mailing tools by explicitly noting that create_mail_quote already verifies addresses for free, so this tool is standalone.

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: standalone address verification, not needed when using PostAgent's create_mail_quote. Explains two-step payment flow, US vs international address requirements, and how to use paymentSignature.

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