PostAgent

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds actionable behavioral context: it fetches a live manifest and provides specific instructions on how to interpret response fields (latestSkillVersion, latestSkillUrl, updateRequired) and what actions to avoid.

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?

Four sentences, front-loaded with the main action. Every sentence adds value: what it does, when to call, and how to act on the result. No redundant or 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?

Despite no output schema, the description provides enough context for an agent to use the tool effectively: it explains the key fields to check (latestSkillVersion, updateRequired) and the actions to take. It could be more complete by explicitly stating the return format is a manifest object, but the instructions are sufficient.

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% for the two optional parameters (installedMcpVersion, installedSkillVersion). The description does not add additional semantics beyond the schema, such as format or usage examples. 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 it fetches the live PostAgent agent manifest, specifying the verb 'Fetches' and the resource 'PostAgent agent manifest'. It distinguishes from sibling tools which are all about mail actions, not update checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to call: before using PostAgent in a new session, after reconnecting the MCP server, or when a skill may be stale. Also gives conditional instructions on handling the response (compare versions, follow update instructions, avoid paid actions if updateRequired).

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, which are consistent with the tool's behavior (creating a quote, not destructive). The description adds context: KYC requirement, x402 payment, 15-minute price lock, address validation after payment, and manual refunds. It also explains the 403 response structure. This adds value 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 well-structured: first sentence defines the tool, then KYC wall, then usage after verification, then post-payment details. It is front-loaded with core purpose. Every sentence adds value, though it could be slightly more concise without losing 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 (6 params, nested objects, no output schema), the description covers prerequisites, error handling, alternatives, workflow steps, and post-call actions. It mentions related tools and the 403 details. It does not detail the return value but that may be acceptable. The description is sufficient for an AI agent to select and invoke the tool 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?

