PostAgent

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

Annotations already mark it as read-only, idempotent, non-destructive. Description adds valuable behavioral context: it fetches a manifest and prescribes actions based on version comparison. 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?

Three concise sentences with front-loaded purpose. Each sentence adds essential information: what it does, when to use, and what to do with results. 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?

For a simple fetch tool with no output schema, the description is complete: it explains the purpose, usage context, and expected behavior. No gaps given 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 coverage is 100% with clear descriptions for both optional parameters. The description does not add additional meaning beyond the schema, so 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?

Description clearly states the tool fetches the live PostAgent agent manifest. It identifies the specific resource and action, and the purpose is distinct from all sibling tools (mail/campaign creation).

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 call: before using PostAgent in a new session, after reconnecting MCP server, or when skill may be stale. Also provides conditional instructions based on the result (e.g., if updateRequired is true, avoid paid/irreversible actions).

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds critical context: price lock period, KYC requirement, x402 payment, address validation post-payment, manual refunds for failed addresses, and tracking via get_campaign_status. 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: starts with core purpose, then important note (KYC), then usage steps. Each sentence adds value, though slightly lengthy. Front-loaded with key 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?

Covers prerequisites, constraints, payment method, and post-payment steps. No output schema exists, but description implies a quote is returned. Mentions tracking via sibling tool. Could explicitly state return format, but overall complete given complexity.

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

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

Schema coverage is 83% (high). Description adds value by explaining relationships (documentId from create_template/letter), payerWallet KYC requirement, and address constraints. It clarifies optionality of 'from' address and use of mergeVariables for templates. Almost fully compensates for the uncovered 17%.

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 obtains a locked price quote for a bulk mail campaign (up to 500 recipients). It distinguishes from siblings like create_mail_quote (individual mail) and create_postcard_quote, and specifies key details: single template/static document, price locked 15 minutes, x402 payment only.

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 (KYC-verified wallet, after creating template/letter) and when not (if not verified, use alternative tools or request access). Provides clear steps and names alternatives (create_mail_quote, request campaign access).

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

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

Beyond annotations (which indicate non-read, open-world), description details asynchronous behavior, webhook-driven letter creation, and tracking via statusUrl. 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 about 100 words, well-structured: purpose, usage guidance, tracking instructions, preference, error condition. 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 no output schema, description covers return values (checkoutUrl, statusUrl) and tracking. Lacks detail on preconditions like quote must be locked, but overall sufficient for a payment tool with two parameters.

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% (webhookUrl has description). Description adds context for quoteId (must be locked) and webhookUrl (optional, for status updates). Provides useful meaning beyond schema, though not exhaustive for both parameters.

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

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

The description clearly states it creates a Stripe-hosted Checkout page for a locked quote, returning checkoutUrl and statusUrl. The verb 'create' and resource 'Stripe-hosted Checkout page for a quote' are specific, and it distinguishes from siblings like pay_mail_with_shared_payment_token which handle different payment methods.

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, when the payer is a human paying by credit card' and 'Prefer x402 (or MPP, if available) for autonomous agent payment.' Provides clear when-to-use and alternatives.

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

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

The description discloses numerous behavioral traits beyond annotations, including that {{...}} is printed literally, the reserved address zone and its impact on page count and cost, that pdf/image inputs get a blank first page prepended, and that the server fetches from URL. It also notes that content is printed exactly as provided.

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

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

The description is well-structured with clear sections and front-loaded purpose. It is not excessively verbose, though it is detailed; every sentence adds value. Given the complexity, it achieves good 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?

Despite no output schema, the description covers return values (documentId, page count, byte size, source format) and all essential aspects: input methods, format handling, address reservation, page count implications, and cost considerations. It is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning by explaining that exactly one source must be provided (error otherwise), the maximum upload size (30 MB), and the behavior of the reserved address zone for different formats. This exceeds the baseline of 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: uploading and normalizing a finished, ready-to-mail document. It explicitly distinguishes itself from the sibling tool 'create_template' by specifying that content must be identical for all recipients, not variable via mail merge.

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 versus 'create_template', quoting/paying once per recipient, and how to provide the document (exactly one of content, contentBase64, or url). It also mentions free usage and maximum upload size.

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 that the tool is non-destructive (does not charge or mail), locks a price for 15 minutes, and verifies addresses. It details the fulfillment block with warnings and design constraints. Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description aligns with these 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?

The description is concisely written with front-loaded key information (verifies addresses, locks price, does not charge). Every sentence adds necessary context without redundancy, making it efficient for an AI agent to parse.

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, nested objects, no output schema), the description is comprehensive. It explains return values (fulfillment, design, paymentUrl), warnings to inspect, and the payment process. This covers what an agent needs to use 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?

The input schema has 80% description coverage, so parameters are well-documented. The description adds value by explaining the overall flow (e.g., documentId from create_letter/create_template, mergeVariables for templates) and how options affect price, going beyond the schema's individual 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 that the tool verifies addresses and locks a 15-minute USDC price for a documentId without charging or mailing. It distinguishes itself from siblings like create_campaign_quote and create_letter by focusing on the quoting action.

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 (to get a locked quote before mailing) and provides alternatives: preferred x402 payment and fallback submit_paid_mail_job. It also instructs to check warnings and get user confirmation before paying, which guides appropriate usage.

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 present, but the description adds significant context beyond them: file is stored VERBATIM, no normalization, no reserved address zone, responsible for bleed, and recipient address block behavior. It also notes free usage and return type.

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 thorough but slightly long due to listing sizes. It is well-structured, front-loading the core purpose, and each sentence provides necessary detail. Could be tightened slightly.

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 lack of output schema, the description adequately explains the return value (documentId with kind 'postcard_art') and usage flow. It also covers cost and next steps, making it complete for agent execution.

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%, and the description clarifies the mutual exclusivity of contentBase64 and url, which is not explicit in schema. However, it does not add detail to the filename parameter beyond its existence.

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 'Upload' and the resource 'postcard artwork (front or back)' with specific file types. It distinguishes itself from siblings by outlining the subsequent quote step with create_postcard_quote.

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

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

Provides explicit when-to-use instructions, including the requirement to upload front and back separately. It also gives explicit how-to-use guidance (EXACTLY ONE WAY: contentBase64 or url) and warns about format rejection.

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 behaviors such as address verification, a 15-minute price lock, service level downgrade possibility, and payment flow similarity to letters. Annotations indicate it is not read-only, not idempotent, and not destructive, which aligns with the described behavior. No contradictions.

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

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

The description is a single paragraph covering all necessary aspects without excessive verbosity. It is front-loaded with the core action and flows logically through constraints, payment, and warnings. Minor redundancy could be trimmed, but overall efficient.

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

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

Given the tool's complexity (5 parameters, nested objects, no output schema), the description covers the essential behaviors, constraints, and user instructions. It explains return values (price, paymentUrl, warnings) and required user confirmation, though a bit more detail on the output structure would improve completeness.

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

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

