Skip to main content
Glama

Paddock Cards

Cancel cards

cancel_order
DestructiveIdempotent

Cancel an eligible purchase or eligible paid cards at the current order revision. Before payment, omit card_ids for whole-purchase cancellation. After payment, omit them for the whole eligible purchase or select returned card IDs. The service checks ownership and each fulfillment cutoff, then returns the actual cancellation and refund states.

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>",
      "expected_revision": "<expected_revision>"
    },
    "name": "cancel_order"
  }
}

Input Schema

NameRequiredDescriptionDefault
card_idsNoOmit to cancel the whole eligible purchase. After payment, select IDs from this order.cards[].id to cancel only those eligible items. Before payment, omit this field. IDs must be distinct and belong to this order.
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.
expected_revisionYesCurrent parent order.revision from prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order before deciding whether to retry cancellation.
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. Changed28 schema fields changed
    • changedInput schema / properties / card_ids / description
      Previous value: -"Omit to cancel the whole eligible purchase. For a paid purchase, list the returned card IDs to cancel only those eligible items. The service verifies every ID belongs to this order."New value: +"Omit to cancel the whole eligible purchase. After payment, select IDs from this order.cards[].id to cancel only those eligible items. Before payment, omit this field. IDs must be distinct and belong to this order."
    • addedInput schema / properties / expected_revision / description
      Added value: +"Current parent order.revision from prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order before deciding whether to retry cancellation."
    • 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
Behavior4/5

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

Annotations already declare destructive, idempotent, and non-read-only, so safety is covered. The description adds real value beyond that by disclosing that ownership and per-fulfillment cutoffs are checked server-side and that responses report actual cancellation and refund states, implying partial or rejected cancellations are possible. It does not discuss refund timing or what makes an item ineligible.

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?

Three sentences, front-loaded with the action and scope, then branching on payment state. The middle sentences are mostly earned, though the card_ids guidance overlaps with the schema and could be trimmed.

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 destructive, eligibility-gated mutation with an output schema, the description covers both operating modes, the server-side eligibility checks, and the shape of the result. The remaining omission is a definition of 'eligible' and any note on refund settlement, which the output schema only partly offsets.

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 the baseline is 3. The description's parameter content largely restates the card_ids schema text (omit for whole purchase, select returned IDs after payment) rather than adding new syntax or constraints, and it does not touch order_access_token or expected_revision beyond 'current order revision'.

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 names a specific verb (cancel) and both resource scopes (an eligible purchase, or eligible paid cards) tied to the current order revision. An agent can immediately tell this apart from pay_order, revise_order, and read_order in the sibling list.

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?

It gives explicit conditional guidance for each parameter path: omit card_ids before payment for whole-purchase cancellation, and after payment either omit for the whole eligible purchase or pass returned card IDs. It stops short of naming alternative tools or stating when not to cancel (e.g. pointing at revise_order), so it is clear context without full routing.

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