PostalForm

Create a mail order draft from letter text

postalform.create_letter_order_draft

Prepare letter text for mailing and return the order ID, total, hosted checkout URL, and checkout session. Accepts text directly; no PDF upload or browser is needed. Letter drafts may include typed or drawn signatures. After buyer approval, a compatible client can use complete_checkout with a Stripe shared payment token; otherwise present the hosted checkout URL. To prepare for MPP, set payment_protocol=mpp and buyer_email; receive a PDF preview, hosted checkout_url fallback and MPP challenge, then use postalform.pay_order with the order_id after buyer approval. Draft creation never pays. For x402, use postalform.create_machine_order.

Input Schema

Name	Required	Description
`color`	No
`letter`	Yes
`certified`	No
`buyer_name`	No	Receipt name; defaults to sender_name for MPP.
`mail_class`	No
`request_id`	No
`buyer_email`	No	Required for MPP receipt delivery.
`sender_name`	Yes
`double_sided`	No
`recipient_name`	Yes
`payment_protocol`	No	Optional payment path. Defaults to hosted checkout. Choose mpp to return a payment challenge for this same prepared order; buyer_email is required. Draft creation never pays.
`sender_address_id`	No
`sender_address_text`	No
`sender_address_type`	Yes
`recipient_address_id`	No
`sender_address_manual`	No
`recipient_address_text`	No
`recipient_address_type`	Yes
`certified_return_receipt`	No
`recipient_address_manual`	No

Output Schema

Name	Required	Description	Default
`view`	Yes
`payment`	No
`order_id`	Yes
`price_usd`	Yes
`page_count`	Yes
`preview_url`	No
`sender_name`	Yes
`checkout_url`	Yes
`recipient_name`	Yes
`checkout_session`	No
`payment_protocol`	No
`sender_address_text`	Yes
`recipient_address_text`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 5, 2026

addedOutput schema / properties / payment / properties / paid_at

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

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

changedOutput schema / properties / payment / 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"
+]

Changed6 schema fields changedOct 15, 2026
- changedInput schema / properties / recipient_name / maxLength
```
Previous value: -32New value: +255
```
- changedInput schema / properties / sender_name / maxLength
```
Previous value: -32New value: +255
```
- addedOutput schema / properties / recipient_name / maxLength
```
Added value: +255
```
- addedOutput schema / properties / recipient_name / minLength
```
Added value: +1
```
- addedOutput schema / properties / sender_name / maxLength
```
Added value: +255
```
- addedOutput schema / properties / sender_name / minLength
```
Added value: +1
```
First observedSep 27, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Adds real context beyond the annotations: 'Draft creation never pays', what the response contains, that typed or drawn signatures are accepted, and what an MPP call yields (PDF preview, fallback URL, challenge). Missing details are minor, such as draft lifetime or the role of request_id for idempotency.

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 purpose and return values, then branches through the payment paths in compact sentences. It is dense but nearly every sentence carries routing information; a mild cost is that the MPP and x402 branches interleave with the core description.

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

Completeness3/5

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

Output shape is well covered and there is an output schema, and the payment workflows are documented. However, for a 20-parameter tool with nested address objects, the required address-selection parameters and mailing options (mail_class, certified, double_sided) get no explanation anywhere, which leaves an agent guessing on mandatory inputs.

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 description coverage is only 15% across 20 parameters, so the description must carry the load. It explains payment_protocol, buyer_email, and the letter/signature shape, but leaves required fields like sender_address_type and recipient_address_type (Address vs Container vs Manual) and options like mail_class and certified entirely undocumented.

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?

States a specific verb and resource ('Prepare letter text for mailing') plus the concrete artifacts returned (order ID, total, hosted checkout URL, checkout session). It explicitly distinguishes itself from PDF upload and from the x402 path served by postalform.create_machine_order.

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?

Names the alternative routes and the conditions that select them: Stripe shared payment token via complete_checkout, otherwise the hosted checkout URL, MPP via payment_protocol=mpp followed by postalform.pay_order, and x402 via postalform.create_machine_order. When-not guidance is implied clearly (no PDF upload, no browser).

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?