AI Storefront
Browse the documentation

Value-Retention Curve

How one model-year cohort held its asking price over 12 months, with the odometer beside it and the whole market for comparison.

This is the technical reference. For the price, a rendered sample and answers to common questions, see the Value-Retention Curve product page.

At a glance

Price $4.99 for one cohort; a batch is $0.99 per cohort delivered. Minimum $4.99 per run. A batch is quoted before it runs: the first call returns a total and charges nothing.
Tool name generate_value_retention_curve
Scope reports:value-retention-curve
Built for Auto Lender, Insurance Adjuster, Market Researcher

What it does

The value-retention curve for one model-year cohort (year, make and model, optionally trim): twelve months of sold-market data, month by month, with the units that left dealer websites, the median asking price at exit, the median odometer and the median days to sell, pinned to ONE model year so the curve moves only when values move, never when the mix of vintages moves. States the retention (the last month's median as a percent of the first), the odometer drift in miles, the low point of the window and the units, and draws the whole used market (every vehicle of the same inventory type, nationally) as a comparison line rebased to the same start. With a powertrain (e.g. BEV) the cohort is filtered to it and a combustion comparator is added: the same nameplate on combustion when it has sales, else every vehicle of the same model year on combustion, stated on the report. National by default; a US state narrows the cohort. From the Sold Summary API: a sale is inferred when a listing leaves a dealer website, every price is the advertised asking price at exit (never a negotiated transaction price), and the cars in a cohort age and add miles across the window, so it is a cohort trajectory, not same-car depreciation and not a residual forecast. PORTFOLIO RETENTION SHEET: paste cohorts instead (one per line: year make model, optional trim) and every cohort gets its own row (first and last median, retention, odometer drift, units) in one table sorted lowest retention first, with a CSV of every row and the whole-market retention beside it. Use when a lender, insurer or analyst asks how a specific model year is holding value, what residual or advance-rate cushion a cohort needs, whether an EV cohort is eroding faster than combustion, or which cohorts in a book are losing value fastest. Do NOT use to value one VIN (use Vehicle Valuation Report), to pick where to remarket units (use Remarketing Liquidity Map), or for a seasonal buy and sell timing question (use Seasonal Buy-Sell Calendar). The sold data has state grain, not ZIP or radius. PRICING: $4.99 for one cohort. A portfolio sheet is metered at $0.99 per cohort with a curve, with a $4.99 minimum, up to 200 cohorts per run; lines that cannot be read or that have no sold data are not billed. A sheet that could cost more than $4.99 requires cost confirmation: call first WITHOUT confirm_cost_usd for an up-to quote (this charges nothing), then again with confirm_cost_usd set to the quoted cap once the user approves.

Arguments

Argument What it is Example
year Recommended Model year of the cohort (the 2022 in "2022 Toyota Camry"). Needed for one cohort; leave blank when you paste cohorts. A curve is pinned to one model year. 2022
make Recommended Make (e.g. Toyota). Needed for one cohort. Toyota
model Recommended Model (e.g. Camry). Needed for one cohort. Camry
trim Optional Trim (e.g. XSE) to pin the cohort to one trim. Leave blank for every trim of the model. XSE
state Optional US state, as a 2-letter code (e.g. TX), to narrow the cohort to one state. Leave blank for the national curve. The comparison line is always the whole US market. TX
inventory_type Optional Which market: used (the default), new, or certified pre-owned. used
months Optional Months in the curve, 2 to 12, ending at the latest data month. 12 by default. 12
powertrain_type Optional Filter the cohort to one powertrain (BEV, PHEV, HEV, MHEV or Combustion) and pair it against combustion: the same nameplate on combustion when it has sales, else every vehicle of the same model year on combustion. BEV
cohorts Optional A portfolio sheet instead of one cohort: one cohort per line as "year make model" with an optional trim (e.g. "2022 Toyota Camry XSE"). Up to 200. State, inventory type and months apply to every line. Metered at $0.99 per cohort with a curve, with a $4.99 minimum. 2022 Toyota Camry XSE
confirm_cost_usd Optional Only for a sheet that could cost more than the $4.99 floor. After quoting the user the up-to cap and getting approval, call again with this set to the quoted cap. Charged only for cohorts with a curve, never above the cap. Leave empty on the first (quote) call. 39.6

What comes back

Asking for it in a chat client

Show the 12-month value-retention curve for 2022 Toyota Camrys nationally

Run a portfolio retention sheet for these 40 cohorts (paste list)

Running it from a backend

Grant an agent the reports:value-retention-curve scope, then call the tool over MCP:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_value_retention_curve",
    "arguments": {
      "year": 2022,
      "make": "Toyota",
      "model": "Camry",
      "inventory_type": "used",
      "months": 12
    }
  }
}

See Server-side access for the token exchange and how to read the response.