Paddock Cards

Revise an unpaid order

revise_order

DestructiveIdempotent

Replace an unpaid draft before payment starts. Send the complete desired cards array, including unchanged cards. Validation and replacement are atomic: failure leaves the original draft intact; success cancels it and returns a new order, price, private token and review_url. Use that replacement for later edits, previews and payment; prior payment approval does not carry over. To add private artwork, first reopen the original draft with open_private_content; existing private artwork can be retained. If payment has started or is uncertain, use read_order and resolve it before changing anything. Retry an uncertain revision only with the identical request. The replacement inherits its source’s history access; revision does not link a previously unlinked order.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "request_id": "<request_id>",
      "cards": "<cards>",
      "order_id": "<order_id>",
      "order_access_token": "<order_access_token>",
      "expected_revision": "<expected_revision>"
    },
    "name": "revise_order"
  }
}

Input Schema

Name	Required	Description
`cards`	Yes	One 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.
`order_id`	Yes	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.
`request_id`	Yes	New caller-generated UUID for this replacement, distinct from the original order ID. To recover a lost response, reuse this ID, the complete identical cards array, original order ID, token and expected_revision. Later edits use the returned replacement order.
`expected_revision`	Yes	Current parent order.revision from prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order again before deciding whether to retry. Keep the original revision when recovering an identical replacement request.
`order_access_token`	Yes	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.

Output Schema

Name	Required	Description	Default
`ok`	Yes
`data`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed58 schema fields changedOct 29, 2026
- 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."
```
- 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 again before deciding whether to retry. Keep the original revision when recovering an identical replacement request."
```
- 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."
```
- changedInput schema / properties / request_id / description
```
Previous value: -"A new UUID for this replacement. Reuse it with the identical full cards array and original order capability to recover a lost response. After success, later edits target the returned replacement order."New value: +"New caller-generated UUID for this replacement, distinct from the original order ID. To recover a lost response, reuse this ID, the complete identical cards array, original order ID, token and expected_revision. Later edits use the returned replacement order."
```
- 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."
```
- addedOutput schema / properties / data / properties / replaced_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."
```
AddedOct 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already flag destructive=true and idempotent=true, but the description adds the crucial context behind them: validation and replacement are atomic, failure leaves the original intact, success cancels it, payment approval does not carry over, and history/linking behavior is inherited. This is exactly the kind of non-obvious mutation semantics an agent needs.

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

Conciseness4/5

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

Front-loaded with the core action and atomicity guarantee, then precondition warnings and edge cases. Dense but nearly every sentence carries operational information; a couple of clauses (history access, unlinked orders) are niche but still useful guardrails.

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 destructive, idempotent replacement tool with concurrency control, the description covers atomicity, retry safety, approval carry-over, private-artwork workflow, and staleness handling. Output schema exists, so return-value enumeration is unnecessary, and the description still sketches what comes back.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: cards must be the complete desired array including unchanged cards (not a diff), request_id must be reused for recovery of an identical request, and expected_revision must be preserved on retry. That is behavioral semantics the schema alone does not convey.

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

Purpose5/5

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

States a specific verb and resource: 'Replace an unpaid draft before payment starts.' This immediately distinguishes it from cancel_order, prepare_order, and read_order, and the title reinforces the precondition.

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

Usage Guidelines5/5

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

Explicit when-to-use (unpaid draft, before payment), when-not (payment started or uncertain → use read_order and resolve first), retry discipline (identical request only), and routing to open_private_content for private artwork. No alternatives are left to inference.

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

All Paddock Cards tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?