CarEdge MCP Server: Tool Documentation

CarEdge (Auto Advocate, Inc.) is a US car-buying service. Its MCP server lets an AI assistant search cars for sale at US dealerships near the shopper's ZIP code, show one car's details, compare cars, price a car out the door for the shopper's location, check a dealer's CarEdge Dealer Transparency Index grade, decode a VIN, check recalls, estimate a trade-in's value and a monthly payment, and, only when the shopper asks, send the shopper's contact request to one CarEdge partner dealer.

United States only: US dealers and US ZIP codes. Prices and fees come from the dealer's own listing, and the dealer confirms the final price. Payment and trade-in figures are estimates, not offers. CarEdge does not sell cars, take payments or arrange financing.

For shoppers

Once CarEdge is connected, you can ask your assistant things like:

• "Find a used SUV under $35,000 near 74133 with CarEdge."
• "What's the out-the-door price on that car if I live in 74133?"
• "Is that dealer straight on price?"
• "What is my 2019 Honda Accord worth as a trade-in, and what would the monthly payment be?"
• "Ask the dealer to contact me about the second car."

Partner dealers and other dealers. A search near your ZIP covers the cars of every dealer in CarEdge's marketplace listings, nearest first. A CarEdge partner dealer gives an itemized out-the-door quote and can be asked to contact you. At any other dealer you see the dealer's listed price, an out-the-door estimate from CarEdge and a link to the car on caredge.com; CarEdge cannot send that dealer your request. Each dealer also carries its grade from CarEdge's Dealer Transparency Index, which grades dealers on their fees, their add-ons and how closely the final price matches the listing.

To connect: in your assistant, add CarEdge as a connector (or custom connector) with the address below. Searching, car details, prices and the other research tools work with no sign-in. You are asked to sign in to CarEdge, or create an account, only when you ask a dealer to contact you. Saying "CarEdge" in your question helps your assistant pick it.

Your assistant never sends your details to a dealer while searching or pricing. When you ask a dealer to contact you, it asks for your name and how to reach you, shows you the dealer's own consent wording, and sends your request only after you agree. Requests from CarEdge's own review accounts go to a CarEdge inbox, never to a dealer.

Setup

Endpoint:

http://preprod-mcp.caredge.com/mcp

Transport: Streamable HTTP MCP, stateless, with JSON responses. Requests are HTTP POST. A GET or DELETE on the endpoint answers 405. Request bodies over 64 KB are refused.

Authentication: OAuth 2.1 authorization code flow with PKCE (S256). The client is a public client with no client secret; assistants register their own client with the authorization server.

A call to lead_prepare or lead_submit without a valid token answers HTTP 401 with a WWW-Authenticate header that points to the protected resource metadata. The server accepts only OAuth access tokens from the authorization server above, signed RS256, unexpired, naming a user, and issued for the audience http://preprod-mcp.caredge.com/mcp. The authorization server also supports the refresh token grant.

How to connect

1. Add the endpoint URL as a remote MCP server in the client.
2. The client reads the protected resource metadata, finds the authorization server, and starts the authorization code flow with PKCE and the inventory:read scope.
3. The user signs in with a CarEdge account at the authorization server (or creates one) and approves access.
4. The client calls tools/list and then calls tools with the access token as a Bearer header.

Permissions

• No sign-in for reading: an AI assistant with no token may list the tools and call every read tool. Only lead_prepare and lead_submit need a signed-in CarEdge user; called with no token, they answer HTTP 401 with the WWW-Authenticate header above, which is how the assistant knows to start sign-in.
• Scope: inventory:read is the only scope the server publishes, and every signed-in call needs it.
• Tool access: every AI assistant gets the same 14 tools below, from one server-side policy for signed-in users and one for callers who have not signed in. There is no separate read-only grant.
• Per-user isolation: limits, lead counts and audit records are kept per signed-in user, or per caller when not signed in. A quote code or lead ticket issued to one user does not work for another.
• Partner dealers: a store or car marked participating: true is a CarEdge partner: it can be quoted and sent a lead. participating: false means it can be described, and given an out-the-door estimate, but not quoted by the dealer or sent a lead.

Tools for AI assistants

These are the 14 tools an AI assistant (Claude, ChatGPT and others) sees. Twelve only read. The two lead tools write, and only lead_submit sends anything to a dealer.

Sign-in: the 12 read tools work with no sign-in; lead_prepare and lead_submit need a signed-in CarEdge user. Every call, on every tool, also writes an audit record (see Data handling). Dealer widgets and partner API keys have a wider set of tools, listed in Dealer widgets and partner keys.

Response format

Every tool returns the same envelope as structured content, with the same JSON repeated as a text block for clients that read only text:

{ "data": { }, "freshness": { }, "error": null }

