Skip to main content
Glama
Sign In

Sendpaper

by io.github.ryan-tish
OverviewDiscussionsAdmin

Create a postcard

create_postcard

Create a postcard order (4x6, 6x9 or 6x11) and get a payment link. Front layouts: a big headline on a color, one photo, a photo with a caption, or a collage of 2-4 photos; the back carries the message (handwriting, serif or sans) and addresses. Set express for USPS Priority Mail (2-3 days, tracked). Mails only after the user pays.

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": {
      "from": "<from>",
      "content": "<content>"
    },
    "name": "create_postcard"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoRecipient's US mailing address (or use recipients for several people)
fromYesReturn address; printed on the mail piece. May be outside the US (set country)
sizeNoPostcard size: 4x6, 6x9 or 6x11 (see get_pricing for prices)4x6
contentYesFront (an image URL or a headline) and the message on the back
expressNoSend by express (USPS Priority Mail, usually 2–3 days, with tracking) for an extra charge; see get_pricing. Not available with certified.
recipientsNoSend the same piece to several people: 2-25 US addresses, used INSTEAD of to. Each gets their own order and tracking; one payment covers all.
customer_emailNoWhere to send the receipt and status updates
idempotency_keyNoAny unique string; retrying with the same key returns the original order instead of creating a duplicate

Output Schema

