First Car Scout

Re-runs the search after the family states a pairwise tradeoff (e.g. 'brand matters more than safety'). Pass the search_token from the previous search_first_cars or refine_shortlist result — it carries the family's details forward, so you do not need to restate them — plus which of two dimensions matters more. If you no longer have the token, pass the original search details directly instead (including licence_type/months_licensed); either way works. Only call this after search_first_cars, and only when the family has actually said they want to refine.

refine_shortlist

Emails the family their shortlist and saves it so they can return to it later. Offer this once, after showing a shortlist (e.g. 'Want me to email you this list?') — do not repeat the offer if they decline or ignore it. Only call this once the family has said yes AND given an email address; never call it on an assumption or before they've agreed. IMPORTANT: pass the search_token from the most recent search_first_cars or refine_shortlist result alongside the email address — it carries the family's details, and if they refined the list, it is what makes the emailed report match the list they actually agreed to be sent. If you no longer have the token, repeat the SAME driver_age, postcode_or_town, budget_max, licence_type and months_licensed from the earlier search instead. This tool regenerates the actual shortlist to build the emailed report, so inaccurate or missing licence details here produce a real report with the wrong insurance figures, not just a save failure. This tool sends the email itself, server-side, from First Car Scout's own address; it does not use or need the user's own email account. If the email cannot be sent through this tool for any reason, tell the family plainly.

save_shortlist

Finds and ranks real UK cars for a new or young driver, using First Car Scout's deterministic recommendation engine over a live, curated catalogue. Returns a ranked shortlist with monthly running costs, safety and reliability, and why each car was picked. Call this first, before refine_shortlist. REQUIRES asking the family first whether the driver has a manual or automatic licence (or hasn't passed) and, if passed, roughly how long ago — this tool refuses with a follow-up question if you skip it, since it materially changes the insurance estimate on every car shown. If refused, that means go ask the family in your next message — do NOT retry with a guessed value; a fabricated licence_type is worse than no shortlist at all.

search_first_cars

Corrects the licence type (and, unless not-passed-yet, how long since passing) for an existing search and re-prices the same cars — insurance is the largest cost this changes. Pass the search_token from the most recent search_first_cars, refine_shortlist, or update_licence_details result plus the corrected licence_type (and months_licensed unless not_passed_yet). If you no longer have the token, pass the original driver_age/postcode_or_town/budget_max alongside the correction instead. Call this when the family states a real correction in conversation ('actually she passed last year') — never to satisfy search_first_cars's own licence gate with a guess; that gate exists specifically to stop a fabricated value, and this tool does not bypass it.

update_licence_details