Paddock Cards

Compose a private card

compose_private_card

Idempotent

Create a new immutable card face from this scope’s artwork, logo or QR URL. Requires at least one of those inputs; a QR-only face needs no upload. Returns design_key and design_version for prepare_order or revise_order. Personal message, recipient and mailing details are supplied in the order’s cards array. Reuse an existing composition when no new face is needed.

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": {
      "scope_id": "<scope_id>",
      "order_access_token": "<order_access_token>",
      "composition_id": "<composition_id>",
      "title": "<title>"
    },
    "name": "compose_private_card"
  }
}

Input Schema

Name	Required	Description
`title`	Yes	Short private name for this card, shown to the buyer only.
`qr_url`	No	Full HTTP(S) destination printed as a QR code; Paddock does not fetch it. A QR-only card needs no uploaded asset.
`scope_id`	Yes	Exact scope_id returned by open_private_content. All supplied asset IDs must belong to this scope.
`logo_asset_id`	No	asset_id with kind logo from read_private_content in this scope. Optional when artwork_asset_id or qr_url is supplied.
`composition_id`	Yes	Caller-generated UUID for this composition. Retrying with the same ID and identical fields returns the same card (reused: true); the same ID with different fields is CONFLICT, so use a new UUID for a different card.
`artwork_asset_id`	No	asset_id with kind artwork from read_private_content in this scope. Supply at least one artwork asset, logo asset or QR URL.
`order_access_token`	Yes	Exact private order_access_token returned by open_private_content for this scope. Keep it private and never invent one.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 29, 2026

addedInput schema / properties / artwork_asset_id / description

Added value: +"asset_id with kind artwork from read_private_content in this scope. Supply at least one artwork asset, logo asset or QR URL."

addedInput schema / properties / logo_asset_id / description

Added value: +"asset_id with kind logo from read_private_content in this scope. Optional when artwork_asset_id or qr_url is supplied."

changedInput schema / properties / order_access_token / description

Previous value: -"The private capability returned by open_private_content. Never invent one."New value: +"Exact private order_access_token returned by open_private_content for this scope. Keep it private and never invent one."

changedInput schema / properties / qr_url / description

Previous value: -"HTTP(S) destination printed as a QR code. Not fetched."New value: +"Full HTTP(S) destination printed as a QR code; Paddock does not fetch it. A QR-only card needs no uploaded asset."

addedInput schema / properties / scope_id / description

Added value: +"Exact scope_id returned by open_private_content. All supplied asset IDs must belong to this scope."

AddedOct 29, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare this as a non-read-only, non-destructive, idempotent, closed-world operation, and the description usefully adds that the resulting card face is immutable and that it returns design_key/design_version for later order calls. It also clarifies what the tool does NOT handle: personalization and mailing data. It does not restate retry/conflict semantics, but the schema's composition_id description already carries those.

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

Conciseness5/5

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

Four short sentences, front-loaded with the action and prerequisite, followed by return values, then the boundary and reuse case. Nothing is redundant or padded.

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?

An output schema exists and annotations cover the safety profile, and the description still supplies the pieces the schema cannot: the input prerequisite, the immutability trait, downstream use of the returned keys, and where order-level data lives. Nothing an agent needs before calling is missing.

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 the baseline is 3; the description still adds a cross-parameter constraint ('at least one of those inputs') and clarifies that the QR URL is printed verbatim and needs no upload. It does not add format-level detail beyond the schema, which is a minor gap.

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: creates an immutable card face from scope artwork, logo, or QR URL. It also names the downstream consumers (prepare_order, revise_order), so an agent can place it in the workflow and distinguish it from preview_card and prepare_order without opening schemas.

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

Usage Guidelines4/5

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

Gives a clear prerequisite ('Requires at least one of those inputs; a QR-only face needs no upload') and an explicit when-not ('Reuse an existing composition when no new face is needed'), plus a boundary that order-level fields such as personal message, recipient, and mailing details go in the order's cards array. It never names preview_card as the alternative for inspecting a face before committing, so the sibling routing is not exhaustive.

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?