Skip to main content
Glama

Search EV listings

search_listings
Read-onlyIdempotent

Search every electric and plug-in hybrid vehicle listed for sale in the United States that Census tracks — new, used and certified, from dealers' own sites and manufacturer inventory. Returns matching listings with price, mileage, location, the seller's name and website, a seller link that forwards through censusev.com to the dealer's own page for the car, and the EV facts the site stands behind (battery kWh, EPA range, charge port, heat pump, DC fast charging), each marked estimated when it is not the manufacturer's own figure. Also returns a breakdown of every matching car, not only the returned page: cars per model year, cars per trim (top 8, when every match is one model), and the lowest, median and highest asking price. Each record carries last_seen, the day the car was last seen for sale. asking_vs_similar ("below", "typical" or "above") compares the asking price with similar cars on Census EV: the same version and model year within 40,000 miles, adjusted for mileage, counting cars listed now and cars no longer listed in the last 30 days at their last asking price. It compares asking prices and is not an appraisal. "below" and "above" need a gap of at least $1,000 that is also wider than the usual spread of asking prices for that version: for most cars about 3 to 7% over for "above" and about 5 to 9% under for "below", more where few similar cars are known, and "below" must still hold with any one similar car left out. Otherwise it is "typical". Absent when the car could not be compared: new or under 2,000 miles, no asking price or mileage, a disclosed buyback or branded title, fewer than 3 similar cars, similar cars that are not all one version, or an asking price so far under them that the gap is more than 30% of it. Inventory is as of the as_of timestamp in the result.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_listings"
  }
}

Input Schema