With 80% schema coverage, the description adds meaningful context: it explains the role of front/backDocumentId, size options, international address requirements (to.country and size limitation), and that sender must be US. It also notes that serviceLevel may be downgraded, adding value 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: to get a locked price quote for printing and mailing a postcard, with specific details on address verification, price lock duration, and size options. It distinguishes from sibling tools like create_mail_quote by focusing on postcards and requiring two 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 explicit guidance on when to use the tool (for postcards with front/back art) and constraints (international only 4x6, sender must be US). It also advises on user confirmation and warning surfacing, but does not explicitly state when not to use it versus 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 indicate it's a write operation (readOnlyHint=false). The description adds many behavioral details: rejection if no fields, return values (documentId, kind, mergeFields, estimatedPageCount), max upload size, page size, reserved address zone, and quoting details. 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-organized and front-loaded with key points (purpose, when to use, return values). Each paragraph serves a purpose, though it's relatively long. A slight reduction in length could be possible 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 tool's complexity (multiple source options, merge fields, integration with other tools), the description is very complete. It covers usage, constraints, return values (despite no output schema), and context for sibling tools. No major gaps.

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 descriptions. Description adds meaning beyond schema: explains 'exactly one source' rule, max upload size 30 MB, output as US Letter, and how format can be inferred. Also clarifies that merging happens later via create_mail_quote.

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 a reusable template with placeholders for mail merge, and explicitly distinguishes from sibling tool 'create_letter' which is for identical content. The title also reinforces the purpose.

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 (content varies per recipient) and when not (identical content, use create_letter). Also provides guidance on how to provide source, rejection criteria, and integration with other tools.

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

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

Description says polling 'advances the campaign' (a side effect), contradicting annotations readOnlyHint and destructiveHint which mark it as non-modifying. This is a serious inconsistency.

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 purpose, no wasted words. Information is well-organized and easy to parse.

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 fields, side effects, and param source; however, the contradiction with annotations undermines reliability and completeness for safe agent 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?

Adds helpful context beyond the schema by explaining how to obtain the campaignId from jobStatusUrl, which aids correct invocation.

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 'Returns a campaign's validation/sending progress' with specific fields (status, counts, URL), distinguishing it from sibling tools like get_mail_job_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?

Provides context on when to use (after payment) and where to find the campaign ID, but does not explicitly exclude alternative tools or state when not to poll.

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 destructiveHint. The description adds that it returns normalized status and tracking events, but does not explain the openWorldHint (outputs may change) or any behavioral nuances like rate limits or authentication requirements. It provides some extra context but not enough to elevate beyond a baseline 3.

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, well-formed sentence that directly conveys the tool's purpose. It is concise with no unnecessary words. Could optionally list return data in a more structured format, but current form is efficient and 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 no output schema, the description partially explains return data (status, carrier/tracking/proof data, tracking events) but lacks details like status values or format. With only one parameter and no nested objects, the tool is simple, so moderate completeness is acceptable. However, more detail on expected output would improve usability.

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 only parameter, jobId, has no description in the schema schema coverage is 0%. The description says 'for a previously created job', implying jobId refers to that job, but does not add format, source, or validation details. This minimally compensates for the missing schema description. A score of 3 is appropriate as it meets the bare minimum.

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 name and title clearly indicate retrieving status of a mail job. The description specifies the exact data returned (normalized status, carrier/tracking/proof data, tracking events) and references a previously created job, distinguishing it from siblings like get_campaign_status or check_postagent_updates.

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

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

No guidance on when to use this tool vs. alternatives is provided. The description implies use after job creation but offers no exclusion criteria or comparison with sibling tools such as check_postagent_updates or 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?

Beyond annotations (destructiveHint: true), the description adds critical behavioral details: 'CHARGES MONEY AND IS IRREVERSIBLE: the server authorizes the SPT, prints the letter, then captures — a job comes back inline (no polling needed).' It also explains constraints (US-only, $0.50 minimum for cards) and the minting responsibility, fully disclosing 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: starts with a bold summary, then usage guidelines, a prominent warning, then detailed minting instructions. It is slightly verbose but each sentence adds necessary information for correct use. Front-loading of critical warnings is effective.

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 (payment with external token), the description covers prerequisites, flow, constraints, and error conditions. It mentions 'job comes back inline' but does not detail the response format. Overall, it provides enough context for an AI agent to invoke correctly, though explicit output schema would improve completeness.

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

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

