Skip to main content
Glama

Paddock Cards

Search cards

search_cards
Read-onlyIdempotent

Find ordinary and artist cards by artwork, occasion, format or budget. Returns matches with exact design keys and versions, images, orderability, destination prices and next_cursor. Pass destination_country when known; read pricing_destination and cents_by_destination. Basic physical specifications appear once in format_specs; include_specs adds published details. Public browsing needs no account or key. If results is empty, inspect unmet, constraints and pagination before adjusting filters. Pass the selected design key and version to prepare_order.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_cards"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoCatalog collection: standard for Paddock cards, artist for artist cards, or any for both. Omission means any.
toneNoMood such as warm, cheerful, elegant or gentle. For funny cards, use humor instead.
humorNoHumor filter: none, light or playful selects that reviewed level; funny accepts light and playful. Omit or use any for no explicit humor filter; the query can still request humor.
limitNoMaximum matches in this page, from 1 to 50. Omission returns 3; use next_cursor for more.
queryNoNatural-language artwork request, such as a birthday card with flowers. Can include an occasion, format, color, subject or exclusions. Omit to browse with the other filters.
artistNoPublished artist name or slug, such as one returned in card.artist. Omit to include all artists and standard cards.
cursorNoExact next_cursor from the previous search with the same filters. Omit for the first page; stop when next_cursor is null.
formatNoRequested card format. Omit to use a format named in query, or flat_card_in_envelope when no format is requested. Other formats remain listed on each result.
occasionNoOccasion ID or recognized name, such as birthday or thank_you. Omit to use the query or browse all occasions.
include_specsNoInclude available paper, finish and envelope details. Basic format specifications are always returned. A missing detail is unspecified.
max_price_centsNoBudget per card for the selected format at the destination’s prices.
destination_countryNoRecipient country as a two-letter ISO code, such as US or CA. Prices depend on it: US addresses have agent-channel introductory prices and other countries the standard prices. Omit it to see US prices with each format’s other-destination amount listed; the prepared order prices every card by its own recipient address.
require_printed_textNoFilter verified wording already printed in the artwork. Unknown wording does not match absent or present.
printed_text_containsNoRequired phrase in verified artwork lettering, matched without case sensitivity. This does not search the customizable message.

Output Schema

