Agent Playbook: How AI Agents Should Use SoldComps for eBay Sold Prices

This is the page to read before using SoldComps as a tool. It applies to the MCP tool get_sold_comps and to the REST endpoint GET /v1/sold. It's written for agents and for the developers writing their instructions; the block at the end is ready to paste into a system prompt.

Connecting a client first? See Claude, ChatGPT, the Claude API, or OpenAI and Vercel AI SDK agents.

#1. When to call

Call it when the user asks about the value of one specific item:

• "What's this worth?", "What does X sell for?", "What should I list it at?"
• "Is $200 a good price for a used X?"
• "What should I offer for this?"

Don't call it from memory or guesswork. Resale prices move week to week, and a tool result is evidence you can cite.

Don't call get_sold_comps for:

• General questions about selling, eBay fees or how comps work. Use search_guides or what_are_sold_comps.
• Several items in one query. Make one call per item.
• New retail prices. SoldComps reports what buyers paid on eBay, mostly second-hand.

#2. Write the query like an eBay search

The query becomes an eBay search, then gets filtered. It decides the answer.

• Include what changes the price: brand and model, reference or part number, storage, size, edition, set and card number, grade.
• Quote exact phrases: "psa 10", "first edition".
• Exclude junk with a minus: -lot, -broken, -box, -case.
• Drop filler: "vintage", "rare", "nice", "authentic" rarely help.
• One item per call.
• Don't invent details. If the user didn't give the size or storage, don't guess one; ask, or search without it and say the range may be wide.

Matching is strict. Every number in the query must appear in the listing title as a whole number, quoted phrases must appear exactly, at least 80% of the other words must appear, and minus words exclude a sale. Loose padding results that eBay adds don't count.

Limits: MCP queries are 3 to 80 characters and up to 12 words. REST q is 2 to 200 characters.

#3. Choose condition and marketplace

• Condition: set it when the item's condition is known. A search without it mixes new and used sales and can move the median a lot. MCP takes new or used; REST also takes open_box, refurbished and for_parts.
• Marketplace: eBay US by default (us / EBAY_US, USD). Use UK (uk / EBAY_GB, GBP) or Germany (de / EBAY_DE, EUR) when the user is there or asks in that currency. Don't convert currencies unless asked, and say which marketplace the figures come from.

#4. Read the stats

What comes back (MCP field / REST field):

How to use them:

• Lead with the median. It's the middle sale, so a few odd sales don't drag it. Never compute or report an average instead. Median vs average sold price explains why.
• Give the middle half as the range. Half of all counted sales fell between p25 and p75. That's the realistic range, not min to max.
• Say how many sales it's based on, and the date range when you have it (sales_dated in MCP, sold_at on items in REST).
• Trust the exclusions. Lots, for-parts sales, empty boxes, replicas, cheap accessories, outliers and hidden Best Offer prices are already left out of the stats. In REST, flags on each item says why it was excluded.
• Use the quartiles for decisions. p25 is a quick-sale price (a sensible floor for buy offers); the median is a fair listing price. Pawn shop sold comps and Sold comps for resellers show the math.

#Confidence

Flag low confidence when either is true:

• Fewer than 10 counted sales. The median is a rough guide. See how many sold comps you need.
• p75 more than about 1.5x p25. Buyers paid very different prices, which usually means the query mixes versions, sizes or conditions.

When confidence is low, say so in plain words and suggest the detail that would sharpen the query. Don't hide it behind a confident number.

#5. Handle no results

median is null (or count is 0) when no clean sales matched in the last 90 days.

1. Check the query for a wrong number or an over-specific phrase.
2. Retry once with a broader query: drop a word, remove quotes, or drop the condition.
3. If there's still nothing, tell the user nothing comparable sold on that marketplace in 90 days. Don't fill the gap with a guess.

#6. Control cost

• MCP without a key: free, limited to 5 lookups a day and 20 a month per IP address. Cloud clients (claude.ai, ChatGPT, hosted APIs) share their provider's addresses, so the allowance can run out early.
• MCP with a key: 20 credits plus 1 per sale listed, and it lists at most 20, so at most 40 credits.
• REST: 20 credits plus 1 per sale returned. Set limit on purpose. Stats use every matching sale (up to 200) whatever limit is, so:
  • limit=1 (21 credits): you only need the stats.
  • limit=10 to 20 (30 to 40 credits): stats plus a few sales to cite. Right for most answers.
  • limit=200 (220 credits): only when you need every sale.
• Don't repeat a lookup you already made in this conversation or batch. Every successful search is billed, including repeats.
• Check the balance for free with GET /v1/usage. Every /v1/sold response also reports credits.charged and credits.remaining.

Plans and prepaid credits: pricing.

#7. Errors and retries

REST errors return an error.code. Errors are never billed.

The MCP tool reports problems as text in the result: a free-limit or out-of-credits message (tell the user, suggest a key at /signup), "paused for today" (daily capacity), or "temporarily unavailable" (retry once after a short wait).

#8. Cite the source

• Say where the numbers come from: completed eBay sales on that marketplace in the last 90 days, via SoldComps.
• Link https://www.soldcomps.io (the MCP result includes a source URL; use it).
• Link individual eBay listings when you quote specific sales.
• Give the sales date range, not "today's price".
• SoldComps is independent and not affiliated with eBay. Don't present it as eBay data from eBay itself.

A good answer, with placeholders in angle brackets:

Used Nintendo Switch OLEDs sold for a median of <median> on eBay US over the last
90 days, based on <counted> sales. Half sold between <p25> and <p75>.
Source: SoldComps (https://www.soldcomps.io), from completed eBay sales.

#9. What not to claim

• Not a guaranteed price. The median is what buyers paid recently, not what this item will fetch.
• Not an appraisal or authentication. Listings can't prove an item is genuine or in the stated condition.
• Not up to the second. Results cover the last 90 days and can be cached for up to 12 hours.
• Not asking prices. These are completed sales. Don't mix in active listings.
• No invented numbers. If the tool didn't return it, don't state it. No averages, no made-up sale counts, no conversions you didn't do.

#10. Paste this into your agent's instructions

You can look up eBay sold comps (completed sales, last 90 days) with SoldComps.
When the user asks what a specific item is worth, sells for, or should be priced at:
1. Call get_sold_comps (or GET /v1/sold) once per item with an eBay-style query:
   model or reference number, size, storage, grade; quote exact phrases ("psa 10");
   exclude bundles and junk with -lot, -broken. Set condition when known. Use site
   uk/EBAY_GB or de/EBAY_DE for UK or German users. On REST, set limit=10.
2. Answer with the median sold price, the middle half (p25 to p75) and the number
   of counted sales, plus the date range. Never report an average.
3. If fewer than 10 sales were counted or p75 is more than about 1.5x p25, say
   confidence is low and suggest what would sharpen the query.
4. If nothing matched, retry once with a broader query, then say nothing comparable
   sold. Don't guess.
5. On errors: wait and retry 429 and 502; stop and tell the user on 402 or
   daily_capacity_reached. Errors are never billed.
6. Cite SoldComps (https://www.soldcomps.io) and link eBay listings you quote.
   Never call the median a guaranteed price or an appraisal.

#Reference

• REST parameters, fields, flags and errors: API docs. OpenAPI spec: /openapi.json. Every page and post also has a markdown twin at its path plus .md, and the site map for LLMs is at /llms.txt.
• MCP server setup and tools: MCP server. Everything for agents: /agents.
• Batch pricing: Price a whole inventory with an AI agent.
• The concept itself, for humans: sold comps.