LLM integration

Expose the API as a tool

Define one or two tools that map directly onto the endpoints — a search_cards tool over /v1/cards/search is enough to start. Return a trimmed projection so the model grounds on exactly the fields you want it to cite. The OpenAPI 3.1 spec can generate these tool schemas for you.

{
  "name": "search_cards",
  "description": "Find trading cards and their current prices by name, game, or set.",
  "input_schema": {
    "type": "object",
    "properties": {
      "q":    { "type": "string", "description": "Card name to search for" },
      "game": { "type": "string", "enum": ["pokemon", "pokemon-jp", "mtg", "yugioh", "onepiece", "lorcana", "swu", "fab"] },
      "set":  { "type": "string", "description": "Set slug, e.g. obsidian-flames" }
    },
    "required": ["q"]
  }
}

Recommended retrieval flow

1. 1Classify intent — lookup, compare, price trend, or grade-spread.
2. 2Resolve the entity — call /v1/cards/search with strict filters (game, set) to pin the exact card id.
3. 3Fetch authoritative data — call /v1/cards/:id for current prices, and /v1/cards/:id/history (paid plans) for trends.
4. 4Ground the answer — have the model summarize only the retrieved fields, with source, condition/grade, and timestamp — never inferred numbers.

Grounding template

A system prompt that forces the model to stay inside the tool data and cite its sources:

Answer only from the data returned by the tools.
If a price field is missing or null, say "not available" — never estimate.
Always cite the source (tcgplayer / ebay), the condition or grade,
and the as_of timestamp for any price you state.
Never invent card names, sets, grades, or prices.

Cite real fields, not vibes

Give the model the exact field it's quoting so answers are verifiable:

• •Raw price: prices.raw.near_mint.tcgplayer.market — say “TCGplayer market, Near Mint”.
• •Sold average: prices.raw.near_mint.ebay.avg_7d — say “eBay 7-day average”.
• •Graded: prices.graded.psa["10"] — say “PSA 10”.
• •Freshness: cite last_price_update so users know how current the figure is.

See the full prices object reference for every field and what it means.

Caching & freshness

• •Cache the resolved id for a normalized query so repeat questions skip the search step.
• •Cache card-detail responses with a short TTL (e.g. 5–15 minutes) to stay well under your rate limit.
• •Surface last_price_update in the answer when discussing trends or recent moves.