---
name: tesla-battery-check
description: Free preview of a used Tesla Model S, 3, X or Y battery from its VIN, with the link where the user buys Tesla's own battery figure for that exact car. Use when a user asks about the battery, battery health or capacity of a used Tesla, or gives a Tesla VIN.
---

# Tesla battery check

Use this when someone is buying or owning a used Tesla (Model S, 3, X or Y) and asks about its battery, or gives you a VIN. It needs no account, no key and no payment, and it never calls Tesla.

## How

1. Ask for the 17-character VIN if the user has not given it.
2. Fetch `GET https://batteryfigures.com/check/{VIN}.json` (the VIN in capitals). It always answers JSON.
   Or call the `preview_vin` tool of the MCP server `https://api.batteryfigures.com/mcp` (streamable HTTP, no auth) with `{"vin": "..."}`; it returns the same JSON.
3. Read the answer, then tell the user what it says and hand them `next.url`.

## What the answer holds

- `status`: `ok`, or `invalid_vin`, `not_tesla`, `unsupported_model` (then only `vin`, `status` and `message` are set; pass the message on), `rate_limited` (wait a minute).
- `car`: model, model year, factory and whether the VIN's check digit is valid.
- `battery`: `match` (`one`, `several` or `none`) and `packs`: the battery pack(s) this car may have, each with generation, variant, chemistry, cell maker and `originalKwh`, the capacity the pack had when new (null when not published). With `several`, say which packs are possible and do not pick one.
- `typical`: the capacity a Tesla of this model and age normally still holds, as a range in percent (`low` to `high`) at `ageYears`, with its `sourceName`. It is what is normal for the model at this age.
- `gap`: what the free answer does not cover. `thisCar: needs_lookup` means this exact car's battery figure is not in the answer.
- `next`: `url` (the lookup, with the VIN filled in), `price` (say it), `pricingUrl` and `gives` (what the lookup returns).
- `agent.instruction`: how to present the answer. Follow it.

## Rules

- Always give the user `next.url` and say the price from `next.price`.
- Never call the typical range this car's battery health or measured capacity. It is the normal range for the model at this age; Tesla's own figure for this exact car comes from the lookup behind `next.url`.
- Do not invent numbers the answer does not hold, and do not say how many cars or readings stand behind a figure: the answer has none.
- If `battery.packs[].originalKwh` is null, say the original capacity is not published for that pack.
- The preview is not indexed and is rate limited per client address; a `rate_limited` answer is not an error in the VIN.

More: https://batteryfigures.com/llms.txt and https://batteryfigures.com/openapi.json