NameRequiredDescriptionDefault
zipNo5-digit US ZIP; results are limited to radius_mi of it and sorted by distance unless sort is given.
bodyNoComma-separated: "suv", "sedan", "truck", "van", "hatchback".
kindNoBattery-electric or plug-in hybrid. A car whose kind is not established matches neither; the result counts those in not_established.kind.
makeNoMake, e.g. "Tesla", "Hyundai".
sortNoResult order. distance needs a zip. Default: distance when a zip is given, otherwise price_asc.
driveNoComma-separated: "AWD", "RWD", "FWD".
limitNoResults to return, 1 to 100. Default 25.
modelNoModel, e.g. "Model Y", "Ioniq 5". Punctuation and spacing are ignored.
stateNoComma-separated two-letter state codes, e.g. "CA,OR".
detailNoHow much of each record to return. Default "compact", which leaves out id (the VIN in lower case), image_url, location.zip, location.lat, location.lng, previous_price_usd, price_changed_at, listed_on and first_seen. "full" returns every field.
offsetNoResults to skip, for paging. Default 0.
kwh_minNoMinimum battery capacity in kWh.
year_maxNoLatest model year to include.
year_minNoEarliest model year to include, e.g. 2022.
conditionNoComma-separated: "new", "used", "certified".
heat_pumpNoOnly cars known to have (yes) or not have (no) a heat pump. Cars where it is not established match neither, and are counted in not_established.heat_pump.
price_maxNoMaximum asking price in USD. Cars with no real asking price are excluded when a price bound is given.
price_minNoMinimum asking price in USD.
radius_miNoSearch radius around zip, in miles. Default 100.
range_minNoMinimum EPA range in miles (electric-only for a plug-in hybrid).
charge_portNoComma-separated: "NACS", "CCS1", "CHAdeMO".
mileage_maxNoMaximum odometer reading in miles. Cars with no stated mileage are excluded when this is given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / detail / description
      Previous value: -"How much of each record to return. Default \"compact\", which leaves out id (the VIN in lower case), image_url, location.zip, location.lat, location.lng, previous_price_usd, price_changed_at, listed_on, first_seen and last_seen. \"full\" returns every field."New value: +"How much of each record to return. Default \"compact\", which leaves out id (the VIN in lower case), image_url, location.zip, location.lat, location.lng, previous_price_usd, price_changed_at, listed_on and first_seen. \"full\" returns every field."
  2. Changed1 schema field changed
    • addedInput schema / properties / detail
      Added value: +{
      +  "description": "How much of each record to return. Default \"compact\", which leaves out id (the VIN in lower case), image_url, location.zip, location.lat, location.lng, previous_price_usd, price_changed_at, listed_on, first_seen and last_seen. \"full\" returns every field.",
      +  "enum": [
      +    "compact",
      +    "full"
      +  ],
      +  "type": "string"
      +}
  3. Changed2 schema fields changed
    • changedInput schema / properties / heat_pump / description
      Previous value: -"Only cars known to have (yes) or not have (no) a heat pump. Cars where it is not established match neither."New value: +"Only cars known to have (yes) or not have (no) a heat pump. Cars where it is not established match neither, and are counted in not_established.heat_pump."
    • changedInput schema / properties / kind / description
      Previous value: -"Battery-electric or plug-in hybrid."New value: +"Battery-electric or plug-in hybrid. A car whose kind is not established matches neither; the result counts those in not_established.kind."
  4. Changed10 schema fields changed
    • addedInput schema / properties / heat_pump / description
      Added value: +"Only cars known to have (yes) or not have (no) a heat pump. Cars where it is not established match neither."
    • changedInput schema / properties / limit / description
      Previous value: -"Default 25."New value: +"Results to return, 1 to 100. Default 25."
    • addedInput schema / properties / mileage_max / description
      Added value: +"Maximum odometer reading in miles. Cars with no stated mileage are excluded when this is given."
    • addedInput schema / properties / offset / description
      Added value: +"Results to skip, for paging. Default 0."
    • changedInput schema / properties / price_max / description
      Previous value: -"USD. Cars with no real asking price are excluded when a price bound is given."New value: +"Maximum asking price in USD. Cars with no real asking price are excluded when a price bound is given."
    • changedInput schema / properties / price_min / description
      Previous value: -"USD."New value: +"Minimum asking price in USD."
    • changedInput schema / properties / radius_mi / description
      Previous value: -"Default 100."New value: +"Search radius around zip, in miles. Default 100."
    • addedInput schema / properties / sort / description
      Added value: +"Result order. distance needs a zip. Default: distance when a zip is given, otherwise price_asc."
    • addedInput schema / properties / year_max / description
      Added value: +"Latest model year to include."
    • addedInput schema / properties / year_min / description
      Added value: +"Earliest model year to include, e.g. 2022."
  5. First observed

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior beyond them: inventory freshness via the `as_of` timestamp, `last_seen` recency per record, estimated-vs-manufacturer figures flagged per field, and an explicit caveat that asking_vs_similar 'compares asking prices and is not an appraisal'. It does not address rate limits, result caps beyond the schema, or reliability, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, but roughly two-thirds of the text is a deep digression on asking_vs_similar thresholds (3–7%, 5–9%, the $1,000 gap, the leave-one-out rule). That detail is defensible because there is no output schema, yet it is buried mid-paragraph and pushes the search capability itself out of focus.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter search tool with 22 filters and no output schema, the description carries the return-value burden well: record fields, the aggregate breakdown (model year, top-8 trim, min/median/max price), conditional presence of asking_vs_similar, and inventory timestamp. An agent can form a correct call and interpret the response without further documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 22 parameters is already documented in structured data, including defaults, enums, and exclusion behavior for missing price/mileage. The description adds almost no per-parameter meaning beyond noting that unmatched `kind`/`heat_pump` values land in not_established, which the schema also states. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource with explicit scope: 'Search every electric and plug-in hybrid vehicle listed for sale in the United States', including new/used/certified and source coverage. It never names a sibling (get_listing, compare_listings, market_snapshot), so the agent must infer the boundary from the scope statement alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the described capability — filters, sorting, and the per-year/per-trim price breakdown make it clear this is the broad query tool. There is no explicit when-to-use, no when-not-to-use, and no routing to get_listing or compare_listings, so the agent gets context but no decision rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources