PostAgent — Print and Mail

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable context about comparing installed versions against the live manifest and the safety implication of updateRequired. No contradiction; the description enriches beyond the annotations with actionable behavioral rules.

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

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

Three sentences cover purpose, usage-trigger conditions, and conditional actions with zero filler. Information is front-loaded and 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 read-only check tool with no required parameters and full annotation coverage, the description is complete: it explains what happens, when to use it, and what to do based on the result. No missing context.

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

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

Schema coverage is 100% with descriptive parameter texts. The description does not add new parameter-level detail, but the schema already carries the meaning. Per rubric, baseline 3 is appropriate when the schema does the heavy lifting.

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 uses a specific verb ('Fetches the live PostAgent agent manifest') and clearly distinguishes this tool from all siblings, which are operational actions like creating mail or submitting jobs. It's immediately obvious that this is a version-check/manifest tool.

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 it ('before using PostAgent in a new session, after reconnecting the MCP server, or when an installed PostAgent skill may be stale') and provides conditional follow-up actions (read latestSkillUrl if outdated, avoid paid/irreversible actions if updateRequired). This is exactly the level of guidance needed.

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

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

Beyond the annotations, the description discloses critical behaviors: price lock for 15 minutes, x402-only payment, KYC wall returning 403, operator-run verification, no retry for same wallet, failed recipient refunds processed manually, and tracking via get_campaign_status. This significantly enriches the agent's understanding without contradicting annotations.

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

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

The description is front-loaded with the core purpose, then logically organized into KYC warning, usage workflow, and post-payment behavior. Every sentence contributes essential guidance; there is no fluff or repetition. The length is justified by the complexity of the tool's requirements.

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 complex KYC requirement, multi-step workflow, and no output schema, the description covers all necessary context: prerequisites, procedure, error behavior, alternatives, and follow-up tracking. It answers likely agent questions about when, how, and what after.

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%, so the schema already documents most fields. The description adds meaningful context that ties parameters together: 'recipients (each `to` a US address, plus per-recipient `mergeVariables` for templates)', 'payerWallet that will pay the quote', and how documentId maps to template vs letter. This goes beyond the schema but is not exhaustive, leaving some details to 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 opens with a specific verb and resource: 'Quote ONE bulk send to MANY recipients (up to 500): a single template or static document, fulfilled through PostAgent's campaign workflow.' This clearly distinguishes it from siblings like create_mail_quote and create_postcard_quote by scope and 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?

The description provides explicit when-to-use guidance, including prerequisites ('upload a template with create_template... or a finished letter with create_letter'), a direct alternative ('mail recipients individually with create_mail_quote'), and a clear exclusion ('Do not retry the same wallet'). It also explains the KYC verification process and when to request 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?

The description adds significant behavioral context beyond annotations: it explains the asynchronous nature (webhook creates the letter), how to track via statusUrl, and that no charge occurs until the human completes the hosted page. Annotations only cover readOnly, idempotency, and destructiveness; they do not disclose these operational details.

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 well-structured, front-loading the primary purpose and output. Each sentence adds value: usage condition, workflow, tracking, error case, and preference for alternatives. While somewhat lengthy, the complexity of the tool justifies the length.

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 fully describes return values (checkoutUrl, statusUrl) and the behavior of statusUrl polling. It covers prerequisites (locked quote, Stripe Checkout enabled), asynchronous workflow, and error handling. This is a complete picture for an 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?

The schema covers webhookUrl with a description, but quoteId lacks a description. The tool description adds meaning to quoteId by stating 'for a locked quote,' implying the quote must be locked. This compensates for the partial schema coverage, though it could explicitly link quoteId to a quote resource.

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 action: 'Creates a Stripe-hosted Checkout page for a locked quote and returns a checkoutUrl plus a statusUrl.' It uses a specific verb and resource, and distinguishes itself from sibling payment tools by emphasizing it is for human credit card payment, unlike x402 or MPP for autonomous agents.

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

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