The description adds significant value beyond the input schema. For 'sharedPaymentToken', it explains the minting process, scoping requirements, and references to quote's paymentOptions. For 'userConfirmed', it reinforces the need for explicit human approval. The schema coverage is 75% but the description compensates with rich contextual details.

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's purpose: 'autonomous, no-browser FIAT payment for a locked quote using a Stripe Shared Payment Token (SPT / Machine Payments Protocol)'. It clearly distinguishes from sibling tools like x402 and creates a clear mental model of the 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?

Provides explicit when-to-use guidance: 'Use this when the agent can mint an SPT...' and 'prefer x402 first if the agent has a USDC-on-Base wallet'. Also specifies prerequisites (minting SPT, user confirmation) and indicates that the tool charges money and is irreversible, guiding appropriate usage.

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 destructiveHint. The description adds context about probing a canonical URL and that no payment is taken, complementing annotations. Could mention return value details but not required for this simple 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?

Four sentences, no redundant wording. Front-loaded with the main purpose, then provides usage guidance and context. Every sentence 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?

For a simple inspection tool with one parameter and no output schema, the description covers the tool's role, alternatives, and the URL being probed. No additional information is needed for an agent to use it correctly.

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

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

The single parameter quoteId is described implicitly through the URL path pattern, adding meaning beyond the schema's minLength constraint. With 0% schema coverage, the description compensates enough by linking the parameter to the use case.

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 returns the x402 payment challenge for a locked quote, using the verb 'returns' and specifying the resource. It distinguishes from siblings by mentioning the alternative flow via 'submit_paid_mail_job'.

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

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

Explicitly states when to use this tool (for inspection or detached-signature flow) and notes the preferred alternative (in-band handshake). Clarifies that no payment is taken at this step, helping the agent decide when to invoke 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?

Annotations already provide destructiveHint=true and idempotentHint=false. Description adds significant context: charges USDC, creates physical letter, is irreversible. Contradictions? No. Enhances transparency 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 key purpose and alternatives, uses all-caps for emphasis, but some redundancy ('Only call after...' repeated). Each sentence adds value, though slightly verbose for some readers.

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 prerequisites, irreversible nature, and alternative paths. Lacks mention of expected response or error handling, and does not reference sibling status-checking tool (get_mail_job_status). Adequate but not fully comprehensive for a payment+mutation 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 description coverage is 75% (3 of 4 parameters have descriptions). The description adds little parameter-specific detail beyond linking paymentSignature to prepare_mail_payment. Baseline 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 is a 'Detached-signature fallback' for paying and mailing a letter, specifying the action (submit payment, create and mail) and distinguishing from the primary in-band payment path. It mentions sibling tools like create_mail_quote and prepare_mail_payment, providing specific verb+resource+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?

Explicitly instructs to use only if wallet cannot pay in-band ('use this tool only if your wallet client cannot do that') and gives prerequisites: user confirmation and obtained payment signature from prepare_mail_payment. Clear when-to-use and 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?

The description discloses the paid nature, the two-step x402 flow, the exact return format (CASS+ZIP4 for US, per-country for international), and required fields depending on address type. Annotations are consistent (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and the description adds significant 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?

The description is well-structured and front-loaded: first sentence captures the core purpose, followed by cost, flow, field requirements, and a clear exclusion note. Every sentence adds value, with no redundancy or filler.

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 (8 parameters, payment flow, no output schema), the description is complete: it covers the process, payment mechanism, address requirements, and relationship to sibling tools. An agent can correctly invoke the tool without additional 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?

The description adds meaning beyond the input schema by explaining the two-step payment flow, the role of paymentSignature, the country code semantics (US vs international), and required fields (line1 + city/state/zip for US, line1 + country for international). Schema coverage is 75%, but the description compensates fully.

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: verifying a postal address for deliverability and returning standardized form. It distinguishes itself from create_mail_quote, which already verifies addresses for free, making the use case 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 explicitly tells when to use this tool (standalone verification) and when not to (if mailing through PostAgent, use create_mail_quote instead). It also provides step-by-step guidance on the two-flow process with paymentSignature.

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