CarClever

Analyze the purchase risk of a specific used car and help users decide. Use this tool when: **DECISION-MAKING INTENT:** - "Should I buy this car?" - "Is this a good deal?" - "Worth buying?" - "Should I walk away?" - "Any red flags?" **RISK INTENT:** - "Should I trust this car?" - "Check this VIN" - "Accident history?" - "Flood damage?" - "Open recalls?" - "Is this risky?" - Title issues, salvage history, odometer concerns **NEGOTIATION INTENT:** - "What should I pay for this?" - "Fair price?" - "Dealer asking too much?" - "What's a good offer?" - "How much below asking?" **Returns a RED/YELLOW/GREEN go/no-go decision gate** plus: title brand verification (salvage, rebuilt, flood, fire, theft, lemon), odometer rollback indicators, NHTSA safety recalls, repair-reserve estimates, negotiation target price, pre-purchase inspection checklist, and a Carfax history report link when available. Call this after search-used-cars returns a candidate the user wants to evaluate, or when the user references a specific vehicle by label, VIN, or position from earlier results. **Operating notes:** - When the user clicks an 'Analyze deal risk' button or asks risk-evaluation questions about a specific vehicle, call this tool directly rather than answering conversationally — the tool's structured output is the appropriate response. - When the invocation includes structured vehicle data (VIN, year, make, model, price, mileage), extract and pass each value to the corresponding parameter rather than inferring from text alone. The VIN is required for full analysis; when the user references a vehicle by label (e.g., 'Option A', 'B'), extract the VIN from the previous search results. - One tool call per request; do not retry with modified VIN or parameters if the call returns sparse data. - Recommend the user verify findings against an independent vehicle history report before purchase. - For EVs (when fuel_type indicates electric), the inspection checklist focuses on battery, charging, and software, not engine and oil items. Hybrids are not EVs and receive the standard checklist. **Do not use for:** general "is X model reliable" research questions, new-car risk assessment, or non-U.S. vehicles.

analyze-deal-risk

Calculate affordability and total ownership cost for a specific used car. Use this tool when: **FINANCIAL INTENT:** - "Can I afford this?" - "What's the monthly payment?" - "How much would it cost?" - "True ownership cost?" - "Insurance plus payment?" - "5-year cost?" - "What's the total cost?" - Any payment or cost question about a vehicle previously shown in search results — even without explicit "affordability check" language **COMPARISON INTENT (cost-focused):** - "Is this one more expensive than that one?" - "Which costs less over 5 years?" - "Compare monthly payments: A vs B" Takes a VIN or vehicle reference (price, year, make, model, mileage, fuel_type, mpg_city, mpg_highway) plus optional financial inputs (credit score, down payment, loan term, annual mileage, ZIP code, driver age) and returns: estimated financing cost at current APR rates, estimated insurance, fuel or charging cost, maintenance reserve, registration fees, total estimated monthly payment, and 5-year ownership cost estimate with depreciation. Gives users a complete picture of what a car will cost beyond the sticker price. All figures are estimates with assumptions disclosed. Call this after search-used-cars when the user asks about affordability or monthly cost for a specific vehicle. Allow recalculation with custom credit score, down payment, loan term, or annual mileage when the user provides them. **Operating notes:** - When the user clicks an 'Affordability check' button or asks specific affordability questions about a vehicle, call this tool directly. Pass price, year, make, model, and mileage from previous search results when available; passing price directly produces accurate results even if VIN-based price lookup fails. - When the invocation includes structured vehicle data (VIN, year, make, model, price, mileage), extract and pass each value to the corresponding parameter rather than inferring from text alone. - For EVs (when fuel_type indicates electric), the cost label is "Energy / charging" rather than "Fuel". - Always disclose APR, term, down payment, and annual mileage assumptions in the response. - Distinguish loan affordability from total ownership affordability in the output. **Do not use for:** new-car lease calculations, generic "what's the average cost of owning a car" questions, or insurance quotes (this tool produces estimates, not quotes).

calculate-affordability

Compares multiple specific vehicle listings side-by-side. Useful when a user wants to decide between vehicles from a prior search, e.g. "Compare A vs B", "Which one should I buy?", "Which is better?", "Rank these", "Best option?" Returns a side-by-side comparison covering price, mileage, year, trim, dealer, location, Deal Score, estimated monthly cost, risk indicator, recall status, market-value gap, best-use case, and main concern for each vehicle. Accepts labels (A, B, C…) from any search-used-cars call in this session, including paginated Load More results. The tool resolves labels from the full accumulated session store and reports clearly if a label cannot be resolved. **Operating notes:** - Maximum eight vehicles per comparison. - Trim and drivetrain differences are surfaced explicitly when comparing similar models. - After invoking, the widget renders the comparison — a brief follow-up prompt is sufficient rather than restating the data in text. **Do not use for:** comparing generic vehicle models without specific listings (e.g., "RAV4 vs CR-V" as a research question — that is conversational, not a tool call).

