Skip to content
MCP & agents / Tool referenceView Markdown ↗
Beta

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 structuredContent and as a text block in content. Read structuredContent if your client supports it.
  • Same contract as REST. valuate_car and get_valuation return the valuation result; get_account returns the account object; search_vehicles returns the same lists as the catalogue endpoints.
  • Notes and attributions. Results include notes and attributions. Keep them with anything you show, and display attribution_text when present. See notes and data sources.

Errors

  • Refused or failed valuations (status refused or failed) return isError: true with the full valuation envelope, including error.code, error.fix and error.retryable. They are recorded, free and replayable with the same idempotency_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_limited and engine_busy carry retry_after (seconds) in the body. Wait that long, then retry with the same idempotency_key.
  • Missing required arguments, such as valuate_car without country, are rejected by the MCP server before the tool runs, with isError: true and a text message naming the argument. Over REST the same request returns country_required.
  • Authentication failures reject the HTTP request itself with 401 before 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.