• Success: data holds the answer and error is null.
• Refusal the assistant can act on: data is null, error is { "code", "message", "retryable" }, and the result has isError: true. The message says what to do next.
• Protocol faults stay JSON-RPC errors and are not wrapped in the envelope. A missing or invalid token answers HTTP 401.
• Money is always a decimal string in dollars, such as "27500.00".

stores_list

Purpose: Lists dealerships near the shopper's ZIP, nearest first, with phone, distance, consent wording and CarEdge's Dealer Transparency Index grade. For an AI assistant it lists every dealer in CarEdge's marketplace listings within the radius, partner or not. Use it when the shopper asks which dealers are near, which store is closest, or for a store's contact details.

Inputs

Key outputs

• rooftops[]: slug, name, group_slug, address, city, state, zip, phone, website, timezone, participating, distance_miles (when near is sent), disclosure_text, dti_grade (A to F, or null), dti_score (0 to 100, or null). For an AI assistant also cars_in_stock, dealer_id and mc_dealer_id. A dealer that is not a CarEdge partner has participating: false and a slug of the form dealer-<id>; its street address may be empty.
• shown_up_to_miles, more_dealers, next_offset (AI assistants): every dealer within shown_up_to_miles is listed; when more_dealers is true, send next_offset as near.offset for the next page.
• sister_stores[]: other stores of the same dealer group, same fields, when the policy covers one store. These cannot be searched, quoted or sent a lead.
• disclosure_text is the store's own consent wording, or null when the store takes no leads or asks for no consent.

Errors: too_broad (coverage spans the whole country and near was not sent), invalid_params.

Side effects: None.

{
  "data": {
    "rooftops": [
      {
        "slug": "jim-glover-chevrolet",
        "name": "Jim Glover Chevrolet",
        "city": "Owasso", "state": "OK", "zip": "74055",
        "phone": "(918) 555-1240",
        "participating": true,
        "distance_miles": 0.9,
        "disclosure_text": "By submitting you agree this dealership may contact you about this vehicle by email, phone or text at the details you provided.",
        "dti_grade": null, "dti_score": null
      }
    ],
    "sister_stores": []
  },
  "freshness": null,
  "error": null
}

dealer_info

Purpose: Describes one store: its contact details, the brands it sells new, how many new and used cars it has, its fees and how its quotes are built, and its Dealer Transparency Index grade. Opening hours are not held.

Inputs

rooftop_slug: one store, from stores_list. Optional when the user's coverage is one store.

Key outputs

• store: the store as stores_list gives it.
• brands_new: makes among the new cars in stock. stock: total, new, used.
• doc_fee, other_fees: from the store's fee schedule; null for a store that takes no quotes and on the public view.
• quotes_include_taxes, binding_fees: whether quotes include tax, title and registration, and whether the fee schedule is confirmed.
• dti_grade, dti_score: CarEdge's Dealer Transparency Index, for AI assistants; null when the store has no grade, and for a dealer's own widget.

A rooftop_slug of the form dealer-<id> from stores_list describes a dealer that is not a CarEdge partner, from its listings: participating: false, no fees, and its grade where one exists.

Errors: invalid_params (no rooftop_slug when the coverage has more than one store), out_of_scope (a store this user does not cover), inventory_unavailable (retryable).

Side effects: None.

inventory_search

Purpose: Finds cars for sale by make, model, year, price, body style, color, mileage, features, stock number and other filters. Returns one page of results at a time. For an AI assistant, a search with near and no rooftop_slug covers every dealer in CarEdge's marketplace listings within the radius, nearest first; without near it covers CarEdge's partner stores. A car at a dealer that is not a CarEdge partner comes back view-only: participating: false, no price_with_fees, a rooftop_slug of the form dealer-<id>, and a dealer object saying who sells it (name, city, state, ZIP, distance, listed price, the dealer's own page and the car's caredge.com page).

Inputs (all optional)

As an AI assistant sees them. A list takes up to 10 values unless noted, and any one value matches. A value outside a fixed list answers invalid_params, naming the field and the values it takes.

When the stores span the whole country, the call must include at least one of query, make, near or state. A partner key sees the smaller schema of the dealer widget: single strings for make, model and body_type, five sort orders and up to 100 cars a page.

Key outputs

• rows[]: vin, rooftop_slug, rooftop_name, source, listed_as_of, participating, year, make, model, trim, condition, price, price_with_fees, msrp, miles, hero_photo_url, photo_count, stock_no, exterior_color, in_transit.
• total: how many cars matched in all, not how many are on this page.
• next_cursor: present when there is another page.
• makes: the match count split by make into new and used.
• freshness: one entry per store, keyed by store slug.
• price_with_fees is the price with the store's own fees, before any discount and tax. source is dealer_feed or marketplace; a marketplace price is CarEdge's best reading of the dealer's advertised price.

Errors: too_broad (no query, make or near on whole-country coverage, or the answer would be over 64 KB; ask again with a smaller limit), out_of_scope (rooftop_slug names a store this user does not cover), invalid_params, inventory_unavailable (retryable).

Side effects: None.

{
  "data": {
    "rows": [
      {
        "vin": "5GAERBKW8RJ102292",
        "rooftop_slug": "jim-glover-chevrolet",
        "source": "dealer_feed",
        "participating": true,
        "year": 2024, "make": "Buick", "model": "Enclave", "trim": "Essence",
        "condition": "used",
        "price": "27500.00",
        "price_with_fees": "28099.00",
        "miles": 48259,
        "in_transit": false
      }
    ],
    "total": 199,
    "next_cursor": "WyJyZWxldmFuY2UiLDIsIjk5YzQyYTY2ZGI0MzQ4OGIiXQ=="
  },
  "freshness": {
    "jim-glover-chevrolet": { "as_of": "2026-11-02T05:44:24Z", "status": "fresh", "source": "dealer_feed" }
  },
  "error": null
}

inventory_facets

Purpose: Counts what is in stock at the stores this user may see: how many cars, how many of each make, model, trim, body type, drivetrain, fuel and color, and the lowest and highest year, price and miles. It answers questions about the whole lot ("what trucks do you have?") from every matching car, not from one page of results.

Inputs (all optional)

One value each, not lists: condition (new, used or certified), query, make, model, body_type (a body style from the inventory_search list, such as SUV or Truck), rooftop_slug and near. When the stores span the whole country, the call must include at least one of query, make or near. The other inventory_search filters are not taken here.

Key outputs

• total, new, used: how many cars matched (used includes certified).
• makes, models, trims, body_types, drivetrains, fuels, exterior_colors: up to 20 { "value", "count" } each, most common first.
• year, miles: { "min", "max" }. price_before_fees: the same in dollars, before the store's fees, so lower than the price_with_fees search results show.
• freshness: one entry per store, keyed by store slug.

Errors: invalid_params, too_broad (no query, make or near on whole-country coverage), out_of_scope, inventory_unavailable (retryable).

Side effects: None.

vehicle_get

Purpose: Returns everything CarEdge holds about one car, by VIN, including the store's consent wording for a later lead.

Inputs

Key outputs

• Car: vin, year, make, model, trim, condition, body_type, miles, stock_no, engine, drivetrain, transmission, fuel, exterior_color, interior_color, features (up to 50) and feature_count, photos (up to 20) and photo_count, one_owner, clean_title, in_transit.
• Price: price, price_with_fees, msrp, doc_fee, incentives (empty today), source, listed_as_of.
• Store: rooftop_slug, rooftop_name, participating, seller_phone, seller_website, also_at (other covered stores listing the same VIN), disclosure_text.

For an AI assistant, a VIN at any other dealer in CarEdge's marketplace listings answers view-only: participating: false, no price_with_fees, and a dealer object saying who sells it, as in inventory_search.

Errors: not_found (no car with that VIN where this user may look; this says nothing about whether the car exists elsewhere), inventory_unavailable (retryable), invalid_params.

Side effects: None.

{
  "data": {
    "vin": "5GAERBKW8RJ102292",
    "rooftop_name": "Jim Glover Chevrolet",
    "participating": true,
    "year": 2024, "make": "Buick", "model": "Enclave", "trim": "Essence",
    "price": "27500.00",
    "price_with_fees": "28099.00",
    "engine": "3.6L V6",
    "photo_count": 1,
    "also_at": [],
    "disclosure_text": null
  },
  "freshness": { "as_of": "2026-11-02T05:44:24Z", "status": "fresh", "source": "dealer_feed" },
  "error": null
}

vehicle_compare

Purpose: Puts two to four cars side by side, by VIN, and says what sets them apart: which fields differ, which features only one car lists, and which car is cheapest, lowest-mileage and newest.

Inputs

vins (required): a list of 2 to 4 different 17-character VINs.

Key outputs

• cars[]: each car exactly as vehicle_get returns it.
• comparison: differs, shared_features, only_features (by VIN), lowest_price, lowest_miles, newest (a VIN, or null on a tie) and price_gap in dollars. Prices are compared on one basis: price_with_fees when every car has it, else the listed price for all. Not an out-the-door price.
• missing: VINs not held at the stores this user may see. With fewer than two cars left, the answer is not_found.
• freshness: one entry per store, keyed by store slug.

Errors: invalid_params (fewer than 2 or more than 4 different VINs), not_found (fewer than two of the cars found), inventory_unavailable (retryable).

