Skip to main content
Glama

MTG Tools — Commander deck review and mana bases

Search Commander-legal cards

search_cards
Read-only

Search Commander-legal paper cards by name, role, or Scryfall syntax. Supports color identity, mana value, card type, price, and commander interaction filters. Returns rules text, commander fit when a commander is supplied, and a legal same-role alternative when available. Prices link to TCGplayer. Supports comparing printings, estimated totals by quantity, and previewing a cart for explicitly selected cards with owned copies deducted.

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": {
      "query": "<query>"
    },
    "name": "search_cards"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNo
limitNo
queryYes
colorsNo
finishNoPreferred finish. Carry this into follow-up searches.
qaTestNoInternal QA only: set true when the user explicitly says this is our test run. Excludes the call from usage/revenue statistics. Omit for normal player requests.
cardTypeNo
quantityNoShow the estimated price for this many copies of each card.
exactNameNo
printingsNoCompare up to two priced printings per result. Use for an exact card or a shortlist.
similarToNoExact card name from a previous result when the player asks for similar cards.
maxPriceUsdNo
compareNamesNoShow two or three exact names side by side from the current search, keeping its existing filters.
groupByPriceNoGroup the shortlist into under $1, $1–$4.99, $5 and up, and price unavailable.
maxManaValueNo
minManaValueNo
commanderNameNoOptional exact commander name for conditional, curated interaction explanations.
excludedNamesNo
searchContextNoSigned context from the previous result’s followUp.toolCall.arguments.searchContext for requests for more matching cards or a related search. Copy it unchanged. Omit for a new, unrelated search.
shoppingSelectionNoUse only for a user-confirmed shopping selection. Repeat the relevant search, pass exact names and quantities, and include owned copies when known. To edit a selection, pass the revised list.
commanderInteractionsNoRestrict the search to the curated interaction candidate for commanderName, intersecting all other search filters. Requires commanderName. Coverage is limited; no result does not mean no synergy.

Output Schema

NameRequiredDescriptionDefault
cardsYes
followUpNo
warningsNo
alternativeNo
priceSourceNo
shoppingCartNo
searchContextNo
answerMarkdownYesComplete linked-price answer for clients that do not render the native result card.
priceCheckedAtNo
shoppingContextNo
affiliateDisclosureNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changed
    • addedInput schema / properties / compareNames
      Added value: +{
      +  "description": "Show two or three exact names side by side from the current search, keeping its existing filters.",
      +  "items": {
      +    "maxLength": 150,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 3,
      +  "minItems": 2,
      +  "type": "array"
      +}
    • addedInput schema / properties / finish
      Added value: +{
      +  "description": "Preferred finish. Carry this into follow-up searches.",
      +  "enum": [
      +    "nonfoil",
      +    "foil",
      +    "etched"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / groupByPrice
      Added value: +{
      +  "description": "Group the shortlist into under $1, $1–$4.99, $5 and up, and price unavailable.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / minManaValue
      Added value: +{
      +  "maximum": 20,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / printings
      Added value: +{
      +  "description": "Compare up to two priced printings per result. Use for an exact card or a shortlist.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / quantity
      Added value: +{
      +  "description": "Show the estimated price for this many copies of each card.",
      +  "maximum": 100,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / shoppingSelection
      Added value: +{
      +  "description": "Use only for a user-confirmed shopping selection. Repeat the relevant search, pass exact names and quantities, and include owned copies when known. To edit a selection, pass the revised list.",
      +  "items": {
      +    "properties": {
      +      "name": {
      +        "maxLength": 150,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "owned": {
      +        "maximum": 100,
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "quantity": {
      +        "maximum": 100,
      +        "minimum": 1,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "quantity"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 20,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedOutput schema / properties / alternative / properties / estimatedQuantityCents
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / alternative / properties / exactMatch
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / alternative / properties / priceTier
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / alternative / properties / printingLabel
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / alternative / properties / quantity
      Added value: +{
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / alternative / properties / withinPriceCap
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / cards / items / properties / estimatedQuantityCents
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / cards / items / properties / exactMatch
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / cards / items / properties / priceTier
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / cards / items / properties / printingLabel
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / cards / items / properties / quantity
      Added value: +{
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / cards / items / properties / withinPriceCap
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / priceCheckedAt
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / priceSource
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / shoppingCart
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "estimatedCents": {
      +      "anyOf": [
      +        {
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "lines": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "cardName": {
      +            "type": "string"
      +          },
      +          "estimatedCents": {
      +            "anyOf": [
      +              {
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "quantity": {
      +            "exclusiveMinimum": 0,
      +            "maximum": 9007199254740991,
      +            "type": "integer"
      +          }
      +        },
      +        "required": [
      +          "cardName",
      +          "quantity",
      +          "estimatedCents"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "message": {
      +      "type": "string"
      +    },
      +    "missing": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "quantity": {
      +      "exclusiveMinimum": 0,
      +      "maximum": 9007199254740991,
      +      "type": "integer"
      +    },
      +    "trackedUrl": {
      +      "anyOf": [
      +        {
      +          "format": "uri",
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "url": {
      +      "anyOf": [
      +        {
      +          "format": "uri",
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    }
      +  },
      +  "required": [
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / shoppingContext
      Added value: +{
      +  "additionalProperties": {},
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
  2. Changed2 schema fields changed
    • addedInput schema / properties / similarTo
      Added value: +{
      +  "description": "Exact card name from a previous result when the player asks for similar cards.",
      +  "maxLength": 150,
      +  "minLength": 2,
      +  "type": "string"
      +}
    • addedOutput schema / properties / followUp / properties / nextSearchLabel
      Added value: +{
      +  "type": "string"
      +}
  3. Changed2 schema fields changed
    • addedOutput schema / properties / alternative
      Added value: +{
      +  "additionalProperties": {},
      +  "properties": {
      +    "buyLink": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "affiliateDisclosure": {
      +          "type": "string"
      +        },
      +        "directAffiliateUrl": {
      +          "format": "uri",
      +          "type": "string"
      +        },
      +        "label": {
      +          "type": "string"
      +        },
      +        "matching": {
      +          "type": "string"
      +        },
      +        "url": {
      +          "format": "uri",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "label",
      +        "url",
      +        "directAffiliateUrl",
      +        "matching",
      +        "affiliateDisclosure"
      +      ],
      +      "type": "object"
      +    },
      +    "commanderFit": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "name": {
      +      "type": "string"
      +    },
      +    "priceCents": {
      +      "anyOf": [
      +        {
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "Estimated price in USD cents."
      +    },
      +    "priceFinish": {
      +      "anyOf": [
      +        {
      +          "enum": [
      +            "nonfoil",
      +            "foil",
      +            "etched"
      +          ],
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "priceMarkdown": {
      +      "description": "Estimated price as a Markdown link to the shopping destination.",
      +      "type": "string"
      +    },
      +    "sourceUrl": {
      +      "format": "uri",
      +      "type": "string"
      +    },
      +    "text": {
      +      "type": "string"
      +    },
      +    "trackedBuyUrl": {
      +      "anyOf": [
      +        {
      +          "format": "uri",
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "type": {
      +      "type": "string"
      +    },
      +    "url": {
      +      "description": "Direct affiliate destination URL.",
      +      "format": "uri",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "priceMarkdown",
      +    "url"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / cards / items / properties / commanderFit
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
  4. Changed1 schema field changed
    • changedInput schema / properties / searchContext / description
      Previous value: -"Optional opaque context from a preceding card search for attributing a related request."New value: +"Signed context from the previous result’s followUp.toolCall.arguments.searchContext for requests for more matching cards or a related search. Copy it unchanged. Omit for a new, unrelated search."
  5. Changed4 schema fields changed
    • changedInput schema / properties / searchContext / description
      Previous value: -"Return the opaque searchContext from the preceding card search when the user requests a follow-up. Never invent it or run follow-ups automatically."New value: +"Optional opaque context from a preceding card search for attributing a related request."
    • changedOutput schema / properties / cards / items / properties / priceCents / description
      Previous value: -"Numeric USD-cent estimate for calculations; display priceMarkdown as the clickable price."New value: +"Estimated price in USD cents."
    • changedOutput schema / properties / cards / items / properties / priceMarkdown / description
      Previous value: -"Ready-to-display clickable price. Preserve this complete Markdown link, including the affiliate wrapper, rather than replacing it with plain text."New value: +"Estimated price as a Markdown link to the shopping destination."
    • changedOutput schema / properties / cards / items / properties / url / description
      Previous value: -"Exact direct affiliate destination; retain its complete URL."New value: +"Direct affiliate destination URL."
  6. Changed1 schema field changed
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +{}
  7. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "affiliateDisclosure": {
      +      "type": "string"
      +    },
      +    "answerMarkdown": {
      +      "description": "Complete linked-price answer for clients that do not render the native result card.",
      +      "type": "string"
      +    },
      +    "cards": {
      +      "items": {
      +        "additionalProperties": {},
      +        "properties": {
      +          "buyLink": {
      +            "additionalProperties": {},
      +            "properties": {
      +              "affiliateDisclosure": {
      +                "type": "string"
      +              },
      +              "directAffiliateUrl": {
      +                "format": "uri",
      +                "type": "string"
      +              },
      +              "label": {
      +                "type": "string"
      +              },
      +              "matching": {
      +                "type": "string"
      +              },
      +              "url": {
      +                "format": "uri",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "label",
      +              "url",
      +              "directAffiliateUrl",
      +              "matching",
      +              "affiliateDisclosure"
      +            ],
      +            "type": "object"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "priceCents": {
      +            "anyOf": [
      +              {
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "description": "Numeric USD-cent estimate for calculations; display priceMarkdown as the clickable price."
      +          },
      +          "priceFinish": {
      +            "anyOf": [
      +              {
      +                "enum": [
      +                  "nonfoil",
      +                  "foil",
      +                  "etched"
      +                ],
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "priceMarkdown": {
      +            "description": "Ready-to-display clickable price. Preserve this complete Markdown link, including the affiliate wrapper, rather than replacing it with plain text.",
      +            "type": "string"
      +          },
      +          "sourceUrl": {
      +            "format": "uri",
      +            "type": "string"
      +          },
      +          "text": {
      +            "type": "string"
      +          },
      +          "trackedBuyUrl": {
      +            "anyOf": [
      +              {
      +                "format": "uri",
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "type": {
      +            "type": "string"
      +          },
      +          "url": {
      +            "description": "Exact direct affiliate destination; retain its complete URL.",
      +            "format": "uri",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "name",
      +          "priceMarkdown",
      +          "url"
      +        ],
      +        "type": "object"
      +      },
      +      "maxItems": 20,
      +      "type": "array"
      +    },
      +    "followUp": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "nextSearch": {
      +          "additionalProperties": {},
      +          "propertyNames": {
      +            "type": "string"
      +          },
      +          "type": "object"
      +        },
      +        "prompt": {
      +          "type": "string"
      +        },
      +        "toolCall": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "arguments": {
      +              "additionalProperties": {},
      +              "propertyNames": {
      +                "type": "string"
      +              },
      +              "type": "object"
      +            },
      +            "name": {
      +              "const": "search_cards",
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "arguments"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "searchContext": {
      +      "type": "string"
      +    },
      +    "warnings": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "cards",
      +    "answerMarkdown"
      +  ],
      +  "type": "object"
      +}
  8. Changed2 schema fields changed
    • addedInput schema / properties / commanderInteractions
      Added value: +{
      +  "description": "Restrict the search to the curated interaction candidate for commanderName, intersecting all other search filters. Requires commanderName. Coverage is limited; no result does not mean no synergy.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / commanderName
      Added value: +{
      +  "description": "Optional exact commander name for conditional, curated interaction explanations.",
      +  "maxLength": 150,
      +  "minLength": 2,
      +  "type": "string"
      +}
  9. Changed1 schema field changed
    • addedInput schema / properties / searchContext
      Added value: +{
      +  "description": "Return the opaque searchContext from the preceding card search when the user requests a follow-up. Never invent it or run follow-ups automatically.",
      +  "maxLength": 400,
      +  "type": "string"
      +}
  10. Changed5 schema fields changed
    • addedInput schema / properties / cardType
      Added value: +{
      +  "enum": [
      +    "creature",
      +    "instant",
      +    "sorcery",
      +    "artifact",
      +    "enchantment",
      +    "planeswalker",
      +    "land",
      +    "battle"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / exactName
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / excludedNames
      Added value: +{
      +  "items": {
      +    "maxLength": 150,
      +    "minLength": 1,
      +    "pattern": "^[^\\u0000-\\u001f]+$",
      +    "type": "string"
      +  },
      +  "maxItems": 30,
      +  "type": "array"
      +}
    • addedInput schema / properties / maxManaValue
      Added value: +{
      +  "maximum": 20,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / sort
      Added value: +{
      +  "enum": [
      +    "edhrec",
      +    "usd"
      +  ],
      +  "type": "string"
      +}
  11. Changed1 schema field changed
    • addedInput schema / properties / qaTest
      Added value: +{
      +  "const": true,
      +  "description": "Internal QA only: set true when the user explicitly says this is our test run. Excludes the call from usage/revenue statistics. Omit for normal player requests.",
      +  "type": "boolean"
      +}
  12. Changed2 schema fields changed
    • addedInput schema / properties / colors / maxLength
      Added value: +30
    • changedInput schema / properties / colors / pattern
      Previous value: -"^[WUBRG]{0,5}$"New value: +"^(?:C|[WUBRG, ]*)$"
  13. Added

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already establish read-only, open-world, non-destructive behavior, and the description adds useful context beyond them: rules text, commander fit, same-role alternatives, TCGplayer price links, print comparisons, quantity totals, and a read-only cart preview with owned copies deducted. It does not discuss price freshness, pagination, or limitations beyond commander interaction coverage, but it adds substantial behavioral detail.

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?

The description front-loads the core search action and then summarizes filters and advanced modes in a compact paragraph. It is dense but mostly efficient for a complex tool, though mixing search, comparison, pricing, and cart-preview behaviors in one paragraph slightly weakens structure.

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

Completeness4/5

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

For a 21-parameter tool with annotations and an output schema, the description covers purpose, major filters, return highlights, and advanced comparison/cart modes. Some parameter-level mechanics are delegated to schema descriptions, but the core information needed to select and invoke the search is present.

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 52%, and the description adds high-level meaning for query modes and filter families such as color identity, mana value, card type, price, and commander interactions. It does not clarify several exposed parameters including sort, limit, exactName, excludedNames, and numeric bounds, so it only partially compensates for the schema gaps.

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: 'Search Commander-legal paper cards.' It also names the query modes (name, role, Scryfall syntax) and filters, making the tool's scope concrete and distinguishable from commander/deck-focused siblings.

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

Usage Guidelines3/5

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

The opening sentence implies use for card lookups, and the description lists supported filters and advanced modes. However, it gives no explicit when-to-use/when-not guidance or named alternatives, so usage is implied rather than fully directed.

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