Inventory

Four read tools, all under one scope: inventory:read. Available to public and partner callers alike. Every tool returns public fields only — never invoice, cost, hold-back, or salesperson data.

VIN format Wherever a VIN is accepted it must match ^[A-HJ-NPR-Z0-9]{17}$ — 17 alphanumeric characters, ISO 3779 (the letters I, O, Q are excluded). VINs are upper-cased and trimmed server-side. See Data formats for VIN, Money, timestamp, and enum conventions used across every tool.

search_inventory

Semantic + structured search across available vehicles. Provide a natural-language query to rank by relevance (a Voyage embedding round-trip), or omit it for a purely structured filter + sort with no embedding cost. Only available (unsold, unreserved) vehicles are returned, up to 25.

Field	Type		Constraints
query	string	optional	≤ 500 chars. Blank → structured path.
min_year	int	optional	1990–2030
max_year	int	optional	1990–2030
min_price	decimal	optional	0–999999
max_price	decimal	optional	0–999999
max_mileage	int	optional	0–500000
condition	enum	optional	new \| used \| cpo \| any (default any)
sort_by	enum	optional	relevance \| price \| mileage \| year (default relevance)
sort_order	enum	optional	asc \| desc (default asc)
limit	int	optional	1–25 (default 10)

Relevance → price fallback Relevance ordering needs an embedding. If you ask for sort_by: "relevance" with no query, the service falls back to a deterministic price / asc sort so results are stable and reproducible.

Request

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "search_inventory",
    "arguments": {
      "query": "2024 Subaru Outback AWD under 35k, white",
      "max_price": 35000,
      "limit": 5
    }
  }
}

Response

{ "data": {
    "items": [
      {
        "vin": "4S4BTGUD8R3201234",
        "year": 2024, "make": "Subaru", "model": "Outback", "trim": "Premium",
        "condition": "new", "exterior_color": "Crystal White Pearl",
        "mileage": 12, "asking_price": 34187.0, "msrp": 35420.0,
        "status": "available", "photos": ["https://…"],
        "similarity": 0.8123
      }
    ],
    "count": 1
  },
  "_metadata": { "trace_id": "trc_…", "tool": "search_inventory", "protocol": "a2a" }
}

similarity is present only on the relevance path (cosine distance, 4 dp). On the structured path it is absent.

Vehicle record fields

Every inventory tool that returns a vehicle (search_inventory items, list_inventory items, get_vehicle_by_vin.vehicle) uses this shape. Public fields only — never invoice, cost, hold-back, or salesperson data.

Field	Type		Description
vin	string	always	17-char VIN, `^[A-HJ-NPR-Z0-9]{17}$`. The stable key for quote / reserve / hand-off.
store_code	string	always	Which store holds the unit (e.g. `MMS` / `MMU`). Required in the schema.
stock_number	string	optional	Dealer stock number for the unit.
year	int	always	Model year.
make	string	always	Manufacturer, e.g. `Subaru`.
model	string	always	Model name, e.g. `Outback`.
trim	string	optional	Trim level, e.g. `Premium`. May be absent on sparse records.
condition	enum	always	Canonical `Condition`: `new` \| `used` \| `certified` \| `rental` \| `demo`. (The input filter also accepts the legacy alias `cpo` → `certified` and `any`.)
body_style	string	optional	Body style, e.g. `SUV` / `Sedan`.
exterior_color	string	optional	Marketing color name, e.g. `Crystal White Pearl`.
interior_color	string	optional	Interior color/trim name.
transmission	string	optional	Transmission type (enrichment field).
drivetrain	string	optional	Drivetrain, e.g. `AWD` / `FWD`.
fuel_type	string	optional	Fuel type, e.g. `Gas` / `Hybrid` / `EV` (enrichment field).
mileage	int	optional	Odometer miles. Near-zero on new units.
asking_price	number	always	The listed price in USD. This is what `request_quote` pins as `quoted_price`.
msrp	number	optional	Manufacturer's suggested retail price, when known.
status	enum	always	`available` \| `pending` \| `sold` \| `off-lot`. Search/list return only `available`. (The separate `check_availability` map can also report runtime states like `reserved` / `in_transit` / `unknown`.)
days_on_lot	int	optional	Days the unit has been in inventory.
stocked_date	string	optional	Date the unit was stocked (ISO 8601).
photos	string[]	optional	Array of image URLs; may be empty.
description	string	optional	Free-text marketing/description blurb.
similarity	number \| null	optional	Relevance score (cosine distance, 4 dp) — present only on the `search_inventory` relevance path; `null`/absent on every structured path.

Nullability: every optional field above is typed ["<type>", "null"] in schemas/inventory.json — it may be returned as an explicit null, not just omitted. Only the always fields (vin, store_code, condition, year, make, model, asking_price, status) are non-null and required. Generate your client types accordingly (accept null for the optionals).

list_inventory

Structured-filter, paginated listing — exact-match lookups, year ranges, and price windows. Use this (not search_inventory) when you want deterministic pagination over a filter set. Returns { items, total, limit, offset } where total is the full match count for the filter.

Field	Type		Constraints
year	int	optional	1990–2030 (exact match)
min_year	int	optional	1990–2030
max_year	int	optional	1990–2030
make	string	optional	≤ 40 chars (case-insensitive)
model	string	optional	≤ 60 chars (case-insensitive)
trim	string	optional	≤ 80 chars (substring match)
condition	enum	optional	new \| used \| cpo \| any (default any)
min_price	decimal	optional	0–999999
max_price	decimal	optional	0–999999
max_mileage	int	optional	0–500000
limit	int	optional	1–100 (default 25)
offset	int	optional	0–10000 (default 0)

Request & response

// arguments
{ "make": "Subaru", "model": "Crosstrek", "min_year": 2023, "limit": 25, "offset": 0 }

// data
{ "items": [ { "vin": "…", "year": 2024, "make": "Subaru", "model": "Crosstrek", … } ],
  "total": 41, "limit": 25, "offset": 0 }

get_vehicle_by_vin

Fetch a single vehicle by VIN. Returns { vehicle, found }; vehicle is null and found is false when the VIN is unknown.

Field	Type		Constraints
vin	string	required	^[A-HJ-NPR-Z0-9]{17}$

// arguments
{ "vin": "4S4BTGUD8R3201234" }

// data
{ "found": true,
  "vehicle": { "vin": "4S4BTGUD8R3201234", "year": 2024, "make": "Subaru",
               "model": "Outback", "trim": "Premium", "mileage": 12,
               "asking_price": 34187.0, "msrp": 35420.0, "status": "available",
               "photos": ["https://…"] } }

check_availability

Batch status check for up to 50 VINs at once. Returns a statuses map; any VIN not in inventory maps to unknown.

Field	Type		Constraints
vins	string[]	required	1–50 items, each ^[A-HJ-NPR-Z0-9]{17}$

// arguments
{ "vins": ["4S4BTGUD8R3201234", "JF2GTHMC5R8301111"] }

// data
{ "statuses": {
    "4S4BTGUD8R3201234": "available",
    "JF2GTHMC5R8301111": "reserved"
} }

Statuses: available, reserved, sold, pending, in_transit, unknown.

Errors

get_vehicle_by_vin never errors on a miss — it returns found: false. A malformed VIN (or out-of-range numeric filter) fails Pydantic validation and returns VALIDATION_FAILED. See the error taxonomy for the full envelope.