Side effects: None.

quote_out_the_door

Purpose: Prices one car for one buyer, line by line: the price, any discount, the dealer's fees and, where the store quotes them, sales tax, title and registration for the buyer's location.

Inputs

Without buyer_location, the car is priced at the store's own location as an estimate (binding: false), and estimate_note says so.

Key outputs

• line_items[]: label, amount, kind (price, discount, fee, tax, registration, incentive) and source (listing, dealer_profile, state_table, licensed_service, incentive_feed).
• total: the cost to drive the car away. A trade-in or deposit does not reduce it.
• binding: true when the dealer stands behind the figure; false when it is an estimate, with estimate_note saying what is unconfirmed.
• taxes_included: false when the store quotes before tax, title and registration. The figure is then not a full out-the-door price.
• buyer_location (the location the tax was computed for), rooftop_slug, rooftop_name, distance_miles, msrp, profile_version, expires_at.
• quote_id: a short code, such as q_d38825v2g3, to pass to lead_prepare so the lead records the figure the shopper saw.
• quote_sheet_url: when present, a link to a printable price sheet of this quote. A caller that has not signed in gets no link.

Dealers that are not CarEdge partners (AI assistants). A car at a dealer that is not a CarEdge partner gets no dealer quote. The answer has participating: false and is_estimate: true: listing_price is the dealer's own advertised price; estimate is an out-the-door estimate for the buyer's ZIP (priced_for: "dealer_zip" when none was given), and each of its line_items says in source and detail where its figure came from; dti_grade, dti_score and dti_grade_reason are the dealer's grade where one exists; caredge_car_url and caredge_dealer_url are its caredge.com pages, null when they cannot be resolved. Such a car cannot be sent a lead.

Errors: not_found (no car with that VIN for this user), quote_unavailable (the store has no pricing arrangement with CarEdge, the car has no price, the store's fee schedule is missing, or there is no tax rate for the buyer's location), invalid_params (for example an unknown ZIP or a negative trade allowance).

Side effects: The signed quote (VIN, total, store, state, county, fee schedule version and expiry) is kept under the short quote_id for 24 hours plus 5 minutes, then discarded. It holds no name or contact details. Nothing is shown to or sent to the shopper or dealer.

{
  "data": {
    "vin": "5GAERBKW8RJ102292",
    "rooftop_name": "Jim Glover Chevrolet",
    "buyer_location": { "state": "OK", "county": "Tulsa", "zip": "74133" },
    "line_items": [
      { "label": "Vehicle Price", "amount": "27500.00", "kind": "price", "source": "listing" },
      { "label": "Admin & Processing Fee", "amount": "599.00", "kind": "fee", "source": "dealer_profile" },
      { "label": "Additional Discount", "amount": "-550.00", "kind": "discount", "source": "dealer_profile" }
    ],
    "total": "27549.00",
    "taxes_included": false,
    "binding": true,
    "estimate_note": null,
    "quote_id": "q_d38825v2g3",
    "expires_at": "2026-11-03T14:07:26.342761Z",
    "quote_sheet_url": "https://<quote sheet host>/public/quote-sheet?t=..."
  },
  "freshness": { "as_of": "2026-11-02T05:44:24Z", "status": "fresh", "source": "dealer_feed" },
  "error": null
}

lookup_dealer_transparency

Purpose: Tells the shopper how transparent a dealer is on price: its CarEdge Dealer Transparency Index grade (A to F) and score, built from real out-the-door quotes from that dealer, not from reviews. It does not check licences, reviews or complaints.

Inputs

Key outputs

• dealer: the grade and score, quote_count (how many out-the-door quotes the grade is based on), the average and median doc fee, add-on behavior and price accuracy. A fee or score CarEdge has not recorded is null, not zero. A dealer graded F because it never sent a written price has grade_reason saying so.
• doc_fee_benchmarks: the state and national average doc fee from CarEdge's State of Dealer Fees report.
• matches: when a name matches dealers in more than one state and no state or VIN is given, dealer is null and this lists them (name, city, state, grade, quote count).
• message and similar_names: when CarEdge holds no grade for the name, dealer is null and similar_names lists graded dealers sharing the name's other words, which may be different dealers.

An AI assistant is never shown individual past quotes from other shoppers, only the grade and the averages.

Errors: invalid_params, upstream_unavailable (the transparency data could not be read; retryable). A dealer with no grade is an answer with dealer: null, not an error.

Side effects: None.

decode_vin

Purpose: Says what car a VIN is, using NHTSA's free vPIC database. For a VIN the shopper pastes, not for a car picked from a search (that is vehicle_get).

Inputs

vin (required): a 17-character VIN.

Key outputs