Schema description coverage is 83%, so baseline is high. The description adds meaning by explaining the wallet must be KYC-verified, documentId can be template or letter, recipients need US addresses with mergeVariables for templates, and from address is optional with fallback. It clarifies the role of each parameter in the workflow, supplementing 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 clearly states the tool's purpose: 'Quote ONE bulk send to MANY recipients (up to 500): a single template or static document, fulfilled through PostAgent's campaign workflow.' It specifies the verb (quote), resource (bulk send campaign), and constraints (up to 500 recipients, template/static document). This distinguishes it from sibling tools like create_mail_quote (individual 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 provides explicit when-to-use and when-not-to-use guidance: 'until the wallet is verified this tool returns kyc_required (403). Do not retry the same wallet — instead either mail recipients individually with create_mail_quote, or request campaign access.' It also lists prerequisites (upload template/letter) and steps (call with recipients and payerWallet), and mentions tracking with 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?

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?

The description discloses important behavioral details beyond annotations, such as reserved address zone, page count increase for PDFs/images, literal printing of {{...}}, size limit, and free usage. Annotations already indicate non-read-only and non-destructive, so no contradiction exists.

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 relatively long but well-organized with clear front-loading of purpose and structured details. Every sentence adds value, though minor trimming could improve 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?

The description is highly complete—explains return values (documentId, page count, etc.), edge cases (multiple sources, blank page prepending), references external resource for format details, and covers cost and idempotency considerations. No output schema exists, so description fulfills that role.

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 100% description coverage, but the description adds crucial context: exactly one of content/contentBase64/url must be provided, format inference rules, and the 30 MB limit. This significantly enhances parameter understanding beyond schema alone.

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

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

The description clearly states the tool uploads a finished, ready-to-mail document to PDF and distinguishes it from create_template for personalized content. It specifies that the document must be identical for all recipients, making the purpose very specific and clear.

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 (final, identical content) and when to use create_template instead (when content varies via merge fields). It also notes that the same document ID can be reused for multiple recipients and that exactly one source must be 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?

The description adds extensive context beyond the annotations: it notes the tool verifies addresses, locks a price for 15 minutes, does not charge or mail, and details the response structure (fulfillment and design blocks). It does not contradict any annotation; readOnlyHint=false and destructiveHint=false are consistent with creating a quote without side effects.

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 action, but it is relatively lengthy due to detailed explanations of the workflow and response fields. While every sentence is informative, it could be slightly more concise without losing clarity.

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

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

Given the complexity (5 parameters, nested objects, no output schema), the description covers all necessary aspects: it explains the return value structure (fulfillment, design, paymentUrl), the workflow (verify, lock, do not charge), and important caveats (warnings, confirmation). It is comprehensive 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?

Schema coverage is 80%, and the schema already contains detailed parameter descriptions (e.g., options.color, extraService, mergeVariables). The description adds value by explaining how parameters like documentId and mergeVariables relate to the quoting process, but does not significantly enhance individual 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 verifies addresses and locks a 15-minute USDC price for a documentId, and explicitly says it does not charge or mail. It distinguishes itself from the sibling tool submit_paid_mail_job by explaining that this is the quoting step before payment and mailing.

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 explains when to use this tool (to get a locked price before mailing), how to proceed (show user info and get confirmation), and when not to proceed (if warnings present without re-confirmation). It also outlines two payment paths, with a preferred method and a fallback.

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 explains file storage behavior ('stored VERBATIM — no page-size normalization and no reserved address zone'), size requirements (e.g., 4x6 cards need 4.25"x6.25" artwork), and delivery constraint (address block covers part of back). It also specifies return value ('documentId with kind "postcard_art"') and format rejection ('Text-based formats are rejected'). This adds far 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?

Description is front-loaded with main purpose and structured in paragraphs, but it is somewhat verbose with technical details (bleed sizes). Every sentence adds value, but could be condensed slightly without losing clarity.

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

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

Given no output schema, description describes return value and usage flow. It covers key aspects: format, size, delivery concerns, and complementary tools. Missing: error handling or file size limits, but overall sufficient for the task.

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?

Description adds meaning beyond schema by requiring exactly one of contentBase64 or url, mentioning single-page constraint, and noting format is inferred. It also clarifies that format enum ('pdf' or 'image') and that text-based formats are invalid. With 75% schema coverage, this is a useful supplement.

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 'Upload ONE side of a postcard (front or back) as single-page PDF, PNG, or JPEG artwork.' It distinguishes this tool from siblings like create_postcard_quote by specifying that this is for uploading artwork only, and front/back must be uploaded separately before 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?

Description provides explicit context: 'Upload front and back separately, then quote with create_postcard_quote.' and notes 'Free; no payment required.' It implies when not to use (e.g., for text-based documents), but lacks an explicit 'do not use for' statement.

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

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

Annotations indicate it is not read-only and not destructive. The description adds behavioral details: address verification, 15-minute price lock, service-level downgrade possibility with warnings, and instructions to surface warnings verbatim. However, it does not explain failure modes for address verification.

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

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

The description is detailed but front-loaded with the core purpose. Every sentence adds value, though slightly verbose. It is well-structured with logical flow from purpose to constraints to payment instructions.

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 main aspects: address verification, price lock, payment, and warnings. It informs the agent to show specific fields to the user. However, it lacks details on error handling (e.g., invalid addresses) and does not fully describe the output structure (e.g., no schema for return type).

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

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

Schema coverage is high (80%), but the description adds significant meaning: explains front/back document IDs, address format differences for US vs. international, size options, service level vs. mailClass, and the role of 'to.country' for international. This goes 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 clearly states the tool's function: verifying addresses and locking a 15-minute USDC price for mailing a postcard using two postcard_art documents. It distinguishes itself from siblings like create_letter and create_mail_quote by focusing on postcards.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides good usage context, specifying when to use (for postcard quotes), constraints (international only on 4x6), and references to payment workflow similar to letters. It implicitly differentiates from siblings but does not explicitly 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 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 claims polling 'advances the campaign' and 'releases the campaign for mailing', implying a side effect, but annotations declare readOnlyHint=true and destructiveHint=false. This is an annotation contradiction, significantly undermining trust.

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

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

The description is three sentences, front-loads the main return value, and efficiently provides essential 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 simplicity (one parameter) and the description detailing return fields, it is mostly complete. However, the annotation contradiction creates confusion about the tool's side effects, and there is 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?

There is only one parameter (campaignId) with 100% schema coverage. The description adds minor context about finding the campaign ID, but does not provide additional semantics 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 explicitly states the tool returns campaign validation/sending progress including status, recipient counts, and a failures report URL. It distinguishes itself from sibling tools like get_mail_job_status by focusing on campaign-specific metrics and the side effect of advancing the campaign.

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 advances the campaign, indicating when to use it (to check progress and trigger release). It also instructs where to find the campaignId (via jobStatusUrl after payment), providing helpful 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 already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds specific return data types, enriching behavioral context without 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?

Single sentence, front-loaded with action verb, 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?

For a simple tool with one parameter and no output schema, the description sufficiently explains what is returned and for what input.

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 has 0% description coverage; description indirectly explains jobId as identifying a previously created job, but does not directly detail the parameter.

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, carrier/tracking/proof data, and tracking events for a previously created job, distinguishing it from sibling tools like 'get_campaign_status'.

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?

Implies use after job creation but lacks explicit when-to-use vs alternatives or 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?

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.