Piloxa – Certified Mail

Buy and send a prepared certified letter

authorize_certified_letter

Idempotent

Buys and sends a letter that prepare_certified_letter prepared IN THIS CONVERSATION, after the person approved the exact total here. Call it only when (1) you have told the person the exact total, the recipient and the service, and they said yes to that total in this conversation, and (2) your platform has given you a Stripe shared payment token (spt_...) granted to Piloxa for that amount. Piloxa holds the payment, hands the letter to the printer, and charges only once the printer accepts it; if the printer refuses, the hold is released and nothing is charged. ALWAYS pass one idempotency_key per purchase and reuse it on every retry: the same key never charges twice and returns what already happened. If the total, the document or the address changed since the person approved, nothing is charged and you must ask again. Without a token, or if paying here is unavailable, nothing is charged and approval_url is returned: give it to the person, who pays there. The result carries transaction_state: AWAITING_APPROVAL, AUTHORIZED, VENDOR_ACCEPTED, MAILED, DELIVERED, RETURNED, FAILED or CANCELLED. Say a letter was sent only at VENDOR_ACCEPTED or later. At AUTHORIZED with failure OUTCOME_UNCERTAIN, do NOT retry: call get_certified_letter_status.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mailing_id": "<mailing_id>",
      "expected_total_cents": "<expected_total_cents>",
      "idempotency_key": "<idempotency_key>",
      "user_approved": "<user_approved>",
      "payer_email": "<payer_email>"
    },
    "name": "authorize_certified_letter"
  }
}

Input Schema

Name	Required	Description
`quote_id`	No	Optional: the quote_id prepare_certified_letter returned. It binds the approval to that exact document, recipient, sender, service and total; if any of them changed or it expired, nothing is charged and you must ask again.
`mailing_id`	Yes	The mailing_id prepare_certified_letter returned in this conversation.
`payer_email`	Yes	Where the receipt, the tracking and the mailing record go.
`user_approved`	Yes	True only when the person explicitly approved this exact total, recipient and service in this conversation.
`document_sha256`	No	Optional: the document_sha256 prepare_certified_letter returned. If the document changed since, nothing is charged.
`idempotency_key`	Yes	One key per purchase, 16 to 100 letters, digits or _ . : -. Reuse the same key on every retry of this purchase; a new key is a new purchase attempt.
`approval_statement`	No	The words the person was shown and said yes to, for the record, e.g. "Send this letter to Acme Property Management by USPS Certified Mail with return receipt for" followed by the exact total.
`expected_total_cents`	Yes	The exact total the person approved, in cents: the total_cents or estimated_total_cents Piloxa returned. If the current total differs, nothing is charged.
`shared_payment_token`	No	A Stripe shared payment token (spt_...) your platform issued to Piloxa for this purchase, limited to the approved amount.

Output Schema

Name	Required	Description
`mailed`	Yes
`charged`	Yes
`failure`	No
`receipt`	No
`service`	No
`currency`	No
`replayed`	No	True when this answers an earlier call with the same idempotency key, or a purchase already under way.
`recipient`	No
`reference`	No	The Piloxa mailing reference, once the letter exists as a mailing.
`mailing_id`	No
`final_quote`	No	When the total differs from expected_total_cents: the standard total, discount, payable total, currency and first-letter status for this payer. Ask the person to approve payable_total_cents.
`amount_cents`	No
`approval_url`	No	Where the person can review and pay instead.
`practice_run`	No
`state_meaning`	No
`document_sha256`	No
`amount_held_cents`	No
`printer_reference`	No
`transaction_state`	Yes
`amount_charged_cents`	No
`usps_tracking_number`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 9, 2026

addedInput schema / properties / quote_id

Added value: +{
+  "description": "Optional: the quote_id prepare_certified_letter returned. It binds the approval to that exact document, recipient, sender, service and total; if any of them changed or it expired, nothing is charged and you must ask again.",
+  "type": "string"
+}

addedOutput schema / properties / final_quote

Added value: +{
+  "description": "When the total differs from expected_total_cents: the standard total, discount, payable total, currency and first-letter status for this payer. Ask the person to approve payable_total_cents.",
+  "type": [
+    "object",
+    "null"
+  ]
+}

AddedOct 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare the mutation/idempotency/open-world profile, but the description discloses the actual money mechanics: funds are held, charged only after the printer accepts, released on refusal, and never charged if the total/document/address changed. It also explains idempotency_key retry semantics and the state machine that governs when an agent may tell the user a letter was sent.

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

Conciseness4/5

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

Front-loads the action, then the preconditions, then the failure semantics, which is the right order for a payment tool with this many caveats. It is dense but nearly every clause carries procedural weight; the enumerated transaction_state list is the one stretch that could have been left to the output schema.

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

Completeness5/5

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

Despite a nine-parameter schema, an output schema, and real financial risk, the description covers the approval gate, the token requirement, the no-charge guarantees, retry safety, and the status vocabulary an agent needs to report accurately. Nothing material for correct invocation appears to be missing.

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

Parameters3/5

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

Schema coverage is 100%, so every one of the nine parameters is already documented in the schema, including quote_id binding, expected_total_cents mismatch behavior, and idempotency_key reuse. The description reinforces the high-stakes ones (expected_total_cents, idempotency_key) but adds little semantic detail the schema does not already carry, so the baseline 3 applies.

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

Purpose5/5

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

Opens with a specific verb and resource ("Buys and sends a letter") and ties it directly to the artifact produced by prepare_certified_letter "IN THIS CONVERSATION," which cleanly separates it from the preparation sibling. An agent knows immediately this is the purchase step, not the quoting or status step.

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

Usage Guidelines5/5

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

Gives two explicit, checkable preconditions (person approved the exact total in this conversation; platform issued an spt_ token) and names the fallback when no token exists (approval_url). It also gives an explicit when-not-to-use rule: at AUTHORIZED with OUTCOME_UNCERTAIN, do not retry and call get_certified_letter_status instead.

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

All Piloxa – Certified Mail tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?