Skip to main content
Glama

Paddock Cards

Read an order

read_order
Read-onlyIdempotent

Read one known private purchase using its order ID and matching capability. Returns the current revision, payment state and order.cards with each card’s production and mailing states. Use it to check progress or refresh a stale revision; it does not change the order.

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": {
      "order_id": "<order_id>",
      "order_access_token": "<order_access_token>"
    },
    "name": "read_order"
  }
}

Input Schema

NameRequiredDescriptionDefault
order_idYesParent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase.
order_access_tokenYesExact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log.

Output Schema

NameRequiredDescriptionDefault
okYes
dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed26 schema fields changed
    • changedInput schema / properties / order_access_token / description
      Previous value: -"Private purchase capability. Keep it secret; never put it in a public URL or log."New value: +"Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log."
    • addedInput schema / properties / order_id / description
      Added value: +"Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / design_key / description
      Added value: +"Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / design_version / description
      Added value: +"Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / message_font / description
      Added value: +"Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / occasion / properties / calendar / description
      Added value: +"Must be us-western-v1, the supported occasion calendar."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / occasion / properties / day / description
      Added value: +"Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / occasion / properties / month / description
      Added value: +"Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / occasion / properties / send_on / description
      Added value: +"Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / address_confirmed / description
      Added value: +"Must be true: the buyer has confirmed the supplied mailing address."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / anniversary_day / description
      Added value: +"Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / anniversary_month / description
      Added value: +"Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / birthday_year / description
      Added value: +"Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / mailing_address / properties / country_code / description
      Added value: +"Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / mailing_address / properties / line1 / description
      Added value: +"Street address or postal delivery line supplied by the buyer."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / mailing_address / properties / locality / description
      Added value: +"City, town or postal locality."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / mailing_address / properties / postal_code / description
      Added value: +"Postal or ZIP code; use an empty string where the destination does not use one."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / mailing_address / properties / region / description
      Added value: +"State, province or region; use an empty string where the destination does not require one."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / origin / description
      Added value: +"Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / display_name / description
      Added value: +"Sender name printed with the return address."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / mailing_address / properties / country_code / description
      Added value: +"Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / mailing_address / properties / line1 / description
      Added value: +"Street address or postal delivery line supplied by the buyer."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / mailing_address / properties / locality / description
      Added value: +"City, town or postal locality."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / mailing_address / properties / postal_code / description
      Added value: +"Postal or ZIP code; use an empty string where the destination does not use one."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / mailing_address / properties / region / description
      Added value: +"State, province or region; use an empty string where the destination does not require one."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / return_address / properties / source_kind / description
      Added value: +"Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
  2. Changed4 schema fields changed
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / include_paddock_gift / description
      Added value: +"Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / paddock_gift
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "included": {
      +      "type": "boolean"
      +    },
      +    "omission_reason": {
      +      "anyOf": [
      +        {
      +          "enum": [
      +            "declined",
      +            "no_envelope",
      +            "international_delivery",
      +            "offer_unavailable",
      +            "not_selected"
      +          ],
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    }
      +  },
      +  "required": [
      +    "included",
      +    "omission_reason"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / product_spec
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "artwork_surface": {
      +      "enum": [
      +        "front",
      +        "front cover"
      +      ],
      +      "type": "string"
      +    },
      +    "envelope": {
      +      "additionalProperties": false,
      +      "description": "Present only for formats mailed in an envelope.",
      +      "properties": {
      +        "addressing": {
      +          "type": "string"
      +        },
      +        "size_in": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "height": {
      +              "exclusiveMinimum": 0,
      +              "type": "number"
      +            },
      +            "width": {
      +              "exclusiveMinimum": 0,
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "width",
      +            "height"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "required": [
      +        "size_in",
      +        "addressing"
      +      ],
      +      "type": "object"
      +    },
      +    "envelope_included": {
      +      "type": "boolean"
      +    },
      +    "format": {
      +      "enum": [
      +        "postcard",
      +        "flat_card_in_envelope",
      +        "folded_card_in_envelope"
      +      ],
      +      "type": "string"
      +    },
      +    "message_surface": {
      +      "description": "Where Paddock prints the personal message.",
      +      "type": "string"
      +    },
      +    "open_size_in": {
      +      "additionalProperties": false,
      +      "description": "Folded card only: size when opened.",
      +      "properties": {
      +        "height": {
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        },
      +        "width": {
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "width",
      +        "height"
      +      ],
      +      "type": "object"
      +    },
      +    "paper": {
      +      "description": "Card stock by its confirmed basis-weight designation.",
      +      "type": "string"
      +    },
      +    "paper_detail": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "basis_weight": {
      +          "type": "string"
      +        },
      +        "caliper_in": {
      +          "description": "Measured sheet thickness in inches; absent when unknown.",
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        },
      +        "color": {
      +          "description": "Absent until confirmed for the stock in use.",
      +          "type": "string"
      +        },
      +        "finish": {
      +          "description": "Absent until confirmed for the stock in use.",
      +          "type": "string"
      +        },
      +        "gsm": {
      +          "description": "Manufacturer-stated grammage; absent when unknown.",
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "basis_weight"
      +      ],
      +      "type": "object"
      +    },
      +    "personalization": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "automatic_greeting": {
      +          "type": "string"
      +        },
      +        "fit_check": {
      +          "type": "string"
      +        },
      +        "fonts": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "minItems": 1,
      +          "type": "array"
      +        },
      +        "max_message_chars": {
      +          "exclusiveMinimum": 0,
      +          "maximum": 9007199254740991,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "fonts",
      +        "automatic_greeting",
      +        "max_message_chars",
      +        "fit_check"
      +      ],
      +      "type": "object"
      +    },
      +    "printed_text": {
      +      "type": "string"
      +    },
      +    "size_in": {
      +      "additionalProperties": false,
      +      "description": "Finished size in inches; the closed size for the folded card.",
      +      "properties": {
      +        "height": {
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        },
      +        "width": {
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "width",
      +        "height"
      +      ],
      +      "type": "object"
      +    },
      +    "title": {
      +      "type": "string"
      +    },
      +    "version": {
      +      "maxLength": 60,
      +      "minLength": 1,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "version",
      +    "format",
      +    "title",
      +    "paper",
      +    "size_in",
      +    "artwork_surface",
      +    "message_surface",
      +    "envelope_included",
      +    "paper_detail",
      +    "personalization",
      +    "printed_text"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / data / properties / order / properties / cards / items / required
      Previous value: -[
      -  "id",
      -  "revision",
      -  "state",
      -  "payment_state",
      -  "refund_state",
      -  "refund_review_reason",
      -  "tax_review_reason",
      -  "input",
      -  "schedule",
      -  "amount_cents",
      -  "currency",
      -  "offer_version",
      -  "terms_version",
      -  "title",
      -  "artist_name",
      -  "quote_expires_at",
      -  "fulfillment_status",
      -  "mailed_at",
      -  "cancellable"
      -]New value: +[
      +  "id",
      +  "revision",
      +  "state",
      +  "payment_state",
      +  "refund_state",
      +  "refund_review_reason",
      +  "tax_review_reason",
      +  "input",
      +  "schedule",
      +  "amount_cents",
      +  "currency",
      +  "offer_version",
      +  "terms_version",
      +  "title",
      +  "artist_name",
      +  "quote_expires_at",
      +  "paddock_gift",
      +  "fulfillment_status",
      +  "mailed_at",
      +  "cancellable"
      +]
  3. Changed1 schema field changed
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / occasion / properties / kind / description
      Added value: +"Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
  4. Changed3 schema fields changed
    • changedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / message / description
      Previous value: -"Personal message, at most 2000 Unicode characters. Printed artwork wording is separate."New value: +"Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / display_name / description
      Added value: +"Name on the envelope or address panel."
    • addedOutput schema / properties / data / properties / order / properties / cards / items / properties / input / properties / recipient / properties / greeting_name / description
      Added value: +"Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
  5. Changed7 schema fields changed
    • changedOutput schema / properties / data / additionalProperties
      Previous value: -{}New value: +false
    • addedOutput schema / properties / data / properties
      Added value: +{
      +  "order": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "amount_cents": {
      +        "maximum": 9007199254740991,
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "card_count": {
      +        "maximum": 500,
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "cards": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "amount_cents": {
      +              "maximum": 9007199254740991,
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            "artist_name": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "cancellable": {
      +              "type": "boolean"
      +            },
      +            "currency": {
      +              "const": "usd",
      +              "type": "string"
      +            },
      +            "fulfillment_status": {
      +              "anyOf": [
      +                {
      +                  "enum": [
      +                    "scheduled",
      +                    "preparing",
      +                    "ready",
      +                    "mailed",
      +                    "cancel_requested",
      +                    "cancelled"
      +                  ],
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "id": {
      +              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      +              "type": "string"
      +            },
      +            "input": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "design_key": {
      +                  "maxLength": 160,
      +                  "minLength": 1,
      +                  "type": "string"
      +                },
      +                "design_version": {
      +                  "exclusiveMinimum": 0,
      +                  "maximum": 2147483646,
      +                  "type": "integer"
      +                },
      +                "format": {
      +                  "description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope.",
      +                  "enum": [
      +                    "postcard",
      +                    "flat_card_in_envelope",
      +                    "folded_card_in_envelope"
      +                  ],
      +                  "type": "string"
      +                },
      +                "include_paddock_gift": {
      +                  "type": "boolean"
      +                },
      +                "message": {
      +                  "description": "Personal message, at most 2000 Unicode characters. Printed artwork wording is separate.",
      +                  "maxLength": 4000,
      +                  "type": "string"
      +                },
      +                "message_font": {
      +                  "enum": [
      +                    "serif",
      +                    "sans_serif",
      +                    "old_school",
      +                    "handwriting"
      +                  ],
      +                  "type": "string"
      +                },
      +                "occasion": {
      +                  "additionalProperties": false,
      +                  "description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
      +                  "properties": {
      +                    "calendar": {
      +                      "const": "us-western-v1",
      +                      "type": "string"
      +                    },
      +                    "day": {
      +                      "maximum": 31,
      +                      "minimum": 1,
      +                      "type": "integer"
      +                    },
      +                    "kind": {
      +                      "maxLength": 100,
      +                      "minLength": 1,
      +                      "type": "string"
      +                    },
      +                    "month": {
      +                      "maximum": 12,
      +                      "minimum": 1,
      +                      "type": "integer"
      +                    },
      +                    "send_on": {
      +                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "kind",
      +                    "calendar"
      +                  ],
      +                  "type": "object"
      +                },
      +                "recipient": {
      +                  "additionalProperties": false,
      +                  "properties": {
      +                    "address_confirmed": {
      +                      "const": true,
      +                      "type": "boolean"
      +                    },
      +                    "anniversary_day": {
      +                      "maximum": 31,
      +                      "minimum": 0,
      +                      "type": "integer"
      +                    },
      +                    "anniversary_month": {
      +                      "maximum": 12,
      +                      "minimum": 0,
      +                      "type": "integer"
      +                    },
      +                    "birthday_day": {
      +                      "maximum": 31,
      +                      "minimum": 0,
      +                      "type": "integer"
      +                    },
      +                    "birthday_month": {
      +                      "maximum": 12,
      +                      "minimum": 0,
      +                      "type": "integer"
      +                    },
      +                    "birthday_year": {
      +                      "anyOf": [
      +                        {
      +                          "maximum": 9999,
      +                          "minimum": 1,
      +                          "type": "integer"
      +                        },
      +                        {
      +                          "type": "null"
      +                        }
      +                      ]
      +                    },
      +                    "display_name": {
      +                      "maxLength": 240,
      +                      "type": "string"
      +                    },
      +                    "greeting_name": {
      +                      "maxLength": 240,
      +                      "type": "string"
      +                    },
      +                    "mailing_address": {
      +                      "additionalProperties": false,
      +                      "properties": {
      +                        "country_code": {
      +                          "pattern": "^[A-Z]{2}$",
      +                          "type": "string"
      +                        },
      +                        "line1": {
      +                          "maxLength": 320,
      +                          "type": "string"
      +                        },
      +                        "line2": {
      +                          "maxLength": 320,
      +                          "type": "string"
      +                        },
      +                        "locality": {
      +                          "maxLength": 320,
      +                          "type": "string"
      +                        },
      +                        "postal_code": {
      +                          "maxLength": 48,
      +                          "type": "string"
      +                        },
      +                        "region": {
      +                          "maxLength": 160,
      +                          "type": "string"
      +                        }
      +                      },
      +                      "required": [
      +                        "line1",
      +                        "line2",
      +                        "locality",
      +                        "region",
      +                        "postal_code",
      +                        "country_code"
      +                      ],
      +                      "type": "object"
      +                    },
      +                    "origin": {
      +                      "const": "manual",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "display_name",
      +                    "birthday_month",
      +                    "birthday_day",
      +                    "mailing_address",
      +                    "address_confirmed",
      +                    "origin"
      +                  ],
      +                  "type": "object"
      +                },
      +                "return_address": {
      +                  "additionalProperties": false,
      +                  "properties": {
      +                    "display_name": {
      +                      "maxLength": 240,
      +                      "type": "string"
      +                    },
      +                    "mailing_address": {
      +                      "additionalProperties": false,
      +                      "properties": {
      +                        "country_code": {
      +                          "pattern": "^[A-Z]{2}$",
      +                          "type": "string"
      +                        },
      +                        "line1": {
      +                          "maxLength": 320,
      +                          "type": "string"
      +                        },
      +                        "line2": {
      +                          "maxLength": 320,
      +                          "type": "string"
      +                        },
      +                        "locality": {
      +                          "maxLength": 320,
      +                          "type": "string"
      +                        },
      +                        "postal_code": {
      +                          "maxLength": 48,
      +                          "type": "string"
      +                        },
      +                        "region": {
      +                          "maxLength": 160,
      +                          "type": "string"
      +                        }
      +                      },
      +                      "required": [
      +                        "line1",
      +                        "line2",
      +                        "locality",
      +                        "region",
      +                        "postal_code",
      +                        "country_code"
      +                      ],
      +                      "type": "object"
      +                    },
      +                    "source_kind": {
      +                      "const": "manual",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "display_name",
      +                    "mailing_address",
      +                    "source_kind"
      +                  ],
      +                  "type": "object"
      +                }
      +              },
      +              "required": [
      +                "design_key",
      +                "design_version",
      +                "message",
      +                "recipient"
      +              ],
      +              "type": "object"
      +            },
      +            "mailed_at": {
      +              "anyOf": [
      +                {
      +                  "format": "date-time",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "offer_version": {
      +              "type": "string"
      +            },
      +            "payment_state": {
      +              "enum": [
      +                "unpaid",
      +                "pending",
      +                "paid",
      +                "failed",
      +                "expired",
      +                "refunding",
      +                "refunded"
      +              ],
      +              "type": "string"
      +            },
      +            "quote_expires_at": {
      +              "format": "date-time",
      +              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      +              "type": "string"
      +            },
      +            "refund_review_reason": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "refund_state": {
      +              "enum": [
      +                "none",
      +                "pending",
      +                "processing",
      +                "succeeded",
      +                "failed",
      +                "unknown"
      +              ],
      +              "type": "string"
      +            },
      +            "revision": {
      +              "exclusiveMinimum": 0,
      +              "maximum": 9007199254740991,
      +              "type": "integer"
      +            },
      +            "schedule": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "arrival_end": {
      +                  "format": "date",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +                  "type": "string"
      +                },
      +                "arrival_start": {
      +                  "format": "date",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +                  "type": "string"
      +                },
      +                "birthday_date": {
      +                  "format": "date",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +                  "type": "string"
      +                },
      +                "collection_date": {
      +                  "format": "date",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +                  "type": "string"
      +                },
      +                "edit_deadline": {
      +                  "format": "date-time",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      +                  "type": "string"
      +                },
      +                "estimate_basis": {
      +                  "type": "string"
      +                },
      +                "late": {
      +                  "type": "boolean"
      +                },
      +                "leap_day_observed": {
      +                  "type": "boolean"
      +                },
      +                "next_year": {
      +                  "type": "boolean"
      +                },
      +                "one_off": {
      +                  "const": true,
      +                  "type": "boolean"
      +                },
      +                "post_by": {
      +                  "format": "date-time",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      +                  "type": "string"
      +                },
      +                "send_date": {
      +                  "format": "date",
      +                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +                  "type": "string"
      +                },
      +                "time_zone": {
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "time_zone",
      +                "birthday_date",
      +                "send_date",
      +                "collection_date",
      +                "arrival_start",
      +                "arrival_end",
      +                "edit_deadline",
      +                "post_by",
      +                "estimate_basis",
      +                "late",
      +                "leap_day_observed",
      +                "next_year"
      +              ],
      +              "type": "object"
      +            },
      +            "state": {
      +              "enum": [
      +                "prepared",
      +                "checkout_pending",
      +                "paid",
      +                "cancel_requested",
      +                "cancelled"
      +              ],
      +              "type": "string"
      +            },
      +            "tax_review_reason": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "terms_version": {
      +              "type": "string"
      +            },
      +            "title": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "id",
      +            "revision",
      +            "state",
      +            "payment_state",
      +            "refund_state",
      +            "refund_review_reason",
      +            "tax_review_reason",
      +            "input",
      +            "schedule",
      +            "amount_cents",
      +            "currency",
      +            "offer_version",
      +            "terms_version",
      +            "title",
      +            "artist_name",
      +            "quote_expires_at",
      +            "fulfillment_status",
      +            "mailed_at",
      +            "cancellable"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 500,
      +        "minItems": 1,
      +        "type": "array"
      +      },
      +      "checkout_url": {
      +        "anyOf": [
      +          {
      +            "format": "uri",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "currency": {
      +        "const": "usd",
      +        "type": "string"
      +      },
      +      "customer_content": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "rights_accepted": {
      +            "type": "boolean"
      +          },
      +          "rights_required": {
      +            "type": "boolean"
      +          },
      +          "terms_version": {
      +            "const": "customer-print-v1",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "rights_required",
      +          "rights_accepted",
      +          "terms_version"
      +        ],
      +        "type": "object"
      +      },
      +      "id": {
      +        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      +        "type": "string"
      +      },
      +      "payment_state": {
      +        "enum": [
      +          "unpaid",
      +          "pending",
      +          "paid",
      +          "failed",
      +          "expired",
      +          "refunding",
      +          "refunded"
      +        ],
      +        "type": "string"
      +      },
      +      "quote_expires_at": {
      +        "format": "date-time",
      +        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      +        "type": "string"
      +      },
      +      "refund_state": {
      +        "enum": [
      +          "none",
      +          "pending",
      +          "partial",
      +          "succeeded",
      +          "failed",
      +          "unknown"
      +        ],
      +        "type": "string"
      +      },
      +      "revision": {
      +        "exclusiveMinimum": 0,
      +        "maximum": 9007199254740991,
      +        "type": "integer"
      +      },
      +      "state": {
      +        "enum": [
      +          "prepared",
      +          "checkout_pending",
      +          "paid",
      +          "cancel_requested",
      +          "cancelled"
      +        ],
      +        "type": "string"
      +      },
      +      "tax_ready_count": {
      +        "maximum": 500,
      +        "minimum": 0,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "revision",
      +      "state",
      +      "payment_state",
      +      "refund_state",
      +      "amount_cents",
      +      "currency",
      +      "card_count",
      +      "tax_ready_count",
      +      "quote_expires_at",
      +      "checkout_url",
      +      "cards"
      +    ],
      +    "type": "object"
      +  }
      +}
    • removedOutput schema / properties / data / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • addedOutput schema / properties / data / required
      Added value: +[
      +  "order"
      +]
    • removedOutput schema / properties / error
      Removed value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "code": {
      -      "type": "string"
      -    },
      -    "issues": {
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "code": {
      -            "type": "string"
      -          },
      -          "field": {
      -            "enum": [
      -              "design_key",
      -              "design_version",
      -              "message",
      -              "format",
      -              "message_font",
      -              "include_paddock_gift",
      -              "recipient",
      -              "recipient.display_name",
      -              "recipient.greeting_name",
      -              "recipient.birthday_month",
      -              "recipient.birthday_day",
      -              "recipient.birthday_year",
      -              "recipient.anniversary_month",
      -              "recipient.anniversary_day",
      -              "recipient.mailing_address",
      -              "recipient.address_confirmed",
      -              "recipient.origin",
      -              "recipient.mailing_address.line1",
      -              "recipient.mailing_address.line2",
      -              "recipient.mailing_address.locality",
      -              "recipient.mailing_address.region",
      -              "recipient.mailing_address.postal_code",
      -              "recipient.mailing_address.country_code",
      -              "return_address",
      -              "return_address.display_name",
      -              "return_address.mailing_address",
      -              "return_address.source_kind",
      -              "return_address.mailing_address.line1",
      -              "return_address.mailing_address.line2",
      -              "return_address.mailing_address.locality",
      -              "return_address.mailing_address.region",
      -              "return_address.mailing_address.postal_code",
      -              "return_address.mailing_address.country_code",
      -              "occasion",
      -              "occasion.kind",
      -              "occasion.calendar",
      -              "occasion.month",
      -              "occasion.day",
      -              "occasion.send_on"
      -            ],
      -            "type": "string"
      -          },
      -          "index": {
      -            "maximum": 499,
      -            "minimum": 0,
      -            "type": "integer"
      -          }
      -        },
      -        "required": [
      -          "index",
      -          "code"
      -        ],
      -        "type": "object"
      -      },
      -      "maxItems": 500,
      -      "type": "array"
      -    },
      -    "message": {
      -      "type": "string"
      -    },
      -    "request_id": {
      -      "type": "string"
      -    },
      -    "retryable": {
      -      "type": "boolean"
      -    }
      -  },
      -  "required": [
      -    "code",
      -    "message",
      -    "retryable",
      -    "request_id"
      -  ],
      -  "type": "object"
      -}
    • addedOutput schema / properties / ok / const
      Added value: +true
    • changedOutput schema / required
      Previous value: -[
      -  "ok"
      -]New value: +[
      +  "ok",
      +  "data"
      +]
  6. First observed

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint:false and openWorldHint:false, so safety is documented. The description adds real context beyond that: it requires a matching private capability token, and it discloses the returned shape (current revision, payment state, per-card production and mailing states). The value-add is modest since much of the payload detail is also in the output schema.

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?

Two sentences with zero filler: identification and privacy constraint first, then return payload, then the no-side-effect guarantee. Every clause carries information an agent needs.

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?

With read/idempotent annotations, fully described parameters, and an output schema, the tool's needs are covered. The description supplies exactly the missing pieces: the private-token requirement and the stale-revision refresh use case.

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%, and the schema descriptions themselves cover the UUID format, the token secrecy rule, and the card-ID exclusion. The description only restates that an order ID plus matching capability is required, adding no syntax or edge-case detail beyond the schema, so 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?

States a specific verb and resource ("Read one known private purchase") plus the identity requirement (order ID + matching capability). The phrase "one known" distinguishes it from the sibling list_orders, and the explicit "it does not change the order" separates it from revise_order/cancel_order/pay_order without needing to open those schemas.

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

Usage Guidelines4/5

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

Gives concrete use cases ("check progress or refresh a stale revision") and an implicit exclusion via "it does not change the order," which routes mutations elsewhere. It does not name a specific alternative sibling (e.g. list_orders when the ID is unknown), so it falls short of the explicit when/when-not/alternatives bar.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources