Skip to main content
Glama

Paddock Cards

Prepare an order

prepare_order
Idempotent

Prepare one unpaid purchase of 1 to 500 cards, with mixed artwork, formats, messages, recipients, occasions and dates in one cards array. Each card is priced for its recipient country. Returns order.cards, the exact total, a private order_access_token and review_url for buyer review and payment. When preview_available is true, optional preview_card can show the finished card; images render only when requested. This authorizes neither a charge nor mailing. Preserve the returned token privately for retries and follow-up tools. If the first response is lost before saving a server-generated token, use a new request_id for another unpaid purchase. The 500-card/4-MiB bounds are technical request limits. Validation issues identify zero-based card indices without copying private content.

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": {
      "request_id": "<request_id>",
      "cards": "<cards>"
    },
    "name": "prepare_order"
  }
}

Input Schema

NameRequiredDescriptionDefault
cardsYesOne purchase containing 1–500 explicit card compositions in their supplied order. Mix any supported designs, formats, messages, recipients, occasions and dates. Do not group purchases by occasion. One card uses this same array.
request_idYesCaller-generated UUID for a new purchase. For private artwork, use scope_id from open_private_content. Retry only with this same ID, unchanged cards and the exact order_access_token; a different purchase needs a new ID.
order_access_tokenNoFor a new catalog purchase, omit so Paddock generates and returns the private token. Private artwork uses the token from open_private_content with request_id = scope_id. Retries require the exact token, same request_id and unchanged cards. Never invent a token. Only clients with a cryptographic random generator may pre-generate 32 random bytes encoded as 43 base64url characters for first-response recovery. Keep it private; existing purchase capabilities cannot be replaced.

Output Schema

