get_vehicle_value

Repair economics · Read-only

Confirm the valuation provider knows the vehicle — coverage and corroboration, with the trade-in range for licensed shop accounts.

Usage

Use this for corroboration and coverage: confirming a VIN resolves to one vehicle rather than several, confirming the trim two independent vendors agree on, and confirming a valuation exists before asking assess_repair_economics for a verdict.

A licensed shop account (OAuth) also receives tradeInValue — the Black Book trade-in range, rough to average condition, the same range assess_repair_economics weighs a repair against — with valuesWithheld: false and an attribution to repeat with it. A self-serve developer key receives valuesWithheld: true: which markets and condition grades the provider holds data for, never the figures themselves.

If the VIN matches more than one trim the result is {ambiguous: true, candidates: [...]}. Present the candidates; trims differ in value by hundreds of dollars, and a confident answer about the wrong one is the worst available outcome.

Parameters

Parameter	Type	Required	Description
`vin`	string	Yes	The vehicle's VIN — full 17 characters, or the 9- or 10-character partial forms. This is the ONLY vehicle identifier these tools accept: it is the one key both MOTOR and Black Book understand. Do NOT pass a baseVehicleId (MOTOR's identifier) or a uvc (Black Book's) here. Example: "2HGFA1F5A"
`mileage`	positive integer	No	Current odometer reading in miles. Strongly recommended: without it the valuation assumes normal mileage for the model year, and a high-mileage vehicle is worth materially less than that. Example: 62000
`state`	string	No	US state abbreviation or ZIP for regional adjustment. The shop's location is a reasonable default. Example: "48226"

Description advertised to clients

The exact description a fully entitled MCP client discovers — the workflow contracts travel with the tool, so a client with no system prompt still uses it correctly. An account missing a licence for content this tool reaches sees the same text behind a [Licensed content — not enabled on this account] or [Partially available] notice:

Identify a vehicle in the valuation provider's taxonomy and report what valuation data exists for it — and, for a licensed shop account, what it is worth. Returns {uvc, vehicle, matchedBy, trimLevel, candidateCount, marketsAvailable, conditionGrades, valuesWithheld} and, for a licensed shop account, {tradeInValue, attribution}. marketsAvailable names which markets the provider holds data for; conditionGrades names the condition ladder. tradeInValue is the Black Book trade-in range — rough to average condition, low to high — the same range assess_repair_economics weighs a repair against; quote it as a range and repeat the attribution. Its other uses are corroboration and coverage: confirming a VIN resolves to one vehicle rather than several, confirming the trim two independent vendors agree on, and confirming a valuation exists at all before asking assess_repair_economics for a verdict. If the result is {ambiguous: true, candidates: [...]}, the VIN matched more than one trim — present the candidates and ask the user which vehicle it is. Do NOT pick one: trims differ in value by hundreds of dollars and a confident answer about the wrong one is the worst available outcome. Vehicle valuations are licensed content (Black Book). Who receives the figures depends on the caller: a licensed shop account (OAuth) receives the trade-in value range, the repair total weighed, and the share of value, with valuesWithheld false and an attribution to repeat alongside any figure you quote. A self-serve developer key receives the BAND only — valuesWithheld true, no dollar figures, no percentages. When valuesWithheld is true, do not ask the user for the vehicle's value to fill the gap, do not estimate one, and do not present a figure of your own as though it came from here. To weigh a repair against the vehicle's worth, call assess_repair_economics, which returns a band. Vehicle resolution runs through MOTOR's evaluation sandbox, which covers model years 2010, 2015, and 2016 ONLY — a VIN outside those years will not resolve. That is sandbox coverage, not an error, and not a fact about the vehicle.

Example — Coverage check by VIN

Example for a licensed shop account; the figures are the live valuation of this vehicle on 2026-09-17. A developer key receives the same response without tradeInValue or attribution, and with valuesWithheld: true.

Request

{
  "vin": "2HGFA1F5A",
  "mileage": 62000,
  "state": "MI"
}

Response

{
  "uvc": "2010360047",
  "vehicle": "2010 Honda Civic LX",
  "matchedBy": "vin",
  "trimLevel": true,
  "candidateCount": 1,
  "confidence": "corroborated",
  "marketsAvailable": [
    "wholesale",
    "tradein",
    "retail"
  ],
  "conditionGrades": [
    "rough",
    "average",
    "clean",
    "xclean"
  ],
  "mileageApplied": true,
  "tradeInValue": {
    "market": "tradein",
    "lowCents": 184500,
    "highCents": 309500,
    "low": "$1,845",
    "high": "$3,095",
    "condition": {
      "low": "rough",
      "high": "average"
    },
    "basis": "adjusted",
    "mileageApplied": true
  },
  "valuesWithheld": false,
  "attribution": "Values supplied by Black Book®. ©2026 Hearst Business Media Corp. ALL RIGHTS RESERVED. Black Book® is a registered trademark of Hearst Business Media Corp."
}