NameRequiredDescriptionDefault
okYes
dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / artist / description
      Added value: +"Published artist name or slug, such as one returned in card.artist. Omit to include all artists and standard cards."
    • addedInput schema / properties / cursor / description
      Added value: +"Exact next_cursor from the previous search with the same filters. Omit for the first page; stop when next_cursor is null."
    • changedInput schema / properties / format / description
      Previous value: -"Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."New value: +"Requested card format. Omit to use a format named in query, or flat_card_in_envelope when no format is requested. Other formats remain listed on each result."
    • addedInput schema / properties / humor / description
      Added value: +"Humor filter: none, light or playful selects that reviewed level; funny accepts light and playful. Omit or use any for no explicit humor filter; the query can still request humor."
    • addedInput schema / properties / kind / description
      Added value: +"Catalog collection: standard for Paddock cards, artist for artist cards, or any for both. Omission means any."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum matches in this page, from 1 to 50. Omission returns 3; use next_cursor for more."
    • addedInput schema / properties / occasion / description
      Added value: +"Occasion ID or recognized name, such as birthday or thank_you. Omit to use the query or browse all occasions."
    • addedInput schema / properties / query / description
      Added value: +"Natural-language artwork request, such as a birthday card with flowers. Can include an occasion, format, color, subject or exclusions. Omit to browse with the other filters."
  2. Changed6 schema fields changed
    • addedInput schema / properties / destination_country
      Added value: +{
      +  "description": "Recipient country as a two-letter ISO code, such as US or CA. Prices depend on it: US addresses have agent-channel introductory prices and other countries the standard prices. Omit it to see US prices with each format’s other-destination amount listed; the prepared order prices every card by its own recipient address.",
      +  "pattern": "^[A-Z]{2}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / max_price_cents / description
      Added value: +"Budget per card for the selected format at the destination’s prices."
    • addedOutput schema / properties / data / properties / pricing_destination
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "assumed": {
      +      "type": "boolean"
      +    },
      +    "country_code": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "introductory": {
      +      "type": "boolean"
      +    },
      +    "scope": {
      +      "enum": [
      +        "US",
      +        "international"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "scope",
      +    "country_code",
      +    "introductory",
      +    "assumed"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / data / properties / results / items / properties / card / properties / formats / items / properties / cents_by_destination
      Added value: +{
      +  "additionalProperties": {
      +    "maximum": 9007199254740991,
      +    "minimum": 0,
      +    "type": "integer"
      +  },
      +  "propertyNames": {
      +    "enum": [
      +      "US",
      +      "international"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • changedOutput schema / properties / data / properties / results / items / properties / card / properties / formats / items / required
      Previous value: -[
      -  "format",
      -  "cents",
      -  "orderable"
      -]New value: +[
      +  "format",
      +  "cents",
      +  "orderable",
      +  "cents_by_destination"
      +]
    • changedOutput schema / properties / data / required
      Previous value: -[
      -  "schema",
      -  "catalog_revision",
      -  "complete",
      -  "generated_at",
      -  "total",
      -  "next_cursor",
      -  "constraints",
      -  "unmet",
      -  "occasion_resolved",
      -  "artist_resolved",
      -  "currency",
      -  "price_includes",
      -  "policy",
      -  "results",
      -  "format_specs"
      -]New value: +[
      +  "schema",
      +  "catalog_revision",
      +  "complete",
      +  "generated_at",
      +  "total",
      +  "next_cursor",
      +  "constraints",
      +  "unmet",
      +  "occasion_resolved",
      +  "artist_resolved",
      +  "pricing_destination",
      +  "currency",
      +  "price_includes",
      +  "policy",
      +  "results",
      +  "format_specs"
      +]
  3. Changed3 schema fields changed
    • addedInput schema / properties / include_specs
      Added value: +{
      +  "description": "Include available paper, finish and envelope details. Basic format specifications are always returned. A missing detail is unspecified.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / data / properties / format_specs
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Physical specifications per format, stated once per response. A property that is absent is unspecified.",
      +  "properties": {
      +    "detail": {
      +      "enum": [
      +        "basic",
      +        "full"
      +      ],
      +      "type": "string"
      +    },
      +    "formats": {
      +      "additionalProperties": {
      +        "anyOf": [
      +          {
      +            "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"
      +          },
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "artwork_surface": {
      +                "enum": [
      +                  "front",
      +                  "front cover"
      +                ],
      +                "type": "string"
      +              },
      +              "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"
      +              },
      +              "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"
      +            ],
      +            "type": "object"
      +          }
      +        ]
      +      },
      +      "propertyNames": {
      +        "enum": [
      +          "postcard",
      +          "flat_card_in_envelope",
      +          "folded_card_in_envelope"
      +        ],
      +        "type": "string"
      +      },
      +      "required": [
      +        "postcard",
      +        "flat_card_in_envelope",
      +        "folded_card_in_envelope"
      +      ],
      +      "type": "object"
      +    },
      +    "unit": {
      +      "const": "in",
      +      "type": "string"
      +    },
      +    "unspecified_means": {
      +      "type": "string"
      +    },
      +    "version": {
      +      "maxLength": 60,
      +      "minLength": 1,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "version",
      +    "unit",
      +    "detail",
      +    "unspecified_means",
      +    "formats"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / data / required
      Previous value: -[
      -  "schema",
      -  "catalog_revision",
      -  "complete",
      -  "generated_at",
      -  "total",
      -  "next_cursor",
      -  "constraints",
      -  "unmet",
      -  "occasion_resolved",
      -  "artist_resolved",
      -  "currency",
      -  "price_includes",
      -  "policy",
      -  "results"
      -]New value: +[
      +  "schema",
      +  "catalog_revision",
      +  "complete",
      +  "generated_at",
      +  "total",
      +  "next_cursor",
      +  "constraints",
      +  "unmet",
      +  "occasion_resolved",
      +  "artist_resolved",
      +  "currency",
      +  "price_includes",
      +  "policy",
      +  "results",
      +  "format_specs"
      +]
  4. Changed10 schema fields changed
    • addedInput schema / 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 / limit / default
      Previous value: -12New value: +3
    • addedInput schema / properties / tone / description
      Added value: +"Mood such as warm, cheerful, elegant or gentle. For funny cards, use humor instead."
    • changedOutput schema / properties / data / additionalProperties
      Previous value: -{}New value: +false
    • addedOutput schema / properties / data / properties
      Added value: +{
      +  "artist_resolved": {
      +    "type": [
      +      "string",
      +      "null"
      +    ]
      +  },
      +  "catalog_revision": {
      +    "maximum": 9007199254740991,
      +    "minimum": 0,
      +    "type": "integer"
      +  },
      +  "complete": {
      +    "type": "boolean"
      +  },
      +  "constraints": {
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "code": {
      +          "type": "string"
      +        },
      +        "detail": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "code",
      +        "detail"
      +      ],
      +      "type": "object"
      +    },
      +    "type": "array"
      +  },
      +  "currency": {
      +    "const": "usd",
      +    "type": "string"
      +  },
      +  "generated_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"
      +  },
      +  "next_cursor": {
      +    "type": [
      +      "string",
      +      "null"
      +    ]
      +  },
      +  "occasion_resolved": {
      +    "type": [
      +      "string",
      +      "null"
      +    ]
      +  },
      +  "policy": {
      +    "type": "string"
      +  },
      +  "price_includes": {
      +    "anyOf": [
      +      {
      +        "additionalProperties": false,
      +        "properties": {
      +          "postage": {
      +            "type": "boolean"
      +          },
      +          "tax": {
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "postage",
      +          "tax"
      +        ],
      +        "type": "object"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ]
      +  },
      +  "results": {
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "card": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "artist": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "name": {
      +                  "type": [
      +                    "string",
      +                    "null"
      +                  ]
      +                },
      +                "slug": {
      +                  "type": [
      +                    "string",
      +                    "null"
      +                  ]
      +                },
      +                "url": {
      +                  "anyOf": [
      +                    {
      +                      "format": "uri",
      +                      "type": "string"
      +                    },
      +                    {
      +                      "type": "null"
      +                    }
      +                  ]
      +                }
      +              },
      +              "required": [
      +                "name",
      +                "slug",
      +                "url"
      +              ],
      +              "type": "object"
      +            },
      +            "card_id": {
      +              "type": "string"
      +            },
      +            "contains_animals": {
      +              "type": [
      +                "boolean",
      +                "null"
      +              ]
      +            },
      +            "contains_people": {
      +              "type": [
      +                "boolean",
      +                "null"
      +              ]
      +            },
      +            "description": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "status": {
      +                  "enum": [
      +                    "available",
      +                    "unknown"
      +                  ],
      +                  "type": "string"
      +                },
      +                "text": {
      +                  "type": [
      +                    "string",
      +                    "null"
      +                  ]
      +                }
      +              },
      +              "required": [
      +                "status",
      +                "text"
      +              ],
      +              "type": "object"
      +            },
      +            "design": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "key": {
      +                  "type": "string"
      +                },
      +                "version": {
      +                  "exclusiveMinimum": 0,
      +                  "maximum": 9007199254740991,
      +                  "type": "integer"
      +                }
      +              },
      +              "required": [
      +                "key",
      +                "version"
      +              ],
      +              "type": "object"
      +            },
      +            "formats": {
      +              "items": {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "cents": {
      +                    "maximum": 9007199254740991,
      +                    "minimum": 0,
      +                    "type": "integer"
      +                  },
      +                  "format": {
      +                    "enum": [
      +                      "postcard",
      +                      "flat_card_in_envelope",
      +                      "folded_card_in_envelope"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "orderable": {
      +                    "type": "boolean"
      +                  },
      +                  "reason": {
      +                    "enum": [
      +                      "CARD_SAMPLE_ACCEPTANCE_REQUIRED",
      +                      "CARD_ARTWORK_ACCEPTANCE_REQUIRED",
      +                      "ARTIST_PRINT_SETUP_REQUIRED",
      +                      "CATALOG_ARTWORK_UNAVAILABLE",
      +                      "OFFER_EXPIRED",
      +                      "AVAILABILITY_UNVERIFIED"
      +                    ],
      +                    "type": "string"
      +                  }
      +                },
      +                "required": [
      +                  "format",
      +                  "cents",
      +                  "orderable"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "from_cents": {
      +              "anyOf": [
      +                {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "humor": {
      +              "enum": [
      +                "none",
      +                "light",
      +                "playful",
      +                "unknown"
      +              ],
      +              "type": "string"
      +            },
      +            "image": {
      +              "anyOf": [
      +                {
      +                  "format": "uri",
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "kind": {
      +              "enum": [
      +                "standard",
      +                "artist"
      +              ],
      +              "type": "string"
      +            },
      +            "occasion_design_keys": {
      +              "additionalProperties": {
      +                "type": "string"
      +              },
      +              "propertyNames": {
      +                "type": "string"
      +              },
      +              "type": "object"
      +            },
      +            "occasions": {
      +              "items": {
      +                "type": "string"
      +              },
      +              "type": "array"
      +            },
      +            "palette": {
      +              "items": {
      +                "type": "string"
      +              },
      +              "type": "array"
      +            },
      +            "primary_occasion": {
      +              "type": "string"
      +            },
      +            "printed_text": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "note": {
      +                  "type": "string"
      +                },
      +                "status": {
      +                  "enum": [
      +                    "verified_absent",
      +                    "verified_present",
      +                    "unknown"
      +                  ],
      +                  "type": "string"
      +                },
      +                "text": {
      +                  "type": [
      +                    "string",
      +                    "null"
      +                  ]
      +                }
      +              },
      +              "required": [
      +                "status",
      +                "text"
      +              ],
      +              "type": "object"
      +            },
      +            "subjects": {
      +              "items": {
      +                "type": "string"
      +              },
      +              "type": "array"
      +            },
      +            "subtitle": {
      +              "type": "string"
      +            },
      +            "title": {
      +              "type": "string"
      +            },
      +            "tone": {
      +              "items": {
      +                "enum": [
      +                  "warm",
      +                  "cheerful",
      +                  "playful",
      +                  "elegant",
      +                  "calm",
      +                  "gentle",
      +                  "romantic",
      +                  "festive",
      +                  "nostalgic",
      +                  "whimsical",
      +                  "sincere",
      +                  "celebratory",
      +                  "serene",
      +                  "bold"
      +                ],
      +                "type": "string"
      +              },
      +              "type": "array"
      +            }
      +          },
      +          "required": [
      +            "card_id",
      +            "kind",
      +            "design",
      +            "title",
      +            "primary_occasion",
      +            "occasions",
      +            "description",
      +            "printed_text",
      +            "tone",
      +            "humor",
      +            "subjects",
      +            "palette",
      +            "contains_people",
      +            "contains_animals",
      +            "image",
      +            "formats",
      +            "from_cents"
      +          ],
      +          "type": "object"
      +        },
      +        "match_reasons": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "score": {
      +          "type": "number"
      +        },
      +        "selected_format": {
      +          "anyOf": [
      +            {
      +              "enum": [
      +                "postcard",
      +                "flat_card_in_envelope",
      +                "folded_card_in_envelope"
      +              ],
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        },
      +        "total_cents": {
      +          "anyOf": [
      +            {
      +              "maximum": 9007199254740991,
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        }
      +      },
      +      "required": [
      +        "card",
      +        "selected_format",
      +        "total_cents",
      +        "score",
      +        "match_reasons"
      +      ],
      +      "type": "object"
      +    },
      +    "maxItems": 50,
      +    "type": "array"
      +  },
      +  "schema": {
      +    "const": "paddock.search.compact.v1",
      +    "type": "string"
      +  },
      +  "total": {
      +    "maximum": 9007199254740991,
      +    "minimum": 0,
      +    "type": "integer"
      +  },
      +  "unmet": {
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "code": {
      +          "type": "string"
      +        },
      +        "detail": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "code",
      +        "detail"
      +      ],
      +      "type": "object"
      +    },
      +    "type": "array"
      +  }
      +}
    • removedOutput schema / properties / data / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • addedOutput schema / properties / data / required
      Added value: +[
      +  "schema",
      +  "catalog_revision",
      +  "complete",
      +  "generated_at",
      +  "total",
      +  "next_cursor",
      +  "constraints",
      +  "unmet",
      +  "occasion_resolved",
      +  "artist_resolved",
      +  "currency",
      +  "price_includes",
      +  "policy",
      +  "results"
      +]
    • 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"
      +]
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds substantial context beyond that: public browsing needs no account/key, pricing depends on destination_country, format_specs and include_specs behavior, pagination via next_cursor, and diagnostic fields for empty results. This is unusually rich behavioral disclosure.

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?

The description is front-loaded with the core purpose and then covers return shape, pricing, pagination, empty-result handling, and the prepare_order handoff. Every sentence adds operational value with no filler.

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?

Given 14 optional parameters, rich annotations, and an output schema, the description is complete enough for correct invocation. It explains destination-sensitive pricing, pagination, format specs, empty-result diagnostics, and the downstream prepare_order handoff.

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 description coverage is 100%, so the baseline is 3. The description still adds meaningful semantics beyond schema text, especially for destination_country and pricing_destination/cents_by_destination, format_specs, and include_specs, though it does not explain every one of the 14 parameters.

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

Purpose5/5

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

The description states a specific verb and resource: find ordinary and artist cards by artwork, occasion, format, or budget. It clearly distinguishes the card-search operation and names the downstream prepare_order step, so an agent can identify the tool without opening the schema.

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

Usage Guidelines4/5

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

It gives concrete usage guidance: pass destination_country when known, use include_specs for extra details, inspect unmet/constraints/pagination when results are empty, and pass the selected design key and version to prepare_order. It does not explicitly compare against alternative search tools, but the sibling list contains no direct search alternative and the next-step routing is clear.

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