AutoUncle Data Services is in beta. The API, MCP tools and agent skill may change often, including breaking changes, until version 1.0. Read the changelog before you upgrade an integration.
Tool reference
The Data MCP server exposes eight tools and one prompt. This page is generated from the server's own tool definitions, so the argument names and descriptions match what tools/list returns.
Tools and prompts
| Tool | Title | Read-only | Spends credits |
|---|---|---|---|
valuate_car |
Value a vehicle | No | Live keys and OAuth: one credit per valued result |
forecast_selling_time |
Forecast a vehicle's selling time | No | Live keys and OAuth: two credits per valued result with its forecast |
get_market |
Describe the market for a car type | No | Live keys and OAuth: one credit per measured result |
search_vehicles |
Browse vehicle catalogue | Yes | No |
get_valuation |
Read a recorded valuation | Yes | No |
get_account |
Check account and credits | Yes | No |
normalize_vehicle |
Normalize a vehicle | No | Live keys and OAuth: one credit per normalized result |
decode_vin |
Decode a VIN | Yes | Live keys and OAuth: one credit per lookup that returns vehicle data |
decode_hsn_tsn |
Look up German HSN/TSN codes | Yes | Live keys and OAuth: one credit per lookup that returns vehicle data |
lookup_plate |
Look up a registration plate | Yes | Live keys and OAuth: one credit per lookup that finds the vehicle |
valuate_car
Value a vehicle. Value a vehicle in its market. The vehicle can be listing attributes or the vehicle that normalize_vehicle, decode_vin, decode_hsn_tsn or lookup_plate returned. Successful live calls cost one credit, plus one when sent images were used; test keys are free synthetic examples. Reuse an idempotency key when retrying the same input. Set options.include to ["comparables"] for similar listings on sale and recently sold as evidence behind the price, for one extra credit charged only when listings are returned (not available in Denmark). Add "trade_in_price" for AutoUncle's estimate of a fair trade-in price with a range, an estimate and not an offer, for one extra credit charged only when it is returned (only in AT, CH, DE, DK, ES, FR, GB, IT, NL, PL, PT and SE), and "similar_cars_link" for a free link to similar cars for sale on AutoUncle.
Takes the same arguments as the POST /v1/valuations body, plus idempotency_key. Refused and failed valuations return isError: true with the full valuation envelope as structured content. Pass options: { include: ["comparables"] } for comparable listings as evidence, for one extra credit when they are returned; add trade_in_price for a trade-in estimate (one extra credit when returned) and similar_cars_link for a free link to similar cars on AutoUncle.
Annotations: destructiveHint: false, idempotentHint: false, openWorldHint: true, readOnlyHint: false.
| Argument | Type | Required | Description |
|---|---|---|---|
country |
string | Yes | Valuation market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own vehicle data, currency and mileage conventions. See request fields. 2 to 10 characters. |
vehicle |
object | No | A vehicle as a request describes it: either an AVS vehicle document (any vehicle an endpoint returned, posted back unchanged, or one you build), recognized by its avs member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing. See request fields. |
description |
string | No | Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs. See request fields. 1 to 20000 characters. |
images |
array | No | Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (usage.charges.images); skipped or unused photos are not charged. See request fields. At most 8 items. |
pricing |
object | No | The asking-price context for this valuation. The result explicitly states its currency and whether the expected asking price is dealer retail or private sale. See request fields. |
options |
object | No | Resolution and minimum precision controls. Missing optional values use the documented default behaviour. See request fields. |
idempotency_key |
string | No | Unique retry key for this exact input. Reuse after an unknown network outcome; use a new key for a deliberate new valuation. At most 200 characters. |
Result: A valuation result, returned as structured content and as JSON text.
forecast_selling_time
Forecast a vehicle's selling time. Value a vehicle and forecast how long it takes to sell if listed now and its price is kept: median days and the chance of selling within 30, 60 and 90 days for each price-rating band, and at pricing.asking_price when given. Available in every Data Services market. Takes the same input as valuate_car. Successful live calls cost two credits (valuation and forecast); test keys are free synthetic examples. Reuse an idempotency key when retrying the same input.
Takes the same arguments as the POST /v1/selling-times body, plus idempotency_key, and returns the same result: a valuation with its selling_time forecast, in every Data Services market. Refused and failed forecasts return isError: true with the full envelope as structured content and spend no credits.
Annotations: destructiveHint: false, idempotentHint: false, openWorldHint: true, readOnlyHint: false.
| Argument | Type | Required | Description |
|---|---|---|---|
country |
string | Yes | Valuation market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own vehicle data, currency and mileage conventions. See request fields. 2 to 10 characters. |
vehicle |
object | No | A vehicle as a request describes it: either an AVS vehicle document (any vehicle an endpoint returned, posted back unchanged, or one you build), recognized by its avs member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing. See request fields. |
description |
string | No | Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs. See request fields. 1 to 20000 characters. |
images |
array | No | Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (usage.charges.images); skipped or unused photos are not charged. See request fields. At most 8 items. |
pricing |
object | No | The asking-price context for this valuation. The result explicitly states its currency and whether the expected asking price is dealer retail or private sale. See request fields. |
options |
object | No | Resolution and minimum precision controls. Missing optional values use the documented default behaviour. See request fields. |
idempotency_key |
string | No | Unique retry key for this exact input. Reuse after an unknown network outcome; use a new key for a deliberate new forecast. At most 200 characters. |
Result: A valuation with its selling-time forecast. The same envelope as ValuationResponse (object is valuation, and the result can be read back with GET /v1/valuations/{id}); a valued result always carries selling_time, returned as structured content and as JSON text.
get_market
Describe the market for a car type. Market and demand figures for a car type in one Data Services market: listings on sale, asking-price and mileage ranges, price-rating mix, listings leaving the market per day, days to leave, days of supply, a demand level relative to the whole market and a 12-month trend. Takes the same vehicle input as valuate_car; a make and model are enough, and year, fuel, gearbox and body narrow the segment. Aggregates over the listings AutoUncle tracks only; "left the market" is not always a sale, and figures from fewer than 10 listings are withheld. A measured live result costs one credit; partial or insufficient_data results and test keys are free. Reuse an idempotency key when retrying the same input.
Takes the same arguments as the POST /v1/market body, plus idempotency_key. A make and model are enough; a partial or insufficient_data result is returned as a normal result and costs nothing. Figures are aggregates over tracked listings only, and "left the market" is not always a sale.
Annotations: destructiveHint: false, idempotentHint: false, openWorldHint: true, readOnlyHint: false.
| Argument | Type | Required | Description |
|---|---|---|---|
country |
string | Yes | Market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. Every figure comes from that market's own listings only. 2 to 10 characters. |
vehicle |
object | No | A vehicle as a request describes it: either an AVS vehicle document (any vehicle an endpoint returned, posted back unchanged, or one you build), recognized by its avs member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing. |
description |
string | No | Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs. 1 to 20000 characters. |
images |
array | No | Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data, to identify the car type. AI image resolution is deployment-configured and never runs for test keys. Photos cost nothing extra on a market request. At most 8 items. |
options |
object | No | How the vehicle is resolved. |
idempotency_key |
string | No | Unique retry key for this exact input. Reuse after an unknown network outcome; a replay spends no credit. At most 200 characters. |
Result: Market & demand figures for a car type in one market: aggregates over the listings AutoUncle tracks there, never a listing, returned as structured content and as JSON text.
search_vehicles
Browse vehicle catalogue. Find catalogue identities and their parent-child relationships. Catalogue calls do not consume valuation credits. Send these IDs back with a valuation to remove ambiguity.
Covers the same lists as the REST catalogue (brands, models, generations, drivetrains, equipment variants, search, enums, countries and version). Drivetrain filters and lookup by ID are REST-only in this version.
Annotations: destructiveHint: false, idempotentHint: true, openWorldHint: false, readOnlyHint: true.
| Argument | Type | Required | Description |
|---|---|---|---|
kind |
string | Yes | Catalogue resource to list or search. One of brands, models, generations, drivetrains, equipment-variants, search, enums, countries, version. |
parent_id |
string | No | Parent catalogue UUID for the requested level. |
query |
string | No | Vehicle make/model text for search; on list kinds, a case-insensitive name filter. At most 200 characters. |
year |
integer | No | Registration year to narrow generation candidates. |
fuel |
string | No | Only drivetrains with this fuel. One of petrol, diesel, electric, hybrid, plug_in_hybrid_petrol, plug_in_hybrid_diesel, lpg, cng, ethanol, hydrogen. |
transmission |
string | No | Only drivetrains with this transmission. One of manual, automatic. |
power_hp |
integer | No | Only drivetrains with exactly this power in horsepower. |
model_id |
string | No | Only drivetrains of this catalogue model, including an alias model's drivetrains. |
Result: Catalogue entries or supported market/enumeration metadata, returned as structured content and as JSON text.
get_valuation
Read a recorded valuation. Read a valuation belonging to the authenticated organization. This does not spend a valuation credit.
The same result as GET /v1/valuations/{id}, counted against the same valuation rate limit.
Annotations: destructiveHint: false, idempotentHint: true, openWorldHint: false, readOnlyHint: true.
| Argument | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The val_ request identifier returned by a valuation. |
Result: A valuation result, returned as structured content and as JSON text.
get_account
Check account and credits. Verify your API connection and inspect key permissions and available valuation credits.
The same result as GET /v1/account, counted against the same valuation rate limit.
Annotations: destructiveHint: false, idempotentHint: true, openWorldHint: false, readOnlyHint: true.
No arguments.
Result: Organization, key permissions and credit balance, returned as structured content and as JSON text.
normalize_vehicle
Normalize a vehicle. Resolve messy vehicle facts or listing text to an AutoUncle vehicle (catalogue identity, specs, equipment, registration) without valuing it. When several catalogue records fit, returns them as candidates instead of a guess. Successful live calls cost one credit, plus one when sent images were used; test keys are free. Reuse an idempotency key when retrying the same input.
Takes the same arguments as the POST /v1/vehicles/normalize body, plus idempotency_key. Present ambiguous results as a choice between identification.candidates; never pick one silently. The returned vehicle can be passed unchanged as the vehicle of valuate_car.
Annotations: destructiveHint: false, idempotentHint: false, openWorldHint: true, readOnlyHint: false.
| Argument | Type | Required | Description |
|---|---|---|---|
country |
string | Yes | Market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own catalogue scope and mileage conventions. See request fields. 2 to 10 characters. |
vehicle |
object | No | A vehicle as a request describes it: either an AVS vehicle document (any vehicle an endpoint returned, posted back unchanged, or one you build), recognized by its avs member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing. See request fields. |
description |
string | No | Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs. See request fields. 1 to 20000 characters. |
images |
array | No | Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (usage.charges.images); skipped or unused photos are not charged. See request fields. At most 8 items. |
options |
object | No | How the vehicle is resolved. See request fields. |
idempotency_key |
string | No | Unique retry key for this exact input. Reuse after an unknown network outcome; a replay spends no credit. At most 200 characters. |
Result: A normalization result with its Vehicle, returned as structured content and as JSON text.
decode_vin
Decode a VIN. Decode a 17-character VIN and identify the vehicle against the AutoUncle catalogue (usually brand, model and model year), with provenance, candidates and source attributions. The returned vehicle can be passed to valuate_car. A live lookup that returns vehicle data costs one credit; no match, failures and test keys are free. A VIN never yields German HSN/TSN codes.
Takes the same arguments as the POST /v1/vehicles/decode body and returns the same result, with the vehicle identified against the catalogue; pass vehicle on to valuate_car with a current mileage. Failures return isError: true with a Problem as structured content and never mean "not found".
Annotations: destructiveHint: false, idempotentHint: true, openWorldHint: true, readOnlyHint: true.
| Argument | Type | Required | Description |
|---|---|---|---|
vin |
string | Yes | The 17-character VIN. Spaces and lower case are accepted; look-alike characters (O for 0, I for 1) are never repaired, and a VIN containing I, O or Q is rejected. 17 to 40 characters. |
country |
string | Yes | Your market for this lookup, as an ISO 3166-1 alpha-2 code from GET /v1/catalogue/countries. It scopes key permissions and logging; it is never treated as the car's original market. Pattern ^[A-Za-z]{2}$. |
market |
string | No | The car's original sales market (ISO 3166-1 alpha-2), only when you know it independently. Never derive it from your market or the registration country. Pattern ^[A-Za-z]{2}$. |
model_year |
integer | No | The model year, only when you know it independently. A first registration or production year does not establish it. 1886 to 2100. |
Result: A lookup result with its Vehicle, returned as structured content and as JSON text.
decode_hsn_tsn
Look up German HSN/TSN codes. Look up the German type codes from a registration document (HSN, field 2.1; the first three characters of TSN, field 2.2) in the Kraftfahrt-Bundesamt type snapshot and identify the brand and model against the AutoUncle catalogue. A live lookup that returns vehicle data costs one credit; no match, failures and test keys are free.
Takes the same arguments as the POST /v1/vehicles/hsn-tsn body and returns the same result.
Annotations: destructiveHint: false, idempotentHint: true, openWorldHint: true, readOnlyHint: true.
| Argument | Type | Required | Description |
|---|---|---|---|
hsn |
string | Yes | Herstellerschlüsselnummer, field 2.1: four digits, sent as a string so leading zeroes are kept. 4 to 8 characters. |
tsn |
string | Yes | The first three characters of the Typschlüsselnummer, field 2.2. Longer codes are rejected rather than truncated. 3 to 8 characters. |
country |
string | No | Your market for this lookup (ISO 3166-1 alpha-2). Defaults to DE. The codes are always KBA codes. Pattern ^[A-Za-z]{2}$. |
Result: A lookup result with its Vehicle, returned as structured content and as JSON text.
lookup_plate
Look up a registration plate. Look up a vehicle by its registration plate in the country's vehicle register (currently Denmark only) and identify it against the AutoUncle catalogue: identity, VIN, first registration, specs and the last inspection's dated odometer reading, with provenance and attributions. A live lookup that finds the vehicle costs one credit; no match, failures and test keys are free. Only look up plates the user gave you for a vehicle they have a reason to check.
Takes the same arguments as the POST /v1/vehicles/lookup body and returns the same result. Countries without a register return isError: true with lookup_country_unsupported. The register's odometer reading is dated (vehicle.vehicle.odometer.readAt); ask for today's mileage before valuing the car.
Annotations: destructiveHint: false, idempotentHint: true, openWorldHint: true, readOnlyHint: true.
| Argument | Type | Required | Description |
|---|---|---|---|
country |
string | Yes | Country of the plate, ISO 3166-1 alpha-2. Only DK is supported in this version. 2 to 2 characters. |
plate |
string | Yes | Registration plate as printed. Spaces, dashes and dots are ignored and letters are matched case-insensitively. Danish plates have 2 to 7 letters and digits, including personal plates. 1 to 20 characters. |
Result: A lookup result with its Vehicle, returned as structured content and as JSON text.
Prompts
value_a_car
Guide a vehicle valuation while keeping market, price basis and uncertainty explicit.
vehicle(required): Vehicle description without personal information.
How results work
- Structured and text. Every tool returns its JSON twice: as
structuredContentand as a text block incontent. ReadstructuredContentif your client supports it. - Same contract as REST.
valuate_carandget_valuationreturn the valuation result;get_accountreturns the account object;search_vehiclesreturns the same lists as the catalogue endpoints. - Notes and attributions. Results include
notesandattributions. Keep them with anything you show, and displayattribution_textwhen present. See notes and data sources.
Errors
- Refused or failed valuations (
statusrefusedorfailed) returnisError: truewith the full valuation envelope, includingerror.code,error.fixanderror.retryable. They are recorded, free and replayable with the sameidempotency_key. - Request problems such as a missing scope, an unsupported country or a rate limit also return
isError: true, with a Problem as the structured content. - Limits. MCP has no response headers, so
rate_limited,concurrency_limitedandengine_busycarryretry_after(seconds) in the body. Wait that long, then retry with the sameidempotency_key. - Missing required arguments, such as
valuate_carwithoutcountry, are rejected by the MCP server before the tool runs, withisError: trueand a text message naming the argument. Over REST the same request returnscountry_required. - Authentication failures reject the HTTP request itself with
401before any tool runs.
Every code is listed in errors & retries.
The idempotency_key argument
valuate_car takes idempotency_key as an argument because MCP has no request headers for it. It behaves exactly like the REST Idempotency-Key header (idempotency):
- Generate a new, unique key for each valuation you intend to make.
- If a call times out or the connection drops, call again with the same key and the same arguments. You get the recorded outcome without a second charge, with
usage.idempotent_replay: true. - Reusing a key with different arguments returns
idempotency_conflict. - After a confirmed refusal or failure, fix the input and use a new key.
Without idempotency_key, every call is a new valuation.
Scopes and billing
| Tool | Scope | Cost |
|---|---|---|
valuate_car |
valuations:write |
One credit per valued result with a live key or OAuth, plus one when requested comparables are returned and one when sent images were used. Free with a test key, when refused or failed, and on an idempotent replay. Valuations rate limit. |
forecast_selling_time |
valuations:write |
Two credits per valued result with a live key or OAuth (valuation and forecast), plus one when requested comparables are returned. Free with a test key, when refused or failed, and on an idempotent replay. Valuations rate limit and valuation concurrency slots. |
search_vehicles |
catalogue:read |
Free. Catalogue rate limit (120 per minute by default). |
get_valuation |
valuations:read |
Free. Valuations rate limit. |
get_account |
account:read |
Free. Valuations rate limit. |
normalize_vehicle |
vehicles:read |
One credit per normalized result with a live key or OAuth, plus one when sent images were used. Free with a test key, on refusal or failure, and on an idempotent replay. Vehicles rate limit (60 per minute by default, counted separately from valuations) and valuation concurrency slots. |
decode_vin, decode_hsn_tsn, lookup_plate |
vehicles:read |
One credit per live lookup that returns vehicle data. Free with a test key, and free on no_match or failure. Vehicles rate limit. |