vehicle-comparison

Call this tool when a user is actively shopping for a used car. **TIER 1 — INVENTORY INTENT:** User wants to find or search live inventory: - "Find me a used Mazda CX-5" - "Show me Camrys for sale" - "What's available near me?" - "Find a truck under $40k" **TIER 2 — PURCHASE INTENT:** User is looking to buy but needs options: - "I'm looking for an SUV" - "Need a reliable commuter" - "Shopping for my first car" - "Help me buy a used Tacoma" **TIER 3 — CATEGORY / LIFESTYLE INTENT:** User describes a lifestyle or life situation: - "Family SUV for three kids" - "College student car, budget under $20k" - "Adventure SUV for camping" - "Work truck for towing" - "Safe car for my teenager" / "teen driver car" - "Reliable hybrid for a long commute" - "Snow vehicle with AWD" - "Retirement car — comfort and easy entry" - "Off-road SUV for overlanding" - "Best value budget car" **TIER 4 — FEATURE INTENT:** User has specific feature requirements: - "Find a low mileage AWD SUV under $35k" - "CPO (Certified Pre-Owned) sedan" - "Hybrid with Apple CarPlay" - "Third-row SUV with leather" - "Dependable / reliable / safe / low risk" (reliability qualifiers influence model selection toward proven models) **Do NOT use for** general research questions that don't require live inventory: - "Is Honda Accord reliable?" → respond conversationally - "Toyota vs Honda?" → respond conversationally - New-car configurators, lease quotes, motorcycle/RV listings, markets outside the U.S. Handles searches by: - **Make and model** ("Honda Civic", "Toyota RAV4", "Ford F-150") - **Category** ("family SUV", "3-row SUV", "large SUV", "full-size SUV", "work truck", "off-road truck", "pickup", "commuter sedan", "daily driver", "luxury SUV", "EV", "electric car", "hybrid", "plug-in") - **Budget** ("under 30k", "below $40,000", "around 25k", "cheap") - **Location** (ZIP code or city: "near Dallas", "in 90210") - **Features** ("AWD", "leather", "low mileage", "reliable", "safe", "dependable", "CPO", "Apple CarPlay", "third row") Returns up to 50 vehicles. By default results are sorted by **Recommended** — a blend of deal quality (0–100 Deal Score), budget utilization, and recency that surfaces newer, well-priced vehicles closely matching the stated budget. The sort parameter also accepts 'deal_score' (pure Best Deal ranking), 'price_low'/'price_high', 'mileage_low'/'mileage_high', and others. Each result includes price, mileage, year, dealer location, market-value comparison, Carfax history link when available, and CPO indicator for certified pre-owned listings. If initial results are empty the tool automatically expands the search radius and ultimately searches nationwide — results will reflect the expanded scope. Use this tool when a used-car shopping intent is present. Downstream CarClever tools (`analyze-deal-risk`, `calculate-affordability`, `vehicle-comparison`) operate on results from this search. **Operating notes:** - Make one tool call per user request. If results are unsatisfactory, ask the user to refine their query rather than retrying with modified parameters. - For pagination ("load more", "show more results"), re-invoke this tool with `offset` set based on the previous response's `offset + limit`. - On an initial search, omit the `limit` parameter to use the default of 6.

search-used-cars

Retrieves comprehensive vehicle information including photos, specifications, recall history, and dealer contact information. Used internally by the widget for detailed vehicle views.

get-vehicle-details

Resolves a vehicle's dealer listing URL. Returns a marketplace listing page when make, model, year, and VIN are available. Returns null when make, model, or year is missing — no fallback URL is constructed.

resolve-dealer-url

Remove a previously saved vehicle from your garage. Examples: • Remove the Honda Civic from my garage • Delete VIN 1HGBH41JXMN109186 from my garage • Unsave this vehicle • Remove this car from my favorites

garage-remove

Save a vehicle to the user's shortlist for later reference. Useful when a user wants to bookmark, favorite, or track a specific listing, e.g. "Save this car", "Keep this one", "Add to my shortlist", "Save vehicle A to my garage". Stores: VIN, make, model, year, trim, price, deal score, dealer info, and photo. `photo_url` is optional but improves the garage view — it can be sourced from search-used-cars results. If a photo URL is not available in the current context (e.g. after analyze-deal-risk or calculate-affordability), calling get-vehicle-details(vin) first will return the full vehicle record including the photo URL.

garage-save

Show saved vehicles. Use this when a user wants to: - "Show my garage" - "View my saved cars" - "What vehicles have I saved?" - "Show my favorites" - "My shortlist" - "What cars did I bookmark?" - "My garage" Returns all saved vehicles with make, model, year, price, deal score, dealer info, and save date.

garage-list