Explicit usage guidance is provided: 'Use this as the LAST-RESORT payment rail, when the payer is a human paying by credit card (the agent cannot complete card entry itself).' It also specifies when not to use it ('Prefer x402 (or MPP, if available) for autonomous agent payment') and notes an error condition when Stripe Checkout is not enabled. This clearly differentiates from 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 key behavioral traits beyond the annotations: the exact bytes are printed, normalization to PDF, free/no payment, 30 MB upload limit, US Letter output, literal handling of {{...}}, and the reserved address zone behavior (content pushed down or blank page prepended). It even explains resulting page-count increases. Annotations only state readOnlyHint=false and openWorldHint=true, but the description adds rich operational context without contradicting them.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then logically covers usage guidance, delivery methods, size limits, literal handling, and the address zone effect. Paragraphs are well-separated, and the content is dense with no filler or repetition of schema definitions.

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 having no output schema, the description enumerates the return values: 'documentId, the stored page count, byte size, and source format.' It also addresses edge cases like literal {{...}} handling, page-count inflation, and per-format details referenced via postagent://formats. Given the tool's complexity and the lack of an output schema, the description is remarkably 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?

The schema already provides 100% coverage for each parameter, so the baseline is 3. The description adds meaningful cross-parameter semantics: it explicitly states that exactly one of content, contentBase64, or url must be supplied, and that none or multiple is an error. It also clarifies format inference and the default for inline content. This goes beyond the per-parameter schema descriptions and adds useful constraint 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?

The description opens with a specific verb+resource: 'Upload and normalize a FINISHED, ready-to-mail document to PDF.' It clearly distinguishes itself from the sibling create_template by stating 'identical content, no mail merge' and explicitly naming the alternative. This unambiguously communicates what the tool does and how it differs from related tools.

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

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

The description provides explicit when-to-use guidance: 'Choose this when the content is final and IDENTICAL for every recipient.' It also gives a concrete alternative: 'Use create_template instead only when the content must vary per recipient via {{fields}}.' It further clarifies the bulk-mailing scenario and the free/no-payment aspect, leaving no ambiguity about when this tool is appropriate.

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 only indicate non-read-only and non-destructive, so the description carries the burden of behavioral disclosure. It adds critical context: no charge/mail, 15-minute price lock, paymentUrl behavior, fulfillment.warnings, design block, and the requirement to inspect warnings before paying. This fully discloses the tool's behavior beyond what annotations or schema provide.

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

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

The description is dense and front-loaded, with the core purpose stated first: 'Verifies the recipient and sender US addresses and locks a 15-minute USDC price.' Every sentence adds value for payment workflow and warnings, though it is somewhat long; it earns its length given the tool's complexity and safety requirements.

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

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

With no output schema, the description thoroughly explains the response structure—paymentUrl, fulfillment block with requested/selected/warnings, and design block—and the necessary confirmation flow. It also clarifies the relationship to payment-related sibling tools, making the description complete for correct 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?

The input schema already provides rich descriptions for all parameters, with 80% coverage. The description adds minimal parameter-specific meaning beyond referencing documentId, and the schema already explains each parameter's purpose. Baseline 3 is appropriate since the schema does the heavy lifting.

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: it verifies addresses and locks a 15-minute USDC price for a documentId, while explicitly noting it does not charge or mail anything. It distinguishes itself from siblings like submit_paid_mail_job and create_postcard_quote by emphasizing the quote-only nature and the document context.

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 names the preferred payment method (x402 payment against the paymentUrl) and provides a fallback tool (submit_paid_mail_job) for alternative clients. It also instructs the agent to show all relevant details and get explicit confirmation before paying, and warns to re-confirm when warnings are present, giving clear when-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 only set generic hints (not read-only, open world, not idempotent, not destructive); the description adds crucial behaviors: stored verbatim with no normalization or reserved address zone, address block printing over the back, and return of a documentId. 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?