NameRequiredDescriptionDefault
idYesOrder id, ord_…
batchNoPresent when the order was created with recipients: the whole group. The top-level fields describe the first recipient's order; use batch.price and batch.checkout_url for the total and payment.
priceYes
objectYes
ordersNoEvery order in the group, when created with recipients
statusYesawaiting_payment, paid, printing, mailed, cancelled or refunded
productYesProduct id, e.g. postcard_4x6 or letter_certified
discountYesFirst-order discount, already taken off price; null when none applies
trackingYesUSPS tracking, for Certified Mail once printed
certifiedYesnone, certified or certified_return_receipt
order_urlYesOrder status page
preview_urlYesExact print preview
checkout_urlYesWhere the user pays; null once paid or cancelled
product_nameYes
status_detailYesPlain-English status to show the user
preview_image_urlNoPNG picture of the piece (postcard front and back, or the letter's first page) to show the user

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • changedInput schema / properties / from / description
      Previous value: -"Return address; printed on the mail piece"New value: +"Return address; printed on the mail piece. May be outside the US (set country)"
    • changedInput schema / properties / from / properties / city / description
      Previous value: -"City"New value: +"City or town"
    • addedInput schema / properties / from / properties / country
      Added value: +{
+  "description": "Two-letter country code (ISO 3166-1), e.g. GB. Defaults to US. The return address can be outside the US; the recipient must be in the US.",
+  "type": "string"
+}
    • changedInput schema / properties / from / properties / name / description
      Previous value: -"Recipient or sender full name"New value: +"Sender full name"
    • changedInput schema / properties / from / properties / state / description
      Previous value: -"Two-letter US state code, e.g. NY"New value: +"US: two-letter state code, e.g. NY (required). Elsewhere: region, county or province, if the address uses one"
    • addedInput schema / properties / from / properties / state / maxLength
      Added value: +40
    • changedInput schema / properties / from / properties / zip / description
      Previous value: -"5-digit US ZIP code, or ZIP+4"New value: +"US: 5-digit ZIP code or ZIP+4 (required). Elsewhere: postcode"
    • addedInput schema / properties / from / properties / zip / maxLength
      Added value: +12
    • removedInput schema / properties / from / properties / zip / pattern
      Removed value: -"^\\d{5}(-\\d{4})?$"
    • changedInput schema / properties / from / required
      Previous value: -[
-  "name",
-  "line1",
-  "city",
-  "state",
-  "zip"
-]New value: +[
+  "name",
+  "line1",
+  "city"
+]
  2. Changed1 schema field changed
    • addedOutput schema / properties / preview_image_url
      Added value: +{
+  "description": "PNG picture of the piece (postcard front and back, or the letter's first page) to show the user",
+  "type": "string"
+}
  3. Changed16 schema fields changed
    • addedInput schema / properties / content / properties / caption
      Added value: +{
+  "description": "photo_caption: short text over a band at the bottom of the photo",
+  "maxLength": 80,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / content / properties / front_headline / description
      Previous value: -"Big text for the front if there is no image, e.g. 'Happy birthday, Sam!'"New value: +"headline layout: big text for the front, e.g. 'Happy birthday, Sam!'"
    • changedInput schema / properties / content / properties / front_image_url / description
      Previous value: -"https URL of a photo or design for the front (JPG or PNG)"New value: +"https URL of a photo or design for the front (JPG or PNG); for photo and photo_caption"
    • addedInput schema / properties / content / properties / front_images
      Added value: +{
+  "description": "Collage: 2 to 4 https photo URLs, laid out in a grid",
+  "items": {
+    "maxLength": 2000,
+    "type": "string"
+  },
+  "maxItems": 4,
+  "minItems": 2,
+  "type": "array"
+}
    • changedInput schema / properties / content / properties / front_theme / description
      Previous value: -"Color theme for a text-only front"New value: +"headline layout: color theme (ink, sky, sunset, forest, rose, sand, night, mint)"
    • changedInput schema / properties / content / properties / front_theme / enum
      Previous value: -[
-  "ink",
-  "sky",
-  "sunset",
-  "forest"
-]New value: +[
+  "ink",
+  "sky",
+  "sunset",
+  "forest",
+  "rose",
+  "sand",
+  "night",
+  "mint"
+]
    • addedInput schema / properties / content / properties / headline_font
      Added value: +{
+  "default": "serif",
+  "description": "Font for the headline or caption: serif, sans or script (handwritten)",
+  "enum": [
+    "serif",
+    "sans",
+    "script"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / content / properties / layout
      Added value: +{
+  "description": "Front layout: headline (big text on a color), photo (one full-bleed photo), photo_caption (photo with a caption band), collage (2-4 photos). Inferred from the fields when omitted.",
+  "enum": [
+    "headline",
+    "photo",
+    "photo_caption",
+    "collage"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / content / properties / message / description
      Previous value: -"Handwritten-style message on the back"New value: +"The message on the back"
    • addedInput schema / properties / content / properties / message_font
      Added value: +{
+  "default": "handwriting",
+  "description": "Font for the message on the back",
+  "enum": [
+    "handwriting",
+    "serif",
+    "sans"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / express
      Added value: +{
+  "default": false,
+  "description": "Send by express (USPS Priority Mail, usually 2–3 days, with tracking) for an extra charge; see get_pricing. Not available with certified.",
+  "type": "boolean"
+}
    • addedInput schema / properties / recipients
      Added value: +{
+  "description": "Send the same piece to several people: 2-25 US addresses, used INSTEAD of to. Each gets their own order and tracking; one payment covers all.",
+  "items": {
+    "properties": {
+      "city": {
+        "description": "City",
+        "maxLength": 40,
+        "minLength": 2,
+        "type": "string"
+      },
+      "company": {
+        "description": "Company name, printed under the person's name",
+        "maxLength": 60,
+        "type": "string"
+      },
+      "line1": {
+        "description": "Street address",
+        "maxLength": 64,
+        "minLength": 3,
+        "type": "string"
+      },
+      "line2": {
+        "description": "Apartment, suite, unit",
+        "maxLength": 64,
+        "type": "string"
+      },
+      "name": {
+        "description": "Recipient or sender full name",
+        "maxLength": 60,
+        "minLength": 1,
+        "type": "string"
+      },
+      "state": {
+        "description": "Two-letter US state code, e.g. NY",
+        "type": "string"
+      },
+      "zip": {
+        "description": "5-digit US ZIP code, or ZIP+4",
+        "pattern": "^\\d{5}(-\\d{4})?$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "line1",
+      "city",
+      "state",
+      "zip"
+    ],
+    "type": "object"
+  },
+  "maxItems": 25,
+  "minItems": 2,
+  "type": "array"
+}
    • changedInput schema / properties / to / description
      Previous value: -"Recipient's US mailing address"New value: +"Recipient's US mailing address (or use recipients for several people)"
    • changedInput schema / required
      Previous value: -[
-  "to",
-  "from",
-  "content"
-]New value: +[
+  "from",
+  "content"
+]
    • addedOutput schema / properties / batch
      Added value: +{
+  "additionalProperties": false,
+  "description": "Present when the order was created with recipients: the whole group. The top-level fields describe the first recipient's order; use batch.price and batch.checkout_url for the total and payment.",
+  "properties": {
+    "checkout_url": {
+      "description": "One payment link for every unpaid order in the group",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "count": {
+      "description": "How many recipients (one order each)",
+      "type": "number"
+    },
+    "discount": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "amount_cents": {
+              "type": "number"
+            },
+            "display": {
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount_cents",
+            "display",
+            "reason"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "id": {
+      "type": "string"
+    },
+    "price": {
+      "additionalProperties": false,
+      "description": "Total for the whole group",
+      "properties": {
+        "amount_cents": {
+          "type": "number"
+        },
+        "currency": {
+          "type": "string"
+        },
+        "display": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "amount_cents",
+        "currency",
+        "display"
+      ],
+      "type": "object"
+    },
+    "url": {
+      "description": "Group page listing every recipient",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "count",
+    "url",
+    "checkout_url",
+    "price",
+    "discount"
+  ],
+  "type": "object"
+}
    • addedOutput schema / properties / orders
      Added value: +{
+  "description": "Every order in the group, when created with recipients",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "order_url": {
+        "type": "string"
+      },
+      "preview_url": {
+        "type": "string"
+      },
+      "to": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "to",
+      "order_url",
+      "preview_url"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
  4. Changed5 schema fields changed
    • changedInput schema / properties / size / description
      Previous value: -"Postcard size: 4x6 ($2.99) or 6x9 ($3.99)"New value: +"Postcard size: 4x6, 6x9 or 6x11 (see get_pricing for prices)"
    • changedInput schema / properties / size / enum
      Previous value: -[
-  "4x6",
-  "6x9"
-]New value: +[
+  "4x6",
+  "6x9",
+  "6x11"
+]
    • addedOutput schema / properties / discount
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "amount_cents": {
+          "type": "number"
+        },
+        "display": {
+          "type": "string"
+        },
+        "reason": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "amount_cents",
+        "display",
+        "reason"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "First-order discount, already taken off price; null when none applies"
+}
    • removedOutput schema / properties / first_postcard_free
      Removed value: -{
-  "additionalProperties": false,
-  "description": "Present when the first-postcard-free offer applies",
-  "properties": {
-    "applied": {
-      "type": "boolean"
-    },
-    "eligible": {
-      "type": "boolean"
-    },
-    "how": {
-      "type": "string"
-    }
-  },
-  "type": "object"
-}
    • changedOutput schema / required
      Previous value: -[
-  "id",
-  "object",
-  "product",
-  "product_name",
-  "certified",
-  "status",
-  "status_detail",
-  "price",
-  "checkout_url",
-  "order_url",
-  "preview_url",
-  "tracking"
-]New value: +[
+  "id",
+  "object",
+  "product",
+  "product_name",
+  "certified",
+  "status",
+  "status_detail",
+  "price",
+  "checkout_url",
+  "order_url",
+  "preview_url",
+  "tracking",
+  "discount"
+]
  5. Changed13 schema fields changed
    • addedInput schema / properties / content / description
      Added value: +"Front (an image URL or a headline) and the message on the back"
    • addedInput schema / properties / from / properties / city / description
      Added value: +"City"
    • addedInput schema / properties / from / properties / company / description
      Added value: +"Company name, printed under the person's name"
    • addedInput schema / properties / from / properties / state / description
      Added value: +"Two-letter US state code, e.g. NY"
    • addedInput schema / properties / from / properties / zip / description
      Added value: +"5-digit US ZIP code, or ZIP+4"
    • addedInput schema / properties / idempotency_key / description
      Added value: +"Any unique string; retrying with the same key returns the original order instead of creating a duplicate"
    • addedInput schema / properties / size / description
      Added value: +"Postcard size: 4x6 ($2.99) or 6x9 ($3.99)"
    • addedInput schema / properties / to / description
      Added value: +"Recipient's US mailing address"
    • addedInput schema / properties / to / properties / city / description
      Added value: +"City"
    • addedInput schema / properties / to / properties / company / description
      Added value: +"Company name, printed under the person's name"
    • addedInput schema / properties / to / properties / state / description
      Added value: +"Two-letter US state code, e.g. NY"
    • addedInput schema / properties / to / properties / zip / description
      Added value: +"5-digit US ZIP code, or ZIP+4"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "certified": {
+      "description": "none, certified or certified_return_receipt",
+      "type": "string"
+    },
+    "checkout_url": {
+      "description": "Where the user pays; null once paid or cancelled",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "first_postcard_free": {
+      "additionalProperties": false,
+      "description": "Present when the first-postcard-free offer applies",
+      "properties": {
+        "applied": {
+          "type": "boolean"
+        },
+        "eligible": {
+          "type": "boolean"
+        },
+        "how": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "id": {
+      "description": "Order id, ord_…",
+      "type": "string"
+    },
+    "object": {
+      "enum": [
+        "postcard",
+        "letter"
+      ],
+      "type": "string"
+    },
+    "order_url": {
+      "description": "Order status page",
+      "type": "string"
+    },
+    "preview_url": {
+      "description": "Exact print preview",
+      "type": "string"
+    },
+    "price": {
+      "additionalProperties": false,
+      "properties": {
+        "amount_cents": {
+          "type": "number"
+        },
+        "currency": {
+          "type": "string"
+        },
+        "display": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "amount_cents",
+        "currency",
+        "display"
+      ],
+      "type": "object"
+    },
+    "product": {
+      "description": "Product id, e.g. postcard_4x6 or letter_certified",
+      "type": "string"
+    },
+    "product_name": {
+      "type": "string"
+    },
+    "status": {
+      "description": "awaiting_payment, paid, printing, mailed, cancelled or refunded",
+      "type": "string"
+    },
+    "status_detail": {
+      "description": "Plain-English status to show the user",
+      "type": "string"
+    },
+    "tracking": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "number": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "number",
+            "url"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "USPS tracking, for Certified Mail once printed"
+    }
+  },
+  "required": [
+    "id",
+    "object",
+    "product",
+    "product_name",
+    "certified",
+    "status",
+    "status_detail",
+    "price",
+    "checkout_url",
+    "order_url",
+    "preview_url",
+    "tracking"
+  ],
+  "type": "object"
+}
  6. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare this is a non-read-only, open-world, non-destructive tool. The description adds important lifecycle context: it returns a payment link and does not mail until the user pays, and express uses tracked USPS Priority Mail.

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

Conciseness5/5

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

The description is front-loaded with the core create-order action and then compactly covers layouts, message/fonts, express, and payment gating. Every sentence carries useful selection or behavioral information.

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

Completeness4/5

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

For a complex nested tool with an output schema, the description covers the main creation flow and payment gating well. It omits bulk recipients and idempotency details, but those are documented in the schema.

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 100%, so the schema already documents sizes, layouts, fonts, express, and addresses in detail. The description summarizes some options but adds no syntax or format meaning beyond the schema.

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

Purpose4/5

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

The description states a specific verb and resource: 'Create a postcard order' with sizes and a payment link. It clearly separates this from get_pricing and pay_order by emphasizing order creation, though it does not explicitly contrast create_letter.

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

Usage Guidelines3/5

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

Usage is implied: create an order to get a payment link, and mailing happens only after payment. However, it does not explicitly say when to use this versus create_letter or when to call get_pricing/pay_order instead.

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

All Sendpaper toolsInspect
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