deal-finder

name	deal-finder
description	Best-deal sourcing and negotiation leverage. Triggers: "find me the best deal", "cheapest option near me", "best price on a", "deal finder", "is this a good price", "should I buy now or wait", "compare deals", "negotiate this price", "find a car for my customer", sourcing best-priced vehicles, validating deal fairness, building negotiation leverage with market data.
version	0.1.0

Date anchor: Today's date comes from the # currentDate system context. Compute ALL relative dates from it. Example: if today = 2026-03-14, then "prior month" = 2026-02-01 to 2026-02-28, "current month" (most recent complete) = February 2026, "three months ago" = December 2025. Never use training-data dates.

get_sold_summary parameter safety:

• Always set inventory_type explicitly (New or Used) — omitting it defaults to New, returning zero results for used-vehicle queries
• Always set limit: 5000 — the default (1000) silently truncates when (months × states × ranking combos) exceeds 1000 rows
• For volume totals, use ranking_dimensions: dealership_group_name (or the single relevant dimension) — never use the default make,model,body_type which creates ~150K rows for national 3-month queries
• Use separate calls for totals vs breakdowns — don't combine in one call

Deal Finder — Source the Best Price, Validate the Deal, Arm the Negotiation

Profile

Load the marketcheck-profile.md project memory file if exists. Extract: zip, radius, dealer_type, country. Note: deal-finder often sources for customers — if sourcing for a customer, ask for customer's ZIP (do not use profile ZIP). US: search_active_cars, predict_price_with_comparables, decode_vin_neovin, get_car_history, get_sold_summary. UK: search_uk_active_cars, search_uk_recent_cars only (Fair Price uses comp median; Market Timing is US-only). Confirm: "Using profile: [dealer.name], [ZIP]"

User Context

Dealer sourcing vehicles for clients or validating deals; needs best price, fair-price proof, and negotiation leverage.

Required	Field	Source
Yes	Year/Make/Model, customer ZIP	Ask
Recommended	Trim, max budget	Ask
Auto/Ask	Radius	Profile or 100mi default
Optional	Mileage pref, color, specific VIN, finance/lease, new/used	Ask

Always confirm new vs used — changes search params and comparables.

Workflow: Best Deal Search

Use this when a dealer says "find me the cheapest 2024 RAV4 XLE near Phoenix" or a customer asks "what's the best deal."

1. Search for the lowest-priced matching units — Call mcp__marketcheck__search_active_cars with year=2024, make=Toyota, model=RAV4, trim=XLE Premium, zip=85281, radius=100, sort_by=price, sort_order=asc, rows=10, car_type=used (or car_type=new if specified). This returns the 10 cheapest matching vehicles in the market. → Extract only: per listing — dealer_name, location, price, miles, dom, distance. Discard full response.

2. Enrich with market context — Call mcp__marketcheck__search_active_cars with the same YMMT and location filters but stats=price,miles, rows=0 to get the market-level statistics (mean, median, min, max, count) without fetching individual listings again. → Extract only: mean, median, min, max, count for price and miles. Discard full response.

3. Score each result — For each of the 10 listings, calculate:

   • Price vs market median (percent below/above)
   • Miles vs market median (higher miles = less desirable, adjust value)
   • DOM (longer DOM = more negotiation leverage)
   • Distance from customer (closer = less friction)

4. Rank and present — Re-rank the 10 listings by a composite score that balances price, miles, DOM, and distance. Present the top 3-5 as recommended options.

5. Deliver the deal sheet — For each recommended unit, show: dealer name, price, miles, DOM, distance, price-vs-market percentage, and a one-line assessment (e.g., "Best overall value — 6% below market, average miles, 42 DOM").

Workflow: Fair Price Validation

Use this when a dealer or customer has found a specific vehicle and asks "is this a good price" or "should I buy this one."

