Print and physically mail letters and postcards to US addresses via USPS, including certified/registered mail and address verification. Paid per call in USDC on Base via the x402 protocol, no signup.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.6/5 across 14 of 14 tools scored. Lowest: 4/5.
Each tool targets a distinct function: updates, document upload (letter/template/postcard), quoting (single, campaign, postcard), payment (x402, MPP, card checkout, detached signature), and status tracking. There is minimal overlap; even the three quote tools (create_mail_quote, create_campaign_quote, create_postcard_quote) are clearly differentiated by recipient type and workflow.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_letter, get_campaign_status, submit_paid_mail_job). Verbs are descriptive and nouns clearly indicate the resource or action. There are no mixed conventions or vague names.
14 tools is well-scoped for a mailing and payment server. Each tool serves a distinct step in the workflow (upload, quote, pay, verify, track) without redundancy. The count is neither too low (would miss essential operations) nor too high (would overwhelm).
The tool set covers the core lifecycle: document preparation, quoting, multiple payment rails, address verification, and status tracking. Minor gaps exist, such as no explicit tool to cancel a job or list previously created documents, but these are not critical for typical use and can be worked around.
check_postagent_updatesCheck latest PostAgent skill and MCP versionsAFetches the live PostAgent agent manifest. Call this before using PostAgent in a new session, after reconnecting the MCP server, or when an installed PostAgent skill may be stale. If the installed skill is older than latestSkillVersion, read latestSkillUrl and follow those instructions for this turn; if updateRequired is true, do not perform paid or irreversible PostAgent actions until the user updates.
| Name | Required | Description | Default |
|---|---|---|---|
| installedMcpVersion | No | Version advertised by the connected PostAgent MCP server, if known. | |
| installedSkillVersion | No | Version from the installed PostAgent SKILL.md frontmatter, if known. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds contextual guidance on how to handle stale versions, which goes beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and front-loaded. Minor improvement possible by separating instructions into a more structured format, but overall concise.
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 the expected behavior and conditional actions, making it sufficiently complete for a version-check 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 100%, so baseline 3. Description does not add extra meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches the live PostAgent agent manifest and checks versions. Distinct from siblings which are about creating campaigns, cards, letters, etc.
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 specifies when to call (before new session, after reconnect, if skill may be stale) and what actions to take based on version comparison, including avoiding paid/irreversible actions if update is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_campaign_quoteGet a locked price quote for a bulk mail campaign (KYC required)AInspectQuote ONE bulk send to MANY recipients (up to 500): a single template or static document, fulfilled through PostAgent's campaign workflow. Price is an inclusive customer-facing total, locked for 15 minutes. Payment is x402 ONLY.
IMPORTANT — KYC WALL: campaigns require the paying wallet to be identity-verified with PostAgent. Verification is operator-run, not self-serve: 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 at https://interpretai.tech/contact (this URL is also returned in the 403's details.contactUrl) to get the wallet enabled.
Usage once the wallet is verified: upload a template with create_template (using {{fields}}) or a finished letter with create_letter, then call this with recipients (each to a US address, plus per-recipient mergeVariables for templates) and the payerWallet that will pay the quote. The print partner validates every recipient address after payment; failed recipients are excluded and their share refunded (processed manually). Track via get_campaign_status.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | US sender/return address. Required unless the server has a fallback. | |
| name | No | Campaign name (for your records). | |
| options | No | ||
| documentId | Yes | Template (html_template) or finished letter (pdf) documentId. | |
| recipients | Yes | One entry per recipient (1-500). | |
| payerWallet | Yes | The x402 wallet that will pay this quote. Must be KYC-verified with PostAgent (re-checked at payment against the wallet that actually signs). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate not read-only and not idempotent. The description adds critical behavioral details: price locking for 15 minutes, x402 payment only, KYC verification returning kyc_required (403), manual refund processing for failed recipients, and tracking via get_campaign_status. 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 front-loaded with the core purpose, then adds caveats and usage steps in a logical order. Every sentence adds value; there is no repetition or fluff. The length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, nested objects, and no output schema, the description covers prerequisites, error handling (KYC), post-payment validation, and refunds. However, it does not describe the successful return value format (e.g., quote ID, price), which would be helpful for an AI agent to process the result. This is a minor gap given the 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 description coverage is high (83%), but the description adds operational context beyond schema: e.g., 'documentId' must be from create_template or create_letter; 'recipients' mergeVariables only for templates; 'payerWallet' must be KYC-verified and notes re-check at payment. This helps the agent select correct values, though some schema descriptions already cover basics.
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 starts with a precise statement: 'Quote ONE bulk send to MANY recipients (up to 500): a single template or static document, fulfilled through PostAgent's campaign workflow.' It clearly identifies the verb (quote), resource (bulk campaign), and scope (up to 500 recipients), and distinguishes from siblings like create_mail_quote (individual) and 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?
The description explicitly states when not to use the tool due to the KYC requirement, offering alternatives: 'Do not retry the same wallet — instead either mail recipients individually with create_mail_quote, or request campaign access.' It also provides step-by-step usage instructions once verified, including prerequisites and tracking. This is comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_card_checkoutCreate a hosted credit-card checkout link for a quoteAInspectCreates a Stripe-hosted Checkout page for a locked quote and returns a checkoutUrl plus a statusUrl. 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). Hand the checkoutUrl to the user to open in a browser and pay; payment is asynchronous — once they finish, the letter is created automatically by Stripe's webhook. To track it without a job id, GET the returned statusUrl (/v1/quotes/:quoteId/job): it returns found:false with status pending/processing until the webhook creates the job, then the full job (id, status, tracking). Prefer x402 (or MPP, if available) for autonomous agent payment. Returns an error if Stripe Checkout is not enabled on the server. No charge occurs until the human completes the hosted page.
| Name | Required | Description | Default |
|---|---|---|---|
| quoteId | Yes | ||
| webhookUrl | No | Optional caller-controlled webhook URL to receive job status updates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate not read-only, but description adds critical behavioral details: no charge until human completes page, asynchronous webhook creates letter, and error condition. 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?
Somewhat dense but front-loads the main action. Every sentence adds value, though could be slightly more concise. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of asynchronous payment and no output schema, the description fully explains the process: how to get the URLs, what the user does, how to track payment completion, and error conditions. All necessary context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only webhookUrl has description). Description adds meaning by explaining quoteId is for a locked quote and webhookUrl is optional for status updates, though not explicitly re-summarized. The return values (checkoutUrl, statusUrl) are well explained.
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 and returns checkoutUrl and statusUrl. It distinguishes from sibling tools like pay_mail_with_shared_payment_token by positioning itself as a last-resort for human credit card payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use as last-resort payment rail for human credit card payment, prefers x402 or MPP for autonomous agent. Provides instructions on handling checkoutUrl and tracking via statusUrl. Also warns about error if Stripe Checkout not enabled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_letterUpload a finished letter (identical content, no mail merge)AInspectUpload and normalize a FINISHED, ready-to-mail document to PDF. Choose this when the content is final and IDENTICAL for every recipient — including when you mail the same letter to many people (just quote/pay once per recipient with the same documentId). The exact bytes you give are what gets printed. Use create_template instead only when the content must vary per recipient via {{fields}}. Returns a documentId, the stored page count, byte size, and source format. Free; no payment required.
Provide the document EXACTLY ONE way: content (inline text, for html/markdown/text), contentBase64 (base64-encoded binary, for pdf/docx/image), or url (a publicly reachable URL the server fetches). Supplying none, or more than one, is an error. Maximum upload size is 31457280 bytes (~30 MB); output page size is US Letter.
Any {{...}} text is printed LITERALLY here — it is NOT treated as a merge field. If you want personalized mail merge across recipients, use create_template instead.
Reserved address zone: a recipient address block is printed over the top ~3 inches of page 1, so the server reserves that space for you automatically. For text/html/markdown/docx, page-1 content is pushed below the block (content may therefore flow onto an additional page); for pdf and image inputs, a blank first page is prepended. As a result the returned page count — and the selected-provider cost behind the resulting quote — can be higher than your source document (e.g. a single-page PDF is stored as 2 pages). You do NOT need to leave the top of your document blank yourself. See the postagent://formats resource for per-format details.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL the server will fetch the document from. Provide exactly one source. | |
| format | No | Source format. Inferred from contentType/filename/content when omitted; inline `content` with no format defaults to text. | |
| content | No | Inline text content (html, markdown, or text). Provide exactly one source. | |
| filename | No | Optional original filename; used to help infer the source format. | |
| contentBase64 | No | Base64-encoded binary content (pdf, docx, image). Provide exactly one source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond annotations: upload and normalize behavior, reserved address zone, page count increase for PDF/images, literal {{...}} handling, upload size limit, and source exclusivity. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose. Each paragraph adds necessary detail, though slightly verbose. Could be more concise but remains clear and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a tool with no output schema: describes return fields (documentId, page count, byte size, source format). Covers all edge cases (source exclusivity, size limit, address zone, page count increase) and references external resource for format details.
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 critical semantics beyond schema: exactly one source required (content, contentBase64, or url), mutual exclusivity constraint not in schema, format inference defaults, and max upload size. Enhances understanding despite 100% 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?
Clearly states uploading a finished, identical letter for all recipients. Explicitly distinguishes from create_template for mail merge. Verb 'upload' and resource 'finished letter' are precise.
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 (final, identical content) and when-not (use create_template for variable content). Includes context like free, no payment needed, and explains reserved address zone behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_mail_quoteGet a locked price quote for a print-and-mail jobAInspectVerifies the recipient and sender US addresses and locks a 15-minute USDC price for a documentId. Does not charge or mail anything. Returns a paymentUrl (a per-quote x402-payable URL); the preferred way to actually mail the letter is for the agent's wallet to perform an in-band x402 payment against that URL (e.g. npx awal@latest x402 pay <paymentUrl>). The MCP submit_paid_mail_job tool is a fallback for clients that can emit a standalone signature header. In all cases, show the recipient, sender, options, selected-route design constraints, price, AND any fulfillment.warnings to the user and get explicit confirmation before paying. The response includes a fulfillment block with requested (what you asked for), selected (what will actually be printed/mailed) and warnings (any soft-preference downgrades — e.g. service_level_downgraded or extra_service_unavailable); do not pay through a non-empty warnings list without re-confirming the trade-off with the user. The response also includes a provider-neutral design block; inspect it and the preview before paying because the selected delivery method determines print address/no-ink zones.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient's US postal address. | |
| from | No | Sender/return address. Required unless the server has a fallback configured. | |
| options | No | ||
| documentId | Yes | ID returned by create_letter (finished document) or create_template (mail-merge template) for the piece to mail. | |
| mergeVariables | No | Values for a template document's {{merge fields}}, e.g. { "name": "Jane", "amount": "$42.00" }. Required when documentId refers to an html_template: every field listed in that document's mergeFields must have a non-empty value, or the quote is rejected. The server substitutes these into the template and renders this recipient's personalized PDF, so the quoted page count and price reflect the final content. Omit for plain (non-template) documents. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the 15-minute price lock, the non-charging/non-mailing nature, and the full response structure including warnings. Annotations indicate non-read-only (creates quote) but non-destructive, which aligns. No contradiction. Adds context beyond annotations like the payment URL mechanism.
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 but well-structured: front-loaded with core purpose, then details on payment, warnings, and response. Every sentence provides useful information. Slightly long, but justified by complexity. Could be tighter but still highly 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 (5 parameters, nested objects, no output schema), the description is complete. It explains the response blocks (fulfillment, design, paymentUrl), warns about warning inspection, and covers both payment paths. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, and the description adds meaning beyond the schema by explaining that documentId must come from create_letter or create_template, and that mergeVariables are required for templates. It also clarifies verification of addresses. These add value, justifying a 4 over baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core purpose: it verifies addresses, locks a 15-minute USDC price for a documentId, and explicitly says it does not charge or mail anything. This distinguishes it from siblings like submit_paid_mail_job which actually executes 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 provides explicit when-to-use guidance: it is the quote step before payment. It warns against paying without checking warnings and describes the preferred payment method (x402) and the fallback (submit_paid_mail_job). No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_postcard_artUpload postcard artwork (front or back)AInspectUpload ONE side of a postcard (front or back) as single-page PDF, PNG, or JPEG artwork. The file is stored VERBATIM — no page-size normalization and no reserved address zone — so you are responsible for the correct trim size plus bleed: 4x6 cards need 4.25"x6.25" artwork, 6x9 needs 6.25"x9.25", 6x11 needs 6.25"x11.25" (0.125" bleed on each edge). The selected delivery method prints the recipient address block over part of the BACK, so keep that area clear of critical content and review the quote's design block before payment. Returns a documentId with kind "postcard_art". Upload front and back separately, then quote with create_postcard_quote. Free; no payment required.
Provide the artwork EXACTLY ONE way: contentBase64 (base64-encoded pdf/png/jpeg) or url (publicly reachable). Text-based formats are rejected — postcards are artwork, not documents.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL the server fetches the artwork from. | |
| format | No | Artwork format; inferred from content when omitted. | |
| filename | No | ||
| contentBase64 | No | Base64-encoded single-page PDF, PNG, or JPEG artwork. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description thoroughly discloses behavioral traits beyond annotations: file stored verbatim with no normalization, no reserved address zone, correct trim size requirements, delivery method printing over back, return of documentId, and rejection of text formats. This adds substantial context beyond annotation fields.
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 relatively long but well-structured with key information front-loaded. Each sentence contributes meaningful details (size specs, address block, usage flow). Could be slightly more concise but efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and no output schema, description includes return type (documentId), relationship to sibling quote tool, and processing details. Fully covers what an agent needs to know 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?
Schema description coverage is 75%, high enough for baseline 3. Description adds key semantic info: exactly one of contentBase64 or url must be used, format inferred when omitted, and that content must be single-page PDF/PNG/JPEG. 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?
The tool name and title clearly indicate uploading postcard artwork. Description states exact action: upload one side as single-page PDF, PNG, or JPEG. Distinguishes from sibling create_postcard_quote by explaining separate steps. Specific verb and resource, no ambiguity.
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 explicitly states to upload front and back separately then quote with create_postcard_quote, and mentions no payment required. Provides clear context for when to use, but does not explicitly list when not to use alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_postcard_quoteGet a locked price quote for printing and mailing a postcardAInspectVerifies the recipient and sender addresses and locks a 15-minute USDC price for mailing a postcard built from two postcard_art documents (front + back, uploaded via create_postcard_art). Sizes: 4x6 (default), 6x9, 6x11 — postcards always print in full color. US recipients use the strict US address shape; INTERNATIONAL recipients are supported on 4x6 only (set to.country to the 2-letter ISO code; the sender must still be a US address). Payment works exactly like letters: pay the returned paymentUrl via x402, or use the MPP/checkout fallbacks. Show the recipient, sender, size, selected-route design constraints, price, AND any fulfillment.warnings to the user and get explicit confirmation before paying — service level is a soft preference and may have been downgraded (e.g. international economy is upgraded to standard) with a service_level_downgraded warning the agent must surface verbatim.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient address. | |
| from | No | US sender/return address. Required unless the server has a fallback configured. | |
| options | No | ||
| backDocumentId | Yes | documentId of the BACK artwork (kind postcard_art). The print partner prints the recipient address block over part of the back. | |
| frontDocumentId | Yes | documentId of the FRONT artwork (kind postcard_art). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic traits (not read-only, not idempotent, not destructive). The description adds significant behavioral detail: price lock time, address verification, international restrictions, service level downgrade warnings, and the need for explicit user confirmation. 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 somewhat long but well-structured: core purpose first, then details. Every sentence adds value, though minor redundancy exists (e.g., 'payment works exactly like letters'). Appropriate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains expected return elements (paymentUrl, design constraints, price, warnings) and required user actions (explicit confirmation). It covers restrictions and edge cases, making it complete for a quoting 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 80%, so baseline 3. The description adds meaning by explaining the purpose of front/back document IDs (postcard_art), the international country code requirement (only 4x6), and the soft nature of serviceLevel. This enhances 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 explicitly states the tool verifies addresses and locks a 15-minute USDC price for mailing a postcard from two art documents. It distinguishes from siblings like create_letter by focusing on postcards and referencing create_postcard_art. The verb+resource+scope are 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 context on when to use (for postcard quotes) and details the payment flow (x402, MPP/checkout fallbacks). It does not explicitly say when not to use or compare to all siblings, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_templateUpload a mail-merge template (content varies per recipient)AInspectUpload a REUSABLE template containing {{field}} placeholders (e.g. Dear {{name}}, or Balance due: {{amount}}). Choose this ONLY when the content must vary per recipient (mail merge) — recipient count is irrelevant, so a single personalized letter belongs here too. If the content is identical for everyone, use create_letter instead (this tool rejects input with no {{fields}}). Returns a documentId with kind: "html_template", a mergeFields list of the detected field names, and an estimatedPageCount. Free; no payment required.
Template source must be TEXT-BASED (html, markdown, or text) and must contain at least one {{field}}, or the upload is rejected — for a finished document with no merge fields, use create_letter.
Provide the template EXACTLY ONE way: content (inline text), contentBase64 (base64-encoded text), or url (a publicly reachable URL the server fetches). Supplying none, or more than one, is an error. Maximum upload size is 31457280 bytes (~30 MB); output page size is US Letter.
Reuse one template documentId across recipients: call create_mail_quote ONCE PER RECIPIENT, supplying that recipient's values via mergeVariables (every field in mergeFields must have a non-empty value). The server substitutes the values and renders that recipient's personalized PDF at quote time, so estimatedPageCount is only a baseline — the binding page count and price are set per quote from the actual rendered output.
Reserved address zone: a recipient address block is printed over the top ~3 inches of page 1, so the server reserves that space automatically (page-1 content is pushed below the block and may flow onto an additional page). You do NOT need to leave the top blank yourself. See the postagent://formats resource for details.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL the server will fetch the document from. Provide exactly one source. | |
| format | No | Template source format (text-based only). Inferred when omitted; inline `content` defaults to text. | |
| content | No | Inline text content (html, markdown, or text). Provide exactly one source. | |
| filename | No | Optional original filename; used to help infer the source format. | |
| contentBase64 | No | Base64-encoded binary content (pdf, docx, image). Provide exactly one source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal, but the description provides extensive behavioral context: no payment required, input must be text-based with placeholders, maximum upload size, output page size, address zone reservation, and how estimatedPageCount is a baseline. 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?
Detailed and well-structured, with core purpose first followed by usage rules and technical details. Slightly verbose but every sentence adds value; front-loading is appropriate.
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 details return fields (documentId, kind, mergeFields, estimatedPageCount), explains page count behavior, and addresses address zone reservation, making it self-contained.
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 description adds significant value: clarifies exactly one source must be provided, infers format, and explains the contentBase64 parameter as base64-encoded text (though schema says binary, creating minor inconsistency).
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 reusable template with mail-merge placeholders. It distinguishes from create_letter by specifying when each should be used.
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 directs to use this tool only when content varies per recipient, and to use create_letter for identical content. Also warns against uploading finished documents without merge fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_campaign_statusGet the status of a bulk mail campaignAReturns a campaign's validation/sending progress: status (validating | sent | partial | failed), recipient counts (total / validated / failed), and a failures report URL when some recipients could not be validated. Polling this endpoint also advances the campaign (it releases the campaign for mailing once the print partner finishes validating the audience). Find the campaign id on the quote's job status (GET jobStatusUrl) after payment.
| Name | Required | Description | Default |
|---|---|---|---|
| campaignId | Yes | Campaign id (cmp_…). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond annotations: polling also advances the campaign (releases it for mailing once validation finishes). However, this contradicts the readOnlyHint=true annotation, creating an 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?
The description is extremely concise: two sentences covering return fields, a side effect, and parameter sourcing. No unnecessary words, and the most critical information is front-loaded.
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, no output schema), the description is complete: it lists all returned fields, discloses a side effect, and explains how to obtain the required parameter. Sibling tools are distinct, so no confusion.
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?
Although the schema already describes the campaignId parameter (100% coverage), the description adds where to find the id (from the job status URL after payment), providing valuable usage context 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 that the tool returns a campaign's validation/sending progress with specific fields (status, recipient counts, failures report URL). It distinguishes itself from sibling tools like create_campaign_quote or pay_mail_with_shared_payment_token by focusing on status retrieval.
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 context for when to use the tool: after payment, to poll for status, and where to find the campaign id (on the quote's job status). However, it does not explicitly exclude alternatives or mention when not to use it, though sibling tools are clearly different.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_mail_job_statusGet the current status of a mail jobAReturns normalized status, carrier/tracking/proof data, and tracking events for a previously created job.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds meaningful behavioral context by specifying the types of returned data (normalized status, carrier/tracking/proof data, tracking events), which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant words. It efficiently conveys the tool's purpose and output without 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?
Given the tool's simplicity (one parameter, no output schema), the description is complete. It explains what the tool returns, which is necessary since there is no output schema. The annotations cover behavioral traits, leaving no critical 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?
With 0% schema description coverage, the description does not elaborate on the meaning of 'jobId' beyond what the schema provides (required string). It adds no additional semantics or formatting guidance, failing to compensate for the lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'normalized status, carrier/tracking/proof data, and tracking events' for a 'previously created job', which is a specific verb+resource combination. It distinguishes itself from sibling tools like create_* and submit_* that perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving information about an existing job ('for a previously created job') but does not explicitly state when to use or not use this tool versus alternatives like get_campaign_status or check_postagent_updates. No exclusions or scenario guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
prepare_mail_paymentFetch the x402 payment challenge for a quoteAReturns the x402 PAYMENT-REQUIRED challenge for a locked quote so an x402-capable wallet client can sign it. No payment is taken at this step. Probes the canonical per-quote pay URL (/v1/quotes/:quoteId/pay). The preferred way to actually pay is for the wallet to perform the standard x402 in-band handshake against paymentUrl; this tool is for inspection or for the detached-signature flow via submit_paid_mail_job.
| Name | Required | Description | Default |
|---|---|---|---|
| quoteId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds 'No payment is taken at this step' and confirms it's for inspection, aligning with annotations and providing context beyond.
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 focused sentences with no redundancy; first sentence states core purpose, and subsequent sentences add necessary context without waste.
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 one-parameter read-only tool, the description covers its role and flow adequately. Missing return format is acceptable as no output schema exists and the challenge type is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the tool's purpose and description imply quoteId is the quote identifier. However, the description does not explicitly define the parameter or its format, leaving a gap despite the parameter name being obvious in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the x402 payment challenge for a locked quote, distinguishes it from the standard in-band handshake, and mentions its use for inspection or detached-signature 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?
Explicitly says when to use (inspection/detached-signature) and when not (preferred is standard x402 handshake), and names related sibling tools 'pay_mail_with_shared_payment_token' and 'submit_paid_mail_job'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_paid_mail_jobSubmit a signed x402 payment to create and mail the letterADetached-signature fallback for x402 wallets that can emit a standalone PAYMENT-SIGNATURE header. THE PRIMARY/RECOMMENDED PATH is for the agent's wallet to pay the quote's paymentUrl in-band (e.g. npx awal@latest x402 pay <paymentUrl>); use this tool only if your wallet client cannot do that. Charges the agent in USDC on Base mainnet and creates a physical letter for printing and mailing. THIS IS IRREVERSIBLE. Only call after the user has explicitly confirmed the recipient, sender, content, and price returned by create_mail_quote, and after obtaining the signed x402 payment header (see prepare_mail_payment).
| Name | Required | Description | Default |
|---|---|---|---|
| quoteId | Yes | ||
| webhookUrl | No | Optional caller-controlled webhook URL to receive job status updates. | |
| userConfirmed | Yes | Must be true. Set this only after the human user explicitly approved sending physical mail at the quoted price. | |
| paymentSignature | Yes | x402 PAYMENT-SIGNATURE header value produced by an x402 client after signing the prepare_mail_payment challenge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description adds 'THIS IS IRREVERSIBLE' and notes charging USDC on Base mainnet. Aligns with annotations and provides actionable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, then usage path, then consequences, then preconditions. Every sentence adds value; no 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 complexity (irreversible payment, multiple preconditions, no output schema), the description covers purpose, guidelines, behavior, and parameters thoroughly. No gaps evident.
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 for 'userConfirmed' (must be true, after explicit approval) and 'paymentSignature' (x402 header). 'quoteId' and 'webhookUrl' are not elaborated further, but the description compensates well overall.
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 'submit' and the resource 'paid mail job', and distinguishes it from the primary in-band payment path. It specifies the x402 payment context, making the purpose unmistakable.
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 instructs to use this tool only if the wallet cannot do in-band payment. Also specifies preconditions: user confirmation, price, and signed header. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_addressVerify a postal address for deliverability (paid, flat fee)AStandalone paid address verification — no mail is sent. Checks whether an address is deliverable and returns the standardized form (US: CASS with ZIP+4; international: per-country matching). Costs a small flat USDC fee per call via x402 (a fraction of a cent vs. mailing).
Two-step flow, like the mail rails: call WITHOUT paymentSignature to get the 402 challenge and paymentUrl (preferred: have the agent's x402 wallet pay paymentUrl in-band with the address as the JSON POST body {"address":{...}}); or sign the challenge and call again WITH paymentSignature to verify and get the result in one round trip. US addresses need line1 + (city+state or zip). International addresses need line1 + country.
Note: when mailing through PostAgent you do NOT need this tool — create_mail_quote already verifies sender and recipient for free as part of the quote.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | ZIP or postal code | |
| city | No | ||
| name | No | Recipient/contact name (optional) | |
| line1 | Yes | Street address line 1 | |
| line2 | No | ||
| state | No | State/province/region | |
| country | No | 2-letter ISO country code. Omit or 'US' for CASS-standardized US verification; any other code runs international verification. | |
| paymentSignature | No | x402 PAYMENT-SIGNATURE header value signed against this endpoint's challenge. Omit to fetch the challenge first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a paid, idempotent, non-destructive tool with open-world semantics. The description adds important behavioral context: the cost via x402, the two-step payment flow, and the standardized output format. It does not contradict annotations. However, it could briefly mention that the output includes deliverability status and standardized address fields, but overall it provides sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with three concise paragraphs: overview and cost, two-step flow with requirements, and a crucial note about alternatives. Every sentence adds unique value. Despite moderate length, it is front-loaded with essential info and avoids 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 8 parameters (1 required), 75% schema coverage, and no output schema, the description provides sufficient context for an agent to decide when and how to use the tool. It covers payment flow, address field requirements, and alternative usage. The only minor gap is the lack of explicit output structure (e.g., 'returns a JSON with deliverability status and standardized fields'), but the mention of 'standardized form' partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema description coverage, the description adds significant meaning beyond the schema. It explains the purpose of 'paymentSignature' (omit to fetch challenge), the role of 'country' (omit or 'US' for US CASS verification), and required combinations (US: line1 + (city+state or zip); international: line1 + country). It also clarifies that 'name' is optional. This helps the agent understand parameter relationships.
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: verifying address deliverability and returning standardized forms (CASS for US, per-country for international). It distinguishes itself from sibling tools by noting it's standalone and not needed when using create_mail_quote (which includes free verification). The verb 'verify' and resource 'address' are clearly linked.
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 (standalone paid verification) and when not to (for mailing via PostAgent, where create_mail_quote provides free verification). It also details the two-step flow with paymentSignature, offering clear instructions for both cases: calling without paymentSignature to get a challenge, or with paymentSignature to get results in one round trip.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