Every sentence provides necessary operational detail—format, one-per-side, bleed dimensions, address block caveat, quote sequencing, delivery mechanism, exclusion of text formats. Dense but efficient, front-loaded with the core action.

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 discloses return value (documentId with kind postcard_art), cost (free), and post-upload workflow (quote with create_postcard_quote). It covers the full lifecycle, including design review before payment.

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 with descriptions, and the description adds that contentBase64 and url are mutually exclusive ('EXACTLY ONE way'), clarifies specific formats (pdf/png/jpeg) and that URL must be publicly reachable. The filename parameter remains unexplained, but the core semantics are clear.

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 one side of a postcard as single-page PDF/PNG/JPEG, mentions it returns a documentId with kind 'postcard_art', and distinguishes itself from the subsequent create_postcard_quote step.

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 upload front and back separately, then use create_postcard_quote, and notes 'Free; no payment required.' Also provides specific trim-size/bleed requirements and states that text-based formats are rejected, giving clear when-to-use and what-not-to-do.

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 the annotations (readOnlyHint false, openWorldHint true, etc.), the description adds rich behavioral detail: address verification, 15-minute price lock, full-color printing, payment flow via paymentUrl with fallbacks, and service-level downgrade warnings that must be surfaced verbatim. This is exactly the kind of side-effect and workflow context that annotations do not provide.

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

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

The description is dense and front-loaded with the primary purpose, then proceeds through constraints and payment workflow. The final sentence is long and packed with imperative instructions, but every clause delivers necessary guidance. It is not bulleted, yet it remains efficiently written for the complexity it covers.

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?

There is no output schema, so the description carries the burden of explaining return values. It mentions paymentUrl, fulfillment.warnings, and service_level_downgraded, and instructs the agent to display them and get confirmation. It does not fully describe the overall quote response shape, but the key operational outputs are covered well enough for an agent to proceed.

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 schema already documents most parameter names and types. The description adds meaningful semantics beyond that: international requires to.country and 4x6 only, serviceLevel is a soft preference that may be downgraded, and postcards always print in full color. It does not exhaustively detail every field, but it compensates well for the schema's gaps.

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

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

The description opens with a specific verb and resource: 'Verifies the recipient and sender addresses and locks a 15-minute USDC price for mailing a postcard built from two postcard_art documents.' It clearly distinguishes this from letter or campaign tools by focusing on postcard-specific mechanics like front/back documents and size options.

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

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

The description gives explicit prerequisites (two postcard_art documents), strong constraints (international only on 4x6, sender must be US), and actionable guidance (show warnings, get confirmation before paying, surface service_level_downgraded verbatim). It does not explicitly name sibling alternatives like create_mail_quote, but the usage context is clear enough to guide selection.

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 only indicate non-read-only, non-destructive, non-idempotent behavior. The description goes far beyond that by disclosing rejection criteria, the 30MB upload limit, US Letter output, the reserved address zone that pushes content to additional pages, estimatedPageCount being only a baseline, and the server-side substitution and rendering behavior. This gives the agent a thorough understanding of side effects and constraints.

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

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

The description is long but every sentence carries essential information: use case, examples, alternatives, constraints, limitations, return values, and integration with create_mail_quote. It is well-structured into logical paragraphs and front-loads the most critical decision (when to use) before details.

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

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

With no output schema and limited annotations, the description carries the full burden of explaining return values and workflow. It clearly states that the response includes a documentId with kind 'html_template', a mergeFields list, and estimatedPageCount, and it explains how those values relate to subsequent per-recipient quoting. Coverage of error conditions, size limits, page size, and reserved address zones makes this tool fully understandable.

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 schema already covers all 5 parameters with descriptions, but the description adds substantial value: exactly one source must be provided, the format can be inferred, and the maximum size is 30MB. However, there is a conflict: the description calls `contentBase64` 'base64-encoded text' while the schema says it is 'Base64-encoded binary content (pdf, docx, image)', which could mislead an agent. This inconsistency prevents a perfect score.

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 opens with a specific action ('Upload a REUSABLE template') and clearly distinguishes this tool from siblings by explaining that it is for mail-merge content with `{{field}}` placeholders. It explicitly contrasts with create_letter and create_mail_quote, so the agent can select it unambiguously.

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 guidance: only when content varies per recipient, and tells the agent to use create_letter for identical content. It also explains exactly how to invoke the tool once per recipient with create_mail_quote, enumerates the exactly-one-source rule, and warns about rejection for missing `{{fields}}`.

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

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

