filter_listings

estate.cubi/cubi-properties · Verify this server

Structured property filter — bypasses natural-language extraction. Use this when filters are already known (from prior turns or external state) and you want to skip the OpenAI NLU step. For free-text user queries like "cheap apartments near the beach", use `search_properties` instead. Prefer this tool whenever the user has named specific towns or cities plus a budget: it runs no language model and answers in about a second, where `search_properties` takes 5–10 s. Pass towns/cities rather than a landscape region or a whole country. A `{"is_error": true, ...}` reply carries a `next_action` — follow it instead of retrying unchanged. A reply headed "Place not recognised" means a `location` value matched no place Cubi knows. Ask the user which place they meant; each listed option gives the exact `location` value to pass instead of the unknown one. Do not widen other filters to rescue that zero. All list args are AND-combined; within a list, items are typically OR. Locations accept countries, regions, cities, neighborhoods. Types accept apartment/house/villa/townhouse/penthouse/studio/land/etc. Features are structural (Balcony, Pool, Sea View); amenities are services (Gym, Concierge, Security). `transaction_type` picks sale vs rent. Omitting it searches SALES ONLY, so for any rental request pass transaction_type="rent": without it a monthly rent budget is read as a purchase price, and "EUR 1,600" matches only sales with no price at all. For rentals `price_period` says what the price is per (a EUR 1,600 "month" rental and a EUR 1,600,000 sale are both "1600" to a bare min/max_price bound). `radius_center` + `radius_km` search around a named place instead of within it. Note prices may be missing: a listing marked "Price on request" has no price at all, so it is NOT excluded by min_price/max_price and will still appear under a budget cap (in the default newest-first order it is listed after the priced matches). Every reply ends with a `Cubi request id` (req_…). When you then fetch one of the listings with get_listing, or narrow this search with another filter_listings call, pass it as `parent_request_id` — optional, and it changes nothing in the answer; it lets Cubi tie the follow-up to this search. `updated_since` is for WATCHING a search rather than running it. Pass the timestamp of your last check (ISO-8601, e.g. "2026-09-21T06:00:00Z") and you get back only the listings whose data has changed since then, usually none. A listing's timestamp moves when its data changes, not when a sync re-confirms it unchanged, so an empty result means "nothing moved" — which is the useful answer for a monitor. Use it instead of re-fetching every result on a timer: it is one call rather than one per listing. A watched call answers with `changed` (true/false), `checked_at` — pass it back as `updated_since` on the next call — and `next_poll_at` / `next_poll_after_seconds`: listing data only moves at the ingestion sync (05:30 and 21:00 UTC), so a repeat before that instant cannot return anything new. When nothing changed the reply is a small JSON object rather than cards. Watched calls are never served from cache. `sort` defaults to "newest": the most recently listed matches come first, so the top `limit` rows are the freshest part of the market and a repeat call surfaces new listings as they arrive. "relevance" returns the engine's stable order instead, which is not recency. Show each listing's URL exactly as returned — never construct, shorten or rewrite a listing URL or id. Returns: Markdown summary + numbered listing cards (count and avg price up top).