NameRequiredDescriptionDefault
okYes
dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed55 schema fields changed
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / occasion / properties / calendar / description
      Added value: +"Must be us-western-v1, the supported occasion calendar."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / recipient / description
      Added value: +"Buyer-supplied recipient details for this card. This does not create or select a saved member recipient."
    • addedInput schema / properties / cards / items / properties / recipient / properties / address_confirmed / description
      Added value: +"Must be true: the buyer has confirmed the supplied mailing address."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / recipient / properties / birthday_day / description
      Added value: +"Birth day valid for birthday_month; February 29 is allowed. Use 0 with birthday_month 0 when the birthday is unknown and this is not a birthday mailing."
    • addedInput schema / properties / cards / items / properties / recipient / properties / birthday_month / description
      Added value: +"Birth month, 1 through 12, required with birthday_day when occasion.kind is birthday. Otherwise omit both or use 0 for both when unknown."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / recipient / properties / mailing_address / description
      Added value: +"Recipient mailing address supplied and confirmed by the buyer."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / recipient / properties / mailing_address / properties / line1 / description
      Added value: +"Street address or postal delivery line supplied by the buyer."
    • addedInput schema / properties / cards / items / properties / recipient / properties / mailing_address / properties / locality / description
      Added value: +"City, town or postal locality."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / recipient / properties / origin / description
      Added value: +"Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
    • addedInput schema / properties / cards / items / properties / return_address / properties / display_name / description
      Added value: +"Sender name printed with the return address."
    • addedInput schema / properties / cards / items / properties / return_address / properties / mailing_address / description
      Added value: +"Sender return mailing address supplied by the buyer."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / return_address / properties / mailing_address / properties / line1 / description
      Added value: +"Street address or postal delivery line supplied by the buyer."
    • addedInput schema / properties / cards / items / properties / return_address / properties / mailing_address / properties / locality / description
      Added value: +"City, town or postal locality."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / 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."
    • changedInput schema / properties / order_access_token / description
      Previous value: -"Omit on the first call so Paddock securely generates and returns the private token. Never invent or type a random-looking token. On retries use the exact returned token, same request_id and unchanged cards. Only clients with a cryptographic random generator may pre-generate 32 random bytes encoded as 43 base64url characters for first-response recovery. Existing purchase capabilities cannot be replaced."New value: +"For a new catalog purchase, omit so Paddock generates and returns the private token. Private artwork uses the token from open_private_content with request_id = scope_id. Retries require the exact token, same request_id and unchanged cards. Never invent a token. Only clients with a cryptographic random generator may pre-generate 32 random bytes encoded as 43 base64url characters for first-response recovery. Keep it private; existing purchase capabilities cannot be replaced."
    • addedInput schema / properties / request_id / description
      Added value: +"Caller-generated UUID for a new purchase. For private artwork, use scope_id from open_private_content. Retry only with this same ID, unchanged cards and the exact order_access_token; a different purchase needs a new ID."
    • 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. Changed2 schema fields changed
    • addedOutput schema / properties / data / properties / preview_available
      Added value: +{
      +  "description": "At least one current card is eligible for optional preview_card. Images render only when requested; access and current state are rechecked then.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / data / required
      Previous value: -[
      -  "order",
      -  "order_access_token",
      -  "review_url"
      -]New value: +[
      +  "order",
      +  "order_access_token",
      +  "review_url",
      +  "preview_available"
      +]
  3. Changed7 schema fields changed
    • addedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / return_address / description
      Added value: +"Required for every card format: the sender’s name and return mailing address supplied by the buyer. Not automatically obtained from billing details."
    • changedInput schema / properties / cards / items / required
      Previous value: -[
      -  "design_key",
      -  "design_version",
      -  "message",
      -  "recipient"
      -]New value: +[
      +  "design_key",
      +  "design_version",
      +  "message",
      +  "recipient",
      +  "return_address"
      +]
    • 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"
      +]
  4. Changed3 schema fields changed
    • addedInput schema / properties / cards / items / 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."
    • changedInput schema / properties / order_access_token / description
      Previous value: -"Optionally generate and privately store 32 cryptographically random bytes encoded as 43 base64url characters before the first request. Reuse that token with the same request_id and unchanged cards to recover a lost response. If omitted, the server generates and returns the capability. Existing purchase capabilities cannot be replaced."New value: +"Omit on the first call so Paddock securely generates and returns the private token. Never invent or type a random-looking token. On retries use the exact returned token, same request_id and unchanged cards. Only clients with a cryptographic random generator may pre-generate 32 random bytes encoded as 43 base64url characters for first-response recovery. Existing purchase capabilities cannot be replaced."
    • 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."
  5. Changed12 schema fields changed
    • changedInput schema / properties / cards / items / 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."
    • addedInput schema / properties / cards / items / properties / recipient / properties / display_name / description
      Added value: +"Name on the envelope or address panel."
    • addedInput schema / properties / cards / items / properties / recipient / properties / greeting_name / description
      Added value: +"Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
    • addedInput schema / properties / cards / items / properties / recipient / properties / mailing_address / properties / line2 / default
      Added value: +""
    • addedInput schema / properties / cards / items / properties / recipient / properties / mailing_address / properties / line2 / description
      Added value: +"Optional second line, such as an apartment or suite. Omitted means empty."
    • changedInput schema / properties / cards / items / properties / recipient / properties / mailing_address / required
      Previous value: -[
      -  "line1",
      -  "line2",
      -  "locality",
      -  "region",
      -  "postal_code",
      -  "country_code"
      -]New value: +[
      +  "line1",
      +  "locality",
      +  "region",
      +  "postal_code",
      +  "country_code"
      +]
    • addedInput schema / properties / cards / items / properties / return_address / properties / mailing_address / properties / line2 / default
      Added value: +""
    • addedInput schema / properties / cards / items / properties / return_address / properties / mailing_address / properties / line2 / description
      Added value: +"Optional second line, such as an apartment or suite. Omitted means empty."
    • changedInput schema / properties / cards / items / properties / return_address / properties / mailing_address / required
      Previous value: -[
      -  "line1",
      -  "line2",
      -  "locality",
      -  "region",
      -  "postal_code",
      -  "country_code"
      -]New value: +[
      +  "line1",
      +  "locality",
      +  "region",
      +  "postal_code",
      +  "country_code"
      +]
    • 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."
  6. Changed9 schema fields changed
    • addedInput schema / properties / cards / items / properties / format / description
      Added value: +"Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
    • changedInput schema / properties / cards / items / properties / message_font / enum
      Previous value: -[
      -  "serif",
      -  "sans_serif",
      -  "old_school"
      -]New value: +[
      +  "serif",
      +  "sans_serif",
      +  "old_school",
      +  "handwriting"
      +]
    • 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"
      +  },
      +  "order_access_token": {
      +    "pattern": "^[A-Za-z0-9_-]{43}$",
      +    "type": "string"
      +  },
      +  "payment_required": {
      +    "type": "boolean"
      +  },
      +  "reused": {
      +    "type": "boolean"
      +  },
      +  "review_url": {
      +    "format": "uri",
      +    "type": "string"
      +  }
      +}
    • removedOutput schema / properties / data / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • addedOutput schema / properties / data / required
      Added value: +[
      +  "order",
      +  "order_access_token",
      +  "review_url"
      +]
    • 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"
      +]
  7. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare openWorldHint and idempotentHint, and the description reinforces them with concrete mechanics: idempotency via request_id + unchanged cards + exact token, the lost-first-response recovery path, per-recipient-country pricing, and validation errors that reference zero-based indices without echoing private content. It also discloses that images render only when requested and that the token is a private capability that cannot be replaced.

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?

Purpose is front-loaded in the first clause and every sentence carries operational content, including the 4-MiB bound that the schema omits. Slightly dense and repetitive around token preservation, which is mentioned in two separate places.

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

Completeness5/5

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

For a high-complexity, 500-item batch mutation with nested card objects, the description covers the non-obvious essentials: no financial authorization, idempotent retry contract, token custody, preview gating and error reporting format. Return-value detail is redundant given the output schema, but nothing an agent needs is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents request_id, order_access_token, cards and pricing by country. The description adds only framing (500-card/4-MiB limits are technical, do not group purchases by occasion) rather than new parameter mechanics, so it sits at the baseline.

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?

Opens with a specific verb and resource plus scope: "Prepare one unpaid purchase of 1 to 500 cards" with mixed artwork, formats, messages and recipients in a single cards array. It is immediately distinguishable from pay_order, revise_order and cancel_order because it states explicitly that no charge or mailing is authorized.

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 clear conditional guidance: preview_card when preview_available is true, reusing the token/request_id for retries, and issuing a new request_id for a genuinely new unpaid purchase. It never explicitly names pay_order as the follow-up that performs the charge, leaving that inference to the reader.

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