Cars.co.za

Use this when the user should be sent to browse a search on cars.co.za themselves — after search_vehicles, when they want the full result set rather than six listings, or when they ask for a link. It only builds the URL; call search_vehicles when they want to see actual cars. The URL is returned in `payload` — always use this rather than assembling a cars.co.za URL yourself, as hand-built paths 404.

build_search_url

Use this when the question is about whether a car is any good, rather than what is for sale: reliability, common problems, running costs, what it is like to live with, which of several to buy, best-of and recommendation questions, and South African road tests and news. It equally covers buying advice with no particular car in mind — what to check when buying used, guidance for a first-time buyer, what a private sale needs, which cars hold their value, Car of the Year and other awards. `keywordPhrase` is a topic as readily as a vehicle: 'first car', 'what to check when buying a used bakkie', 'Car of the Year' all work, so a question with no make or model in it is still one for this tool. Search it BEFORE answering such a question from memory — this is Cars.co.za's own editorial, written for South African roads, fuel and pricing. Ground your answer in the articles returned in `payload` and cite their URLs; call get_article for the body text when detail matters. For comparisons make ONE call with a combined phrase (e.g. 'BMW X1 X3 X5 comparison') — never one call per vehicle.

find_articles

Use this for a factual figure about a current model: what it costs new, power, torque, fuel consumption, boot space, seats, 0-100, towing, engine, transmission — for South African specification, in rand and litres per 100km. Never answer such a figure from memory. For a comparison, pass every model in `models` in ONE call, which grounds all sides at once. Use find_articles instead for whether a car is good, reliable or comfortable, and search_vehicles for what is actually for sale and at what price today.

get_model_specs

Use this when the user asks about one particular listing they have already been shown — 'what engine does the second one have', 'does that one have leather', 'who's selling it'. Takes the `id` of a listing returned by search_vehicles, and describes that exact car rather than the model in general. Returns an error in place of the sheet if that listing carries none, keep the available listing facts; model catalogue data cannot verify this exact car; `dealer` is still there either way.

get_vehicle_specs

Use this when an article from find_articles looks like it answers the question but the headline is not enough — a verdict, a specific criticism, what a road test concluded. Takes an `id` from find_articles. Read it before summarising what a review said, rather than inferring from the title.

get_article

Use this when someone wants to find, browse, price or shortlist a car for sale in South Africa — new or used, from Cars.co.za's live listings. It covers cars for sale, used cars, new cars, dealer stock, bakkies, family SUVs, first cars, cheap cars under a budget, and searches by make, model, price, province or town, year, mileage, fuel type or transmission. Use it for 'what's available', 'how much are they', 'the cheapest', 'the newest', 'near me'. EVERY parameter is optional, and no make or model is needed: 'brand new only', 'under R150 000', 'something with low mileage', 'an MPV for a big family', 'a demo model', 'whatever is for sale near me' are each a complete search on their own. Call it with whatever the user gave, even if that is almost nothing — answering a browsing question from memory is always wrong, because only this tool knows what is actually for sale today. A place on its own is a complete search too — 'near me', 'in Boksburg', 'dealers in Pretoria' — so search and then say which area you covered; only pass `latitude`/`longitude` if the host actually handed you coordinates. Cars, bakkies, SUVs and vans only: this is not the tool for motorbikes, trucks, caravans, trailers, boats or parts, and it lists only South African stock. Do not use it for how a car is to own or drive (find_articles), or for specifications and figures (get_model_specs). Matching listings are returned in `payload`, each with a title, price, mileage, location and listing URL. Present them from there — never invent a listing, price or URL. Set `sortBy` whenever the user implies an order (cheapest, lowest mileage, newest, nearest): it sorts across every match, so 'the cheapest' really is the cheapest of `total` rather than of the six returned. With no `sortBy` the results come back in the order cars.co.za itself shows them, which favours dealers' promoted listings — so describe them as current listings, never as the best or most suitable. There is no ranking by quality or value here; if someone asks which car is best, use find_articles for the editorial verdict, or sort by something you can defend such as price or mileage. When a question needs a verdict before a shortlist ('the best Polo', 'which should I buy'), get the verdict FIRST and search afterwards — a search sent in the same breath cannot carry criteria you have not worked out yet, and a shortlist that contradicts the advice printed above it is worse than no shortlist. Once you have named a spec, search for THAT spec: a recommendation of 'a 2024 Polo Life DSG under 30 000 km' means yearMin 2024, transmission Automatic, mileageMax 30000, not make and model on their own.

search_vehicles