Car Handshake

Shop vehicles

shop_vehicles

Read-onlyIdempotent

Search and rank participating US/Canadian dealer cars, SUVs, trucks, EVs, motorcycles, RVs and trailers by place (including near me), budget, mileage, make/model, condition, body, fuel and features. Quebec excluded. Accepts the shopper’s wording and optional structured filters. Named-dealer stock uses a dealer_id from find_dealerships. Returns a ranked page, total and geographic fallback details. Coverage and equipment evidence are partial; zero matches do not establish market-wide absence.

Input Schema

Name	Required	Description
`fuels`	No
`limit`	No
`makes`	No
`trims`	No
`bodies`	No
`cursor`	No
`models`	No
`country`	No	US default; CA supported outside Quebec.
`request`	Yes	Verbatim shopper request.
`sort_by`	No	Default: relevance.
`features`	No	Classes: third_row, awd_4wd, tow_package, apple_carplay, android_auto, adaptive_cruise, leather, heated_seats, ev_range_200_plus.
`statuses`	No	Omit unless status is explicit; omission searches both available and intransit.
`year_max`	No
`year_min`	No
`price_max`	No
`price_min`	No
`conditions`	No
`dealer_ids`	No
`drivelines`	No
`nationwide`	No
`mileage_max`	No
`charge_ports`	No
`radius_miles`	No	US miles; CA kilometres. Fallback widens geography only; filters remain exact.
`location_text`	No	Free-text city/place/state/postal exactly as the shopper supplied; never ask for a ZIP code.
`transmissions`	No
`vehicle_types`	No
`dc_fast_charge`	No
`sort_direction`	No
`exterior_colors`	No
`interior_colors`	No
`electric_range_max`	No
`electric_range_min`	No
`displacement_cc_max`	No
`displacement_cc_min`	No

Output Schema

Name	Required	Description	Default
`total`	Yes
`matches`	Yes
`coverage`	Yes
`fallback`	Yes
`freshness`	Yes
`next_action`	Yes
`next_cursor`	Yes
`total_relation`	Yes
`applied_filters`	Yes
`interpreted_request`	Yes
`suggested_relaxations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedAug 18, 2026

removedInput schema / properties / conditions / description

Removed value: -"New, used, or certified pre-owned (cpo)."

changedInput schema / properties / country / description

Previous value: -"US default; CA for Canada. Quebec excluded."New value: +"US default; CA supported outside Quebec."

changedInput schema / properties / features / description

Previous value: -"Feature classes: third_row, awd_4wd, tow_package, apple_carplay, android_auto, adaptive_cruise, leather, heated_seats, ev_range_200_plus. Unknowns are disclosed."New value: +"Classes: third_row, awd_4wd, tow_package, apple_carplay, android_auto, adaptive_cruise, leather, heated_seats, ev_range_200_plus."

changedInput schema / properties / radius_miles / description

Previous value: -"US miles; CA kilometres. Zero results widen radius, state/province, then countrywide; filters stay exact; fallback reports stage."New value: +"US miles; CA kilometres. Fallback widens geography only; filters remain exact."

changedInput schema / properties / request / description

Previous value: -"The shopper's natural-language request, verbatim."New value: +"Verbatim shopper request."

changedInput schema / properties / sort_by / description

Previous value: -"Result order; default relevance."New value: +"Default: relevance."

removedInput schema / properties / vehicle_types / description

Removed value: -"Vehicle categories, including motorcycles, RVs, and trailers."

Changed8 schema fields changedAug 18, 2026

addedInput schema / properties / country

Added value: +{
+  "description": "US default; CA for Canada. Quebec excluded.",
+  "enum": [
+    "US",
+    "CA"
+  ],
+  "type": "string"
+}

changedInput schema / properties / features / description

Previous value: -"Features: third_row, awd_4wd, tow_package, apple_carplay, android_auto, adaptive_cruise, leather, heated_seats, ev_range_200_plus. Unknown names are disclosed, not hard-filtered."New value: +"Feature classes: third_row, awd_4wd, tow_package, apple_carplay, android_auto, adaptive_cruise, leather, heated_seats, ev_range_200_plus. Unknowns are disclosed."

changedInput schema / properties / radius_miles / description

Previous value: -"Search radius around the resolved location. If nothing matches, the search widens automatically — double this radius, then statewide, then national — keeping every vehicle filter exact, and reports the stage it stopped at in fallback.applied."New value: +"US miles; CA kilometres. Zero results widen radius, state/province, then countrywide; filters stay exact; fallback reports stage."

removedOutput schema / properties / coverage / properties / country / const
```
Removed value: -"US"
```
addedOutput schema / properties / coverage / properties / country / enum
```
Added value: +[
+  "US",
+  "CA"
+]
```
addedOutput schema / properties / matches / items / properties / listing / properties / currency
```
Added value: +{
+  "enum": [
+    "USD",
+    "CAD"
+  ],
+  "type": "string"
+}
```
removedOutput schema / properties / matches / items / properties / listing / properties / location / properties / country / const
```
Removed value: -"US"
```
addedOutput schema / properties / matches / items / properties / listing / properties / location / properties / country / enum
```
Added value: +[
+  "US",
+  "CA"
+]
```

Changed1 schema field changedAug 13, 2026

addedInput schema / properties / radius_miles / description

Added value: +"Search radius around the resolved location. If nothing matches, the search widens automatically — double this radius, then statewide, then national — keeping every vehicle filter exact, and reports the stage it stopped at in fallback.applied."

First observedAug 11, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety and side-effect behavior are covered. The description adds meaningful context beyond annotations: Quebec is excluded, a ranked page plus total and geographic fallback are returned, coverage/equipment evidence is partial, and zero matches do not establish market-wide absence. That is unusually useful transparency for a search tool.

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

Conciseness4/5

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

The description is front-loaded with the core search scope and then appends the important caveats about dealer_id sourcing, return shape and coverage limits. It is dense but efficient, with no obvious filler. A slight restructuring could make the filter categories and return details easier to scan, but it is well within acceptable length.

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

Completeness4/5

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

Given a large search surface with an output schema, the description supplies the critical behavioral context: supported countries, Quebec exclusion, dealer-specific lookup via find_dealerships, ranked pagination, geographic fallback and partial coverage caveats. It does not explain pagination mechanics, limit behavior or every filter category, so it is not fully complete, but it covers the operational essentials for calling the tool correctly.

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 low (21%) across 34 parameters, so the description must carry more semantic weight. It groups the main filters (place, budget, mileage, make/model, condition, body, fuel, features) and states that named-dealer stock uses dealer_ids from find_dealerships, but it does not cover many parameters such as trims, drivelines, transmissions, colors, charge ports, electric range, displacement, nationwide, statuses, cursor or limit. The schema itself documents a few key fields (country, features, statuses, radius_miles, location_text), so the description adds partial value but leaves significant gaps.

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

Purpose5/5

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

The description names a specific verb and resource ('Search and rank participating US/Canadian dealer cars...') and enumerates the covered vehicle categories and ranking dimensions. It also distinguishes itself from the sibling tool find_dealerships by explaining that named-dealer stock uses a dealer_id from that tool. An agent can tell this is the broad vehicle shopping search rather than a detail or comparison tool.

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

Usage Guidelines4/5

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

Usage is clear for the main scenario: search by place, budget, mileage, make/model, condition, body, fuel and features, and it explicitly routes dealer-specific stock through find_dealerships. It does not explicitly exclude or compare against siblings like get_vehicle or compare_vehicles, but the context is strong enough to imply when this is the right entry point.

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

All Car Handshake tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?