1. Predict the market value — Call mcp__marketcheck__predict_price_with_comparables with the candidate vin, miles (listed odometer), zip (customer's market), dealer_type (match the selling dealer type). Record the predicted price. → Extract only: predicted_price. Discard full response.

2. Compare asking price to predicted value — Calculate the delta:

   • Below market: Asking price is lower than predicted — this is a favorable deal.
   • At market: Within +/- 3% of predicted — fair deal, standard pricing.
   • Above market: Asking price exceeds predicted by more than 3% — the buyer is overpaying unless there are justifying factors (low miles, rare color, certified warranty).

3. Pull competing alternatives — Call mcp__marketcheck__search_active_cars with the same YMMT, zip, radius=100, sort_by=price, sort_order=asc, rows=5, car_type=used. Show the buyer what else is available — if cheaper options exist, cite them. → Extract only: per listing — dealer_name, price, miles, dom, distance. Discard full response.

4. Deliver the verdict — Present a clear buy/negotiate/pass recommendation:

   • Buy: Price is 5%+ below market with acceptable miles and condition.
   • Negotiate: Price is at or slightly above market — there is room to negotiate down, especially if DOM is high.
   • Pass: Price is 5%+ above market and comparable alternatives exist at lower prices within reasonable distance.

Workflow: Negotiation Leverage Report

Use this when a dealer is preparing to negotiate on a specific VIN and needs data to strengthen their position.

1. Pull listing history for the VIN — Call mcp__marketcheck__get_car_history with vin, sort_order=desc. Check how long this specific unit has been listed and whether the price has already been reduced. → Extract only: total_dom, price_history (each date + price), number of dealer hops. Discard full response.

2. Decode the VIN — Call mcp__marketcheck__decode_vin_neovin with vin to confirm exact specs and identify any features that could justify a premium or that the listing may have wrong. → Extract only: year, make, model, trim, key features. Discard full response.

3. Get predicted market value — Call mcp__marketcheck__predict_price_with_comparables with vin, miles, zip. This establishes the data-backed "fair" price. → Extract only: predicted_price. Discard full response.

4. Find competing units — Call mcp__marketcheck__search_active_cars with YMMT, zip, radius=100, sort_by=price, sort_order=asc, rows=10, car_type=used. These are the alternatives the dealer can cite during negotiation ("I can get a comparable unit at Dealer X for $1,200 less"). → Extract only: per listing — dealer_name, price, miles, dom, distance, stock_number. Discard full response.

5. Build the leverage brief — Present:

   • DOM leverage: If the unit has been listed 30+ days, the dealer is motivated. 60+ days = highly motivated.
   • Price drop history: If the dealer already dropped the price, they may drop again. If they haven't dropped in 30+ days, a first offer below asking may trigger a counter.
   • Competing unit citations: List 3-5 specific competing vehicles with dealer name and price that the dealer can reference by name in the negotiation.
   • Suggested offer price: Predicted market value minus a negotiation margin (typically 3-5% below predicted for used, 2-3% for new). Adjust upward if the unit is priced below market or has very low DOM.

Workflow: Finance/Lease Comparison

Use this when a customer asks "what would my payment be" or a dealer needs to compare financing across dealers.

1. Search with finance data — Call mcp__marketcheck__search_active_cars with YMMT, zip, radius=100, include_finance=true, sort_by=price, sort_order=asc, rows=15, car_type=new (finance/lease data is most common on new inventory). → Extract only: per listing — dealer_name, price, monthly_payment, term, apr, down_payment. Discard full response.

2. Search with lease data — Call mcp__marketcheck__search_active_cars with the same filters but include_lease=true, rows=15. → Extract only: per listing — dealer_name, price, monthly_payment, term, money_factor, down_payment, residual. Discard full response.

3. Build the comparison table — For each listing that includes finance or lease data, extract: dealer, selling price, monthly payment, term, APR (finance) or money factor (lease), down payment, and residual (lease).

4. Calculate total cost of ownership — For each option, compute: total payments over term + down payment = total out-of-pocket. This allows apples-to-apples comparison even when terms differ.

5. Present the comparison — Show a table sorted by lowest monthly payment and a separate sort by lowest total cost. Highlight the best overall deal and note any unusually favorable terms (e.g., manufacturer subvented rates, lease loyalty bonuses).

Workflow: Market Timing Advice

Use this when a customer asks "should I buy now or wait" or a dealer needs to advise on timing.

1. Assess current supply — Call mcp__marketcheck__search_active_cars with YMMT, zip, radius=150, stats=price,miles, rows=0, car_type=used. The total count indicates supply depth. The price stats show current market conditions. → Extract only: total_count, mean_price, median_price. Discard full response.

2. Assess recent demand and sell-through — Call mcp__marketcheck__get_sold_summary with make, model, inventory_type=Used, date_from (30 days ago), date_to (today), ranking_dimensions=make,model, ranking_measure=sold_count, ranking_order=desc, limit=5000. This shows how many units sold recently — a proxy for demand velocity. → Extract only: sold_count, average_days_on_market. Discard full response.

3. Compare supply to demand — Calculate the supply-to-demand ratio:

   • Active listings (supply) / Units sold in last 30 days (demand) = months of supply
   • Under 30 days of supply = seller's market (prices rising, buy now)
   • 30-60 days of supply = balanced market (prices stable, reasonable to wait for the right unit)
   • Over 60 days of supply = buyer's market (prices softening, negotiate aggressively or wait for further drops)

4. Check for price trend direction — From the stats in step 1, note the mean and median prices. Call mcp__marketcheck__search_active_cars with price_change=negative, same YMMT and location, rows=0 to count how many dealers are dropping prices. A high percentage of the market dropping prices confirms a softening trend. → Extract only: total_count of price-drop listings. Discard full response.

5. Deliver the timing recommendation:

   • Buy now: Supply is low, demand is high, prices are rising or stable. Waiting risks paying more or missing available units.
   • Buy soon (within 2-4 weeks): Market is balanced. The customer can afford to be selective but should not wait indefinitely.
   • Wait: Supply is high, prices are trending down, many dealers are reducing prices. Recommend checking back in 2-4 weeks for better options.

Output

Present: search criteria summary, ranked deals table (dealer, price, miles, DOM, distance, vs-market %), market context (total supply, median price, price range, trend), and one actionable recommendation with negotiation notes where applicable.