PostalForm

Pay a prepared order with MPP

postalform.pay_order

Get an MPP challenge or pay an existing MPP PDF, letter, workflow-form order, or bulk letter campaign after buyer approval. Use the order_id returned by any draft tool with payment_protocol=mpp or by create_machine_order. When switching from create_machine_order, omit the credential first to get this payment endpoint’s challenge. Review the preview or campaign_url, recipient count and total. No document or addresses are resubmitted. Without payment_authorization this only returns a challenge; with it, this can pay and send real mail. Reuse the same order_id on retries and follow the returned payment status.

Input Schema

Name	Required	Description	Default
`order_id`	Yes
`payment_authorization`	No	Buyer-approved MPP Authorization header, usually Payment ... . Omit to retrieve the challenge.

Output Schema

Name	Required	Description	Default
`bulk`	No
`view`	Yes
`status`	Yes
`is_paid`	Yes
`paid_at`	Yes
`payment`	No
`currency`	Yes
`endpoint`	Yes
`order_id`	Yes
`protocol`	Yes
`next_step`	No
`price_usd`	Yes
`page_count`	No
`request_id`	Yes
`status_url`	No
`next_action`	No
`preview_url`	No
`campaign_url`	No
`checkout_url`	No
`postcard_size`	Yes
`mailpiece_type`	Yes
`payment_status`	Yes
`payment_options`	No
`order_complete_url`	Yes
`payment_status_label`	Yes
`payment_status_description`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 5, 2026

addedOutput schema / properties / paid_at

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / payment_status_description
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / payment_status_label
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "view",
-  "protocol",
-  "order_id",
-  "request_id",
-  "endpoint",
-  "status",
-  "payment_status",
-  "is_paid",
-  "price_usd",
-  "currency",
-  "mailpiece_type",
-  "postcard_size",
-  "order_complete_url"
-]New value: +[
+  "view",
+  "protocol",
+  "order_id",
+  "request_id",
+  "endpoint",
+  "status",
+  "payment_status",
+  "payment_status_label",
+  "payment_status_description",
+  "paid_at",
+  "is_paid",
+  "price_usd",
+  "currency",
+  "mailpiece_type",
+  "postcard_size",
+  "order_complete_url"
+]

First observedSep 27, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true) the description discloses the key behavioral fork: without payment_authorization it only returns a challenge; with it, it can pay and send real mail. It further notes no document or addresses are resubmitted and that the agent should follow the returned payment status, which is meaningful context for a charge-and-mail operation.

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?

Six dense sentences, but they are front-loaded with purpose and the credential-switching rule, and each carries actionable content. The 'Review the preview or campaign_url, recipient count and total' line is the weakest for informational density but still supports verification before paying.

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?

For a two-parameter, high-stakes payment tool with an output schema, the description covers the prerequisite (buyer approval), provenance of order_id, credential handling, side effects (real mail), retry semantics, and post-call behavior. Nothing an agent needs to invoke it safely is missing.

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

Parameters4/5

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

Schema coverage is only 50%, and order_id has no schema description, so the description compensates by explaining where order_id comes from (draft tools with payment_protocol=mpp, or create_machine_order) and that it must be reused on retries. For payment_authorization it adds the consequence of supplying vs omitting it, though the challenge-vs-pay point partly duplicates the schema's own description.

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?

The description opens with a specific verb and resource set: get an MPP challenge or pay an existing MPP PDF, letter, workflow-form order, or bulk letter campaign. It clearly scopes the tool against the draft-creation siblings by naming create_machine_order and the payment_protocol=mpp draft path.

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?

It gives explicit when-to-use and how-to-sequence guidance: use the order_id returned by draft tools with payment_protocol=mpp or by create_machine_order, and when switching from create_machine_order omit the credential first to obtain this endpoint's challenge. It also states the retry rule (reuse the same order_id) and the prerequisite of buyer approval.

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

All PostalForm 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?