Annotation Contradiction: The annotations declare readOnlyHint=true and idempotentHint=true, but the description states 'Polling this endpoint also advances the campaign (it releases the campaign for mailing...)' which is a side effect that modifies state. This directly contradicts the readOnly and idempotent hints.

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 the return payload, then the side effect, then a practical tip. Every sentence contributes necessary information with no fluff.

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

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

With no output schema, the description adequately enumerates return fields and status values. It also covers the side effect and how to obtain the input. The only significant gap is that it doesn't reconcile the side effect with the readOnly annotations, but that's already penalized under transparency.

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 single campaignId parameter, so the schema carries the basic meaning. The description adds value by telling the user where to find the campaign id (on the quote's job status after payment), which goes beyond the schema's type/format info.

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 a campaign's validation/sending progress, including specific fields (status, recipient counts, failures report URL). It distinguishes from the sibling get_mail_job_status by referencing the campaign id location on the quote's 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?

It gives clear context on when to use (after payment, via jobStatusUrl) and mentions polling behavior. It doesn't explicitly name alternatives or exclusions, but the context is strong enough.

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=false, so the safety profile is known. The description adds value by enumerating the types of data returned (normalized status, carrier/tracking/proof, tracking events), which goes beyond the annotations. No contradiction.

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

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

A single concise sentence, front-loaded with the action verb, that includes all essential information without any filler. Every word contributes to understanding the tool's function.

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 status-retrieval tool with one parameter and no output schema, the description provides a solid list of return data categories. It could mention possible error conditions or the source of the job ID, but the given context is sufficient for most use cases.

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 schema for jobId has no description (0% coverage), so the description must compensate. It does, somewhat, by noting the job was 'previously created', implying jobId refers to an existing job. However, it does not specify where the ID comes from or any format details, leaving some ambiguity.

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 specifies the resource: normalized status, carrier/tracking/proof data, and tracking events. It scopes to 'a previously created job', which distinguishes it from sibling tools like get_campaign_status and creation/payment tools.

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

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

The description implies use after job creation ('previously created job'), giving clear context. It doesn't explicitly name alternatives or exclusions, but the tool's purpose is obvious enough that an agent can infer when to use it.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description openly warns 'CHARGES MONEY AND IS IRREVERSIBLE' and explains the server-side flow (authorizes, prints, captures). It also adds non-obvious constraints like SPTs being US-only, the 0.50 USD minimum, and the inline job response without polling, enriching the behavioral context significantly.

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 dense and well-structured, starting with the core purpose and then layering safety warnings and technical minting instructions. While a bit long, every sentence contributes essential information for a tool that moves real money. It could be trimmed by moving the detailed SPT-minting instructions to a separate reference, but the current structure is justifiable given the stakes.

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 high complexity (irreversible payment, SPT requirement, no output schema), the description is remarkably complete. It covers prerequisites (user confirmation, SPT scoping), execution flow (inline response, no polling), and failure modes (error if MPP not configured). The absence of an output schema is compensated by explicitly stating what happens after the call ('a job comes back inline'), leaving little ambiguity for an agent.

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

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

The schema covers 75% of parameters, but the description adds meaningful depth to sharedPaymentToken (minting details, scoping to stripeProfileId, using link-cli) and userConfirmed (only after explicit human confirmation). For quoteId and webhookUrl, it relies on context but still provides enough through the overall workflow. This goes beyond the schema descriptions, warranting a score above 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 function: 'Autonomous, no-browser FIAT payment for a locked quote using a Stripe Shared Payment Token.' It uses a specific verb and resource (pay a quote) and explicitly differentiates itself from siblings by noting it is the fiat alternative to x402, which helps an agent select this over similar tools like prepare_mail_payment or 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?

Provides explicit when-to-use guidance: 'Use this when the agent can mint an SPT on the buyer's behalf and wants to pay by card/wallet without a human in a browser (prefer x402 first...).' It also gives an exclusion condition by saying 'Only call after the user has explicitly confirmed,' and mentions an alternative (x402) by name, making the decision framework clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that no payment is taken at this step and that it probes a specific canonical URL, providing context about the operation's effect without contradicting the annotations.

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

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

Three sentences, front-loaded with the core purpose, followed by relevant usage caveats. Every sentence earns its place and there is no fluff or repetition.

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 simple single-parameter tool and existing annotations, the description adequately explains what is returned, that no payment happens, and how this tool fits into the broader payment flows. It lacks detailed response format details, but the description orients an agent sufficiently for 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?

The only parameter, quoteId, is required and has a schema type and minLength. The description references 'per-quote pay URL' implying the parameter is the quote identifier, but it does not explicitly define quoteId. With one param and low schema coverage, the indirect context is sufficient but not exemplary.

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 returns the x402 PAYMENT-REQUIRED challenge for a locked quote, and explicitly distinguishes this from the in-band handshake and the detached-signature flow via submit_paid_mail_job. The verb 'returns' plus the resource and scope make the purpose unambiguous.

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 it: for inspection or the detached-signature flow via submit_paid_mail_job, while noting the preferred payment method is the standard in-band handshake. This gives clear alternative guidance and exclusion criteria.

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

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

Beyond the annotations (destructiveHint=true), the description adds crucial details: it charges the agent in USDC on Base mainnet, creates a physical letter, and is irreversible. This goes far beyond the annotation's generic destructive flag and gives the agent a concrete understanding of consequences.

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-loading the core purpose and fallback status, then packing usage constraints and consequences into a compact warning. No fluff; every clause adds necessary guidance. Despite its density, it remains highly scannable.

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 complex, irreversible payment and mailing tool with no output schema, the description covers all critical aspects: the exact trigger condition, prerequisites, cost (USDC on Base), outcome (physical letter), and irreversibility. It also points to related tools (prepare_mail_payment) for further context. This is thoroughly complete for agent decision-making.

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 with descriptions. The description adds meaning by connecting paymentSignature to the prepare_mail_payment challenge and userConfirmed to explicit human approval. It also implies quoteId from create_mail_quote. While not deeply detailed, it supplements the schema effectively for a tool with high schema coverage.

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 this tool is a detached-signature fallback for x402 wallets, specifically for submitting a signed payment to create and mail the letter. It distinguishes itself from the primary in-band payment path and sibling tools like pay_mail_with_shared_payment_token, making its unique role obvious.

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 the primary/recommended path is in-band payment via paymentUrl, and this tool should only be used if the wallet client cannot do that. It also provides clear prerequisites: user must confirm recipient, sender, content, and price, and the signed x402 header must be obtained via prepare_mail_payment. This is excellent when/when-not 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?

Despite annotations already marking readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral context: a flat USDC fee is charged, the two-step payment flow with challenge and signature, the standardized output, and the advantage of in-band payment. It does not contradict any annotation and fully discloses the tool's side effects and flow.

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 focused paragraphs: purpose/pricing, detailed flow, and a note about an alternative. Every sentence carries essential information; no filler. It is front-loaded with the core purpose and quickly differentiates from siblings, making it easy for an agent to process.

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 tool is complex (8 params, payment flow, no output schema), but the description fully covers all critical context: it explains the two-step payment protocol, fee implications, required vs. optional fields, US/international behavior, and the relationship to sibling tools. Given no output schema, it still leaves the agent with a clear mental model of how the tool operates and what it returns.

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

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

With 75% schema description coverage, the description still adds critical meaning beyond the schema: it explains the paymentSignature flow (omit to get challenge, include to verify), the country field's role in selecting US vs. international verification, and exact address requirements (line1 + city/state/zip for US, line1 + country for international). This enriches the agent's understanding of how parameters interact.

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: 'Checks whether an address is deliverable and returns the standardized form' with specific details (CASS, ZIP+4, international matching). It also explicitly distinguishes itself from sibling tools, noting that create_mail_quote already verifies addresses for free when 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?

Provides explicit usage context: standalone verification, no mail is sent, paid via x402. It also gives a clear 'when NOT to use' by stating that within PostAgent you should use create_mail_quote instead. The two-step payment flow and address requirements for US vs. international are clearly explained, giving the agent all necessary decision guidance.

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