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

Help users decide between multiple vehicles by comparing them side-by-side. Use this tool when: **COMPARISON INTENT:** - "Compare A vs B" - "Which one should I buy?" - "Which is better?" - "Rank these three" - "Narrow this list" - "Best option?" - "Top pick?" - "Show me alternatives" - User asks to compare options by label (A, B, C…) from any search-used-cars call in this session, including paginated Load More results 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. Call this after search-used-cars returns results. The tool resolves labels from the full accumulated session store across all search pages — **always invoke this tool with the labels the user requested and let the tool report if resolution fails**. Never block or refuse the request agent-side; invoke the tool and let it handle label resolution. **Operating notes:** - Maximum eight vehicles per comparison. - Always call the tool with whatever labels the user provides — the tool handles resolution and returns a clear error if a label is genuinely unavailable. - Trim and drivetrain differences should be surfaced explicitly when comparing similar models. - After invoking, do not summarize or restate the comparison data in text — the widget is the response. A brief follow-up like 'What would you like to do next?' is sufficient. **Do not use for:** comparing generic vehicle models without specific listings (e.g., "RAV4 vs CR-V" as a research question — that's conversational, not a tool call).

vehicle-comparison

Call this tool when a user is actively shopping for a used car. **TIER 1 — INVENTORY INTENT (Highest Priority):** 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 (Very High Priority):** 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 ranked by a 0–100 Deal Score (budget fit, age, mileage, market value, reliability). 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. Call this **first** 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 your shortlist for later. Use this when a user wants to: - "Save this car" - "Bookmark this" - "Keep this one" - "Favorite this" - "Remember this car" - "Add to my shortlist" - "Save vehicle A to my garage" - "Add option B to my favorites" Stores: VIN, make, model, year, trim, price, deal score, dealer info, and photo. **PHOTO PRE-FETCH RULE (required):** Before calling this tool, check whether `photo_url` is available in your current context. Some tool responses (e.g., `analyze-deal-risk`, `calculate-affordability`) do NOT include `photo_url`. If `photo_url` is null or absent, you MUST call `get-vehicle-details(vin)` first to retrieve the complete vehicle record — which includes the photo URL — then pass `photo_url` from that response into this tool. Saving without a photo causes blank image placeholders in the garage view.

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