• Year, make, model, trim, body type, fuel type, drivetrain and engine.
• in_dealer_stock, store_name, dealer_stock_note: present when the VIN is a car for sale on a covered dealer's lot.

Errors: invalid_params (not a valid VIN), not_found (NHTSA answered but could not decode the VIN), upstream_unavailable (NHTSA did not answer; retryable).

Side effects: None. The VIN is sent to NHTSA's public service.

check_vehicle_recalls

Purpose: Lists NHTSA's open safety recall campaigns for a year, make and model. Not a car's accident or title history.

Inputs

year, make, model (all required).

Key outputs

• Up to 10 recalls, each with the affected component and the remedy.
• total_recalls: NHTSA's full count. truncated: true when there are more than those listed.

Errors: invalid_params, upstream_unavailable (NHTSA did not answer, so the check was not done; it never means the car has no recalls).

Side effects: None.

estimate_trade_in

Purpose: Gives a rough value for the car the shopper wants to trade in or sell. Not for a car a dealer is selling.

Inputs

Key outputs

• The value, in cents. source: vehicle_database (trade-in values for that exact trim and condition, from Vehicle Databases, for a signed-in user who gives a VIN) or comparable_listings (an estimate from retail listings nationwide, less exact). With no sign-in the paid service is never asked.
• guidance: how firm the figure is and how it was reached. market_data.trim_matched: false means the listings are of another trim.

Errors: invalid_params, not_found (no comparable listing with a price for that year, make and model, so there is no figure).

Side effects: None.

calculate_finance_payment

Purpose: Works out an example monthly loan payment for a price. It needs a real price, from the shopper or a tool. It is not a loan offer, and CarEdge does not arrange financing.

Inputs

vehicle_price (required, dollars). Optional: the down payment, the trade-in value, the loan term (36, 48, 60, 72 or 84 months), the APR, the state (two-letter code, for a tax estimate) and whether the price already includes tax and fees.

Key outputs

• The monthly payment. With no APR, example payments for excellent, good, fair and poor credit, and rates_note says those APRs are examples.
• With a state: tax_estimate, taxable_amount, trade_in_credit_policy and trade_in_credit_cap, a state-level sales tax estimate that follows the state's trade-in credit rule. County, city and district tax are not included. With no state, or one it does not know, tax_estimate is 0, unknown_state is true and tax_note says the payment excludes tax. caveat, when set, states the limits of the tax figure.

Errors: invalid_params.

Side effects: None.

lead_prepare

Purpose: Step one of sending a shopper's contact request to a dealer. It picks the store, returns that store's own consent wording, and issues a ticket for lead_submit. Nothing is sent to the dealer. Call it only after the shopper has asked to be contacted and has given a first name and at least one of an email address or a phone number.

Inputs

Key outputs

• ticket: a short code, such as t_..., for lead_submit. Good for 15 minutes and one lead.
• disclosure_text: the store's own consent wording, which the shopper must see before agreeing. For an AI assistant it is the store's wording, or CarEdge's when the store has none. Empty when there is no wording to show (an AI assistant still needs the shopper's yes at lead_submit), or on a conversation follow-up, whose consent carries over from the earlier lead.
• expires_at, rooftop_slug, rooftop_name, distance_miles.
• routing_reason: why this store was picked: holds_vin, nearest_to_buyer, caller_named or no_buyer_zip.
• When this shopper's lead for this car was already sent in the last 24 hours and the shopper has reached the daily prepare limit, the answer is that earlier lead in lead_submit's output shape with already_sent: true and no ticket. The assistant should not call lead_submit then.

Errors: invalid_params (no channel, no email or phone, a channel without its matching detail, an unknown ZIP, a quote_id that is expired or for another car or store, an invalid follow-up, or through an AI assistant, a call or text or a phone number at a store with no consent wording: ask for an email address and send channels: ["email"] only), not_found (no car with that VIN for this user), quote_unavailable (no store holding the car takes leads through CarEdge), rate_limited (retryable; see Rate limits), consent_required (a conversation follow-up whose store has added consent wording since the earlier lead).

Side effects: Creates a single-use ticket that expires after 15 minutes, and CarEdge keeps it until shortly after then. The ticket holds a SHA-256 fingerprint of the shopper's name and contact details, never the details themselves, plus the store, the car, the chosen channels, a fingerprint of the consent wording and the quoted figures when a quote_id was given. Each call counts toward the lead limits. If the shopper says no, nothing more happens and the ticket expires on its own. Nothing is sent to a dealer.

{
  "data": {
    "ticket": "t_<code>",
    "disclosure_text": "<the store's own consent wording>",
    "expires_at": "<15 minutes from now>",
    "rooftop_slug": "<store slug>",
    "rooftop_name": "<store name>",
    "distance_miles": 6.6,
    "routing_reason": "nearest_to_buyer"
  },
  "freshness": null,
  "error": null
}

lead_submit

Sensitive. This tool sends the shopper's name and contact details to a real dealership.

Purpose: Step two. Spends the ticket from lead_prepare, records the lead and emails it to that store's lead inbox. Call it only after the shopper has agreed to the disclosure_text that lead_prepare returned: a clear yes after seeing it, or giving their details after it was shown to them word for word.

Inputs

Key outputs

• lead_id: the lead's UUID.
• status: see Status values for leads.
• rooftop_slug, accepted_at.
• already_sent: true when this user already sent this shopper's lead for this car in the last 24 hours. Nothing new reaches the store, and the answer carries the earlier lead's lead_id and accepted_at.

Idempotency: A ticket makes one lead. Sending exactly the same call again returns the same lead_id with the lead's current status, and nothing is sent twice. A different request on a used ticket answers ticket_used.

Errors: ticket_expired (older than 15 minutes; call lead_prepare again and show the wording again), ticket_used, consent_required (consent missing, or the wording sent back differs from what the ticket was issued for), quote_unavailable, invalid_params (a ticket not issued to this user, changed customer details, or more channels than at prepare), rate_limited (the store has already taken its daily share of AI assistant leads; ask the shopper to call the store directly).

Side effects: Writes the lead and queues it for delivery in one step, then emails it to the store's lead inbox right away. Delivery problems are retried automatically, so the shopper never has to agree twice. See Data handling for exactly what is stored and sent.

{
  "data": {
    "lead_id": "<uuid>",
    "status": "accepted",
    "rooftop_slug": "<store slug>",
    "accepted_at": "<timestamp>",
    "already_sent": false
  },
  "freshness": null,
  "error": null
}

Status values for leads

• lead_submit returns accepted for a new lead.
• Repeating the exact same lead_submit call returns the lead's current status. An already_sent answer from either lead tool carries the earlier lead's current status.
• There is no separate tool to look up a lead's status.
• A failed lead does not count toward the one-lead-per-shopper-per-car limit, so a new lead can be sent. A failed lead cannot be the target of a conversation follow-up.

Other status fields on the read tools

• freshness.status: fresh, stale (older than CarEdge's freshness window; tell the shopper) or no_data.
• binding and taxes_included on a quote: see quote_out_the_door.
• participating: false means the car or store can be described but not quoted or sent a lead.
• in_transit: true means the car is on its way to the store and not on the lot yet.

Errors

These are the only error codes a tool returns in the envelope. Any tool can also answer invalid_params for arguments its schema rejects, rate_limited when a request limit is reached, and out_of_scope when the tool is not granted to the caller.

Rate limits

• Requests: each signed-in user, and each caller that has not signed in, has a limit on requests a minute across all tools: 60 a minute unless CarEdge sets a higher tier for that policy. All callers that have not signed in also share one limit together, 600 a minute by default. Over a limit, calls answer rate_limited with retryable: true.
• Leads prepared per shopper: a limit on lead_prepare calls per shopper per user in any 24 hours, follow-ups included; limits are set per assistant policy. Past that, the answer is the earlier lead with already_sent: true if one was sent for this car, otherwise rate_limited.
• One lead per shopper per car: one lead per shopper per car per user in any 24 hours. A repeat answers already_sent: true with the earlier lead. A lead marked with adds_to (for example a trade-in added later) reaches the store as its own lead.
• Leads per user: a limit on lead_prepare calls per hour per signed-in user; limits are set per assistant policy.
• Leads per store from AI assistants: each store takes at most 25 leads a day from all AI assistant users together, counted when a lead is sent. Past that, lead_submit answers rate_limited.
• Search pages: up to 20 cars per page for an AI assistant (100 for a partner key). The default page size is the dealer's setting, 10 unless changed.
• Answer size: any answer over 64 KB is refused as too_broad, never cut short.
• Request size: request bodies over 64 KB are refused.
• Lifetimes: a lead ticket lasts 15 minutes; a quote lasts 24 hours.

Data handling

Read tools (every tool except lead_prepare and lead_submit) take search filters, a VIN, a dealer name, a car's year, make and model, prices, and a ZIP code or a state and county. decode_vin and check_vehicle_recalls pass the VIN or the year, make and model to NHTSA's public services; estimate_trade_in, for a signed-in user who gives a VIN, passes it to Vehicle Databases. The server never asks for a street address or precise location. The ZIP sets the distance to a store and the tax on a quote. None of these tools takes a name, email address or phone number. CarEdge does not see the rest of the conversation, only the arguments the assistant sends to a tool.

Audit record on every call: the signed-in user's ID (for a caller that has not signed in, a hashed ID, not its raw IP address), the tool, the time, the result or error code, the response time, and a SHA-256 hash of the arguments. The argument values themselves are not stored in the audit record or written to logs.

lead_prepare takes the shopper's first name, optional last name, email address and/or phone number, the contact channels they agreed to, and optionally a ZIP, comments and a quote_id. It stores only a SHA-256 fingerprint of the name and contact details in the ticket record, never the details themselves. Nothing leaves CarEdge.

lead_submit takes the same shopper details, the consent wording and agreement, the channels, optional comments and an optional trade-in car (year, make, model, trim, VIN, mileage, appraisal and who appraised it). It then:

1. Stores the lead: the shopper's name, email and phone encrypted at rest (AES-256-GCM), plus the channels, comments, trade-in details, the quoted figures from the quote_id (car, total, store, state and county), the status, the time, and the name of the AI assistant used.
2. Emails the lead to that one store's lead inbox as an ADF (Auto-lead Data Format) XML document. The email contains the shopper's name, email and phone, the car and its asking price, the comments, the contact channels the shopper agreed to, any trade-in, the total CarEdge quoted (when the shopper saw a quote), and the name of the AI assistant used.

The dealer receives its own copy of the lead by email and handles it under its own privacy policy. A lead goes only to the one store the ticket names, and only after the consent check passes. Through an AI assistant every lead needs the shopper's yes; only a partner key may send a lead without one, and only at a store that asks for no consent wording.

Read the full CarEdge Privacy Policy and Terms of Use.

Disconnect and delete

To stop CarEdge, open your assistant's connector settings and disconnect or remove CarEdge. To delete your CarEdge data, use the privacy request form or email [email protected]. A dealer that already received your request keeps its own copy; ask that dealer directly to delete it.

Support

Email [email protected].

Dealer widgets and partner API keys

This section is for CarEdge's dealer website chat (the CarEdge widget) and other partners that connect with a CarEdge API key. It does not apply to AI assistants such as Claude or ChatGPT, which get the 14 tools above. A partner key can hold more tools, and some answer differently for a key than for an assistant.

Where each tool works

The server offers 33 tools, but a caller sees and can call only the tools its access lists.

CarEdge sign-in. No tool here reads anything stored in the shopper's own CarEdge account. In an AI app the shopper signs in with a CarEdge account only to contact a dealer; the tools never read that account's garage, deals or saved cars. A dealer's website chat needs no sign-in at all.

The CarEdge tools that work on a signed-in account are not on this server and are only in the CarEdge assistant on caredge.com: My Garage (the shopper's own cars and their values), saved cars, deals and the CarEdge AI Buying Agent's negotiations (offers, counter-offers, drafts, follow-ups), and the shopper's saved profile and past conversations.

Some tools also need an outside source to be connected before they answer; until then they answer upstream_unavailable:

• DataOne: get_vehicle_specs, lookup_vehicle_colors, lookup_invoice_price, analyze_deal, market_insights.
• Vehicle Databases: get_market_value, estimate_trade_in (by VIN), analyze_deal.
• MarketCheck: check_manufacturer_incentives, parse_vehicle_link (listing links), analyze_deal.
• Circle: search_community (answers no threads rather than an error).
• An AI model: research_vehicle_value (gives market figures without it), parse_vehicle_link (skips reading the page), draft_negotiation_message.
• CarEdge price history: lookup_price_history (answers "not tracked yet" without it).
• CarEdge cost-to-own data: lookup_cost_to_own, lookup_depreciation_curve.

Everything else answers from data this server already holds: the dealers' cars, CarEdge's marketplace listings, the Dealer Transparency Index, and NHTSA's free VIN and recall data.

Every tool on a partner key

"Where it works" is where a tool can be used once it is granted; see Where each tool works for who grants what and which tools need an outside source connected first.

Every call, on every tool, also writes an audit record (see Data handling).

Research tools on partner keys

These four answer exactly as the CarEdge assistant's own tools of the same names do, so a dealer widget gets the same answer whichever server runs them. Their answers keep that shape: dollar amounts are plain numbers, and some answers carry notes for the assistant.

• decode_vin (vin): year, make, model, trim, body, fuel, drivetrain and engine from NHTSA's free VIN decoder. When the VIN is a car on this dealer's lot, it also says so (in_dealer_stock, store_name).
• check_vehicle_recalls (year, make, model): NHTSA recall campaigns, at most 10 listed, with the full count. upstream_unavailable means NHTSA did not answer.
• analyze_bundle_deal (vehicles, optional fees, cash, trade-in and the dealer's combined quote): itemized totals for a multi-car or cash-plus-trade deal, and whether a combined quote already includes the doc fees.
• calculate_finance_payment (vehicle_price, optional down payment, trade-in, term, APR, state): the monthly payment with a state-level tax estimate, or a breakdown by credit tier when no APR is given.

Two more read CarEdge's Dealer Transparency Index, built from verified out-the-door quotes:

• predict_otd_price (listing_price_cents, dealer_name, vehicle_make): the out-the-door price that dealer's quote history predicts, in cents, with its doc fee and add-on averages. not_found when we hold no history for that dealer.
• lookup_dealer_transparency (dealer_name, optional state, vin, vehicle_make, vehicle_model): the dealer's grade (A to F), fees, add-ons and price accuracy, its latest quotes, and the state and national average doc fee. A name that matches stores in two states with nothing to tell them apart gets no grade rather than a guess.

Three more read CarEdge's marketplace listings, every dealer's, not only this one's:

• get_vehicle_features (vin, or make, model, optional trim, year, condition): the car's high-value features, or for a car named without a VIN the features every sampled listing of that trim shares.
• analyze_days_on_market (make, model, optional vin, year, days_on_market): how long the car has been listed against similar cars, and the negotiating leverage that suggests. A one-price retailer gets no_haggle: true instead.
• compare_dealer_prices (year, make, model, optional trim, asking_price in cents, zip_code, radius_miles, condition): the cheapest comparable listings at other dealers, the price range and where the asking price ranks.

Two more read CarEdge's cost-to-own and depreciation data, by make and model:

• lookup_cost_to_own (make, model, optional ownership_years, default 5): the total cost to own in dollars, split into depreciation, maintenance, insurance, fuel, interest and fees, the figures for every ownership length held, and the five cheapest to own at a similar new price.
• lookup_depreciation_curve (make, model): the predicted used price and percent of value kept at each age, newest model years first, and the age with the steepest drop.

Three more ask outside services CarEdge pays for:

• get_market_value (vin, optional mileage, state): Vehicle Databases' trade-in, private-party and dealer-retail values by condition. not_found when it holds nothing for that VIN.
• check_manufacturer_incentives (make, optional model, year, zip_code): MarketCheck's active manufacturer offers, grouped by type, within 100 miles of the ZIP when one is given. upstream_unavailable when MarketCheck could not be asked.
• search_community (query, optional limit up to 10): matching threads from the CarEdge community forum, each with its permalink. Nothing found and the forum being unreachable look the same: an empty list.

Two more ask DataOne, a vehicle data service:

• get_vehicle_specs (vin, or year, make, model and optional trim): engine, transmission and basic data. When several trims match, the error lists them; call again with one. No fuel economy, dimensions, towing or seating.
• lookup_vehicle_colors (vin, optional year, make, model, trim): the factory exterior and interior colors for that VIN's trim, and the car's on-lot exterior color when it is listed on CarEdge. Needs a VIN.

Two more value a car or its price over time:

• lookup_price_history (vin, optional is_new): every tracked price change for a listing on CarEdge, in whole dollars, with the net change. has_history: false when the listing is not tracked yet.
• estimate_trade_in (year, make, model, optional vin, trim, mileage, condition): with a VIN, Vehicle Databases' trade-in value for that trim and condition; otherwise an estimate from comparable used listings nationwide, in cents, labelled as such. not_found when no comparable listing has a price.

Three more put a price in context, from those services and CarEdge's listings:

• lookup_invoice_price (vin, or year, make, model and optional trim; optional listed_price, is_new): MSRP, invoice price and the dealer's margin in whole dollars, and the car's days on market when it is listed on CarEdge. For a new car with a listed price, the MSRP is that sticker. When several trims match, the error lists them.
• analyze_deal (year, make, model, asking_price_cents, optional trim, vin, mileage, condition, seller_type): a deal rating and score, the fair market value and how it was weighed from book value, comparable listings and invoice, suggested offer and target prices, and a rough out-the-door figure at a default 7% tax and $600 in fees.
• market_insights (vin, optional asking_price_cents, listed_price, is_new, trim, mileage, condition, zip_code): the two above plus the dealer's transparency grade, for one listed car.

Three more ask an AI model (Anthropic's Claude):

• research_vehicle_value (year, make, model, optional trim, mileage, condition, zip_code): price statistics over up to 15 comparable CarEdge listings, and the model's fair-value estimate, demand level and factors. not_found when there are no comparables.
• parse_vehicle_link (url): the car and seller behind a listing link, from CarEdge's own listings, MarketCheck, the public page itself (never a private or internal address) or an NHTSA VIN decode. invalid_params for a link that cannot be read.
• draft_negotiation_message (vehicle_description, asking_price_cents, seller_type, channel, optional target, seller name, market value and leverage points): an opening message to a seller for the shopper to review. upstream_unavailable when the model could not be reached.

None of these tools takes a shopper's name, email address or phone number.