Apartments.com

Retrieve media specific to an individual apartment unit: interior photos, unit-specific floor plan, and virtual tour for that exact unit. WHEN TO CALL: (1) user asks to see photos or tours for a specific unit they are considering; (2) `hasUnitLevelMedia` is true in a media.listing response and user is focused on a specific unit. INPUT: `unitKey` from a unit-level rental in listing.details (rentals[].unitKey). Set `preferredTab` based on the user's intent: "Photos", "Videos", "Virtual Tours" (also for 3D tours / Matterport), or "Floor Plans". The response `selectedTab` field tells the MediaCard which tab to pre-select — pass it directly to the component. Do NOT call if unitKey is absent on a rental — not all rentals are unit-level. AFTER RESPONSE: render the MediaCard component using `selectedTab` as the active tab.

media.unit

Get neighborhood context for a geographic area — walk score, city demographics, rent trends, and top schools. Requires matchType and encrypted matchId from prior search or listing detail results. For non-City geographies, provide cityId for demographics. Returns structuredContent for conversational presentation.

local.guide

Resolves a user's selection from a typeahead disambiguation list to a listingKey. Call this after typeahead returns multiple results and the user has picked a property. Pass the disambiguationId from the typeahead result and the user's selection (e.g. "1", "2", "the Irvine one", "Volar Irvine"). AFTER THIS TOOL RETURNS: call listing.details immediately with the returned listingKey. Do NOT call residentialForRent, search.listings, or any other tool.

typeahead.resolve

GPS-based apartment search. Call this tool — with no arguments — whenever the user wants rentals near their current location and has NOT named a specific city, ZIP, or address. Trigger phrases (call immediately, no questions asked): "search nearby", "search near me", "apartments near me", "rentals near me", "nearby apartments", "nearby rentals", "near by rentals", "close by rentals", "rentals around here", "local apartments", "apartments in my area". Also triggers when filters are combined with proximity: "nearby under $2000", "2-bed near me". This tool takes NO arguments. The app retrieves GPS automatically and calls search.listings. After calling this tool, reply only: "Getting your location now…" and wait. When the updateModelContext message with GPS coordinates arrives, call search.listings immediately. If the user specified filters, include them. If no filters were specified, call search.listings with ONLY the GPS coordinates — do NOT ask the user for filters.

search.near_me

Search for rental property listings (apartments, houses, condos, townhouses) by location, price, bedrooms, amenities, and other criteria. Returns a paginated list of matching listings with pricing, photos, and coordinates for map display. LOCATION PRECONDITION: This tool REQUIRES a concrete location named by the user — a city, neighborhood, postal code, street address, or named landmark/area. When the user uses proximity words like "near", "nearby", "near by", "here", "around", "close", "local" without naming a specific place — even when combined with filters like price, beds, or amenities (e.g. "nearby rentals under $2000", "near me 2 bed") — call search.near_me instead of this tool. When the user mentions price/beds/amenities but no place and no proximity word (e.g., "find apartments under $3000"), ask: "Which city, neighborhood, or ZIP code should I search?" and wait. When the user names a place alongside a self-relative phrase (e.g., "near me in Atlanta", "apartments near the airport in Boston"), use the NAMED place directly and call as normal. PAGE SIZE RULES: Always use pageSize=50 (and pageNumber=1 for the first page). Applied uniformly across all UI modes so the result ordering is identical whether the user is in list, inline-map, or fullscreen-map view. Increment pageNumber to retrieve subsequent pages of 50. RESPONSE RULES: (1) For pageNumber=1, the opener, bullet count, and CTA BRANCH on listings.length. The "narrow down with more filters" option appears ONLY when listings.length >= 10 — below that, results are too few to narrow further; offer "adjust your search" instead: • 1 result → render 1 bullet. Opener: "<Property Name> matched your search criteria of <filters>." CTA: "Want details on it, or adjust your search?" No "see more", no "narrow". • 2 results → render both bullets. Opener: "<Property A> and <Property B> matched your search criteria of <filters>." CTA: "Want details on one, to compare them, or adjust your search?" No "see more", no "narrow". • 3 results → render all 3 bullets. Opener: "There are various places with <filters> — here are the top 3." CTA: "Want details on one, to compare a few, or adjust your search?" No "see more" (the top 3 ARE all results), no "narrow". • 4–9 results → render the top 3 bullets. Opener: "There are various places with <filters> — here are the top 3." CTA: "Want to see more rentals, get details on one, compare a few, or adjust your search?" No "narrow". After the user asks for "more", render the remaining bullets (4–listings.length) in a single chunk, then close with: "Want details on one, to compare a few, or adjust your search?" • 10+ results → render the top 3 bullets. Opener: "There are various places with <filters> — here are the top 3." CTA: "Want to see more rentals, get details on one, compare a few, or narrow down with more filters?" In all five cases, wait for the user before doing anything else. (2) PAGINATION WITHIN THE CURRENT RESULT — no new tool call (applies ONLY when listings.length >= 4 on page 1, or on any page>=2): on every 'see more rentals' reply, render the NEXT CHUNK of up to 10 bullets from the SAME result object already in context. Track how many bullets you have shown so far for this page (call it N). The next 'more' response renders bullets at 1-based indices (N+1)..min(N+10, listings.length). Page-1 chunk sequence (listings.length >= 10): top 3 → 4–13 → 14–23 → 24–33 → 34–43 → 44–50 (or fewer if listings.length < 50). For 4–9 results, there is just one follow-up chunk: 4–listings.length. DO NOT call search.listings while any listing in the current result is still unshown — they are already in the structuredContent of the previous tool result that is still in context. End each chunk response with: "Want details on one, to compare a few, see more rentals, or narrow down with more filters?" — but DROP "narrow down with more filters" (replace with "adjust your search") when listings.length < 10, and DROP "see more rentals" once every bullet on the current page has been rendered. Wait after each response. (2a) For pageNumber>=2, the FIRST response shows the top 10 (no summary-opener sentence — that was on page 1); subsequent 'more' replies follow the same chunk-of-10 pattern from rule (2): 11–20 → 21–30 → 31–40 → 41–50 (or fewer if listings.length < 50). DO NOT call search.listings until N === listings.length. End each response with exactly: "Want details on one, to compare a few, see more rentals, or narrow down with more filters?" and wait. (2b) Branch on the user's follow-up answer: (i) "see more rentals" / "more" / "show more" / "yes" / "sure" → render the NEXT CHUNK of up to 10 bullets from the result already in context, per the chunk sequence in rule (2) (page 1: 3 → 13 → 23 → 33 → 43 → 50) or rule (2a) (page 2+: 10 → 20 → 30 → 40 → 50). This is a CHAT-ONLY response with NO tool call. Only when you have already rendered every listing in the current result as a bullet (N === listings.length) does the NEXT "more" reply trigger search.listings again with pageNumber incremented by 1. Never call search.listings just to fetch listings that are already in the previous result. (ii) "details" / a specific property name → wait for the user to name a property if not yet specified, then call listing.details with that listingKey. (iii) "compare" → wait for the user to name 2–3 properties, then briefly contrast their key attributes (price, beds/baths, amenities the user cares about, location) in a single side-by-side response using the data already in the current result; do NOT call any tool. (iv) "ratings" / "reviews" / "stars" / "how are they rated" / "show me ratings and reviews" / similar → answer from the `reviewRating` field already in the current search result for the requested listings; do NOT call listing.details (the search result is the source of truth for ratings). ALWAYS present each requested listing's `listingDetailPageUrl` as a markdown link on its name — whether or not the property has a rating. The `listingDetailPageUrl` points to the property's full Apartments.com listing page; the page itself contains the reviews section (which lazy-loads as the user scrolls down), so do NOT describe the link as going "to the reviews" — describe it as the listing page. Branch on how many properties the user is asking about: • SINGLE property (the user named one specific property, e.g. "show me reviews of Colonnade at The Market Place") → do NOT render a table. Reply with one short prose sentence: state the rating if `reviewRating` is present (e.g. "Colonnade at The Market Place is rated 5/5 by renters."), or note no reviews yet if it is missing (e.g. "Enzo doesn't have any renter reviews yet."). Follow that with one short statement-form sentence presenting the listing name as a markdown link to `listingDetailPageUrl` — e.g. "Tap [Colonnade at The Market Place](url) to view its Apartments.com listing page." If unrated, you may append a brief CTA hint, e.g. "Tap [Enzo](url) to view its Apartments.com listing page — you can be the first to leave a review there." • MULTIPLE properties (the user asked about two or more, or asked broadly across the current result set) → render a clean two-column table: Apartment, Rating. Render every apartment name as a markdown link to that listing's `listingDetailPageUrl` regardless of whether it has a rating. Do NOT add a Reviews, Notes, Commentary, or Analysis column, and do NOT editorialize on which listing has the "strongest" or "best" rating. If `reviewRating` is missing for a row, write "Not rated" in the Rating cell — but still link the name. After the table, add exactly one short sentence acknowledging the link goes to the Apartments.com listing page (statement, not offer — e.g. "Tap a property name to view its Apartments.com listing page."). Individual written reviews are NOT in the search response — only the aggregate `reviewRating`. Then end with a conversational follow-up question. Do NOT offer to open, fetch, summarize, or pull up the reviews on the user's behalf — the link IS the action; let the user click it themselves. (v) "narrow" / "more filters" / ANY mention of changing the search criteria → call search.listings AGAIN with the updated criteria. Triggers include (non-exhaustive): a new bedroom or bathroom count, a different price range, a new must-have amenity (gym, pool, parking, etc.), a different neighborhood/city, a pet-policy change, "show only ones with X", "actually I need…", "what about under $X", "any with a Y", etc. Merge the user's new criteria onto the existing listingFilters and re-call this tool — do NOT try to filter the existing in-context result client-side. If the user said "narrow" without specifying what to narrow on, ask 1–2 short clarifying questions first (e.g. "Any must-have amenities?", "Closer to a specific neighborhood?", "Tighter budget?"), then call. (vi) "amenities" / "features" / "what amenities" / "does it have a [gym/pool/etc]" / "what's included" / similar follow-up about what a SPECIFIC property offers → answer from the `amenities` array already in the current search result for that listing; do NOT call listing.details. The `amenities` array is a flat, curated subset of enum values — the Apartments.com listing page has the full, categorized list (Unique Features / Community / Apartment) which may include items not in our enum. To make that source of truth reachable, render the property name as a markdown link to its `listingDetailPageUrl` (use the URL as-is, no anchor) on first mention — for example: "[Enzo](url) amenities include: …". Do NOT add a trailing "tap the link" sentence — the link is a quiet affordance, not the answer. End with a conversational follow-up question. (3) Format each bullet: bold property name — price (or price range) — any UNIQUE highlight specific to that listing (e.g., "rent special: 1 month free", "5-star rating", "newly built", "$0 deposit") — full address (street, city, state, ZIP). Put the address LAST so the unique highlight (the differentiator) is visually prominent before the longer geographic anchor. If there is no unique highlight, drop that segment entirely (name — price — address). Do NOT repeat per-listing the shared filter attributes (bedroom/bath count, pet policy, requested amenities, search-area city) that already appear in the summary opener — those are noise when repeated on every bullet. The address IS allowed (and expected) per-listing because each property's street address is unique. Keep each bullet short. Never expose null fields as implementation details. (3a) Consolidate the user's filter criteria (petFriendly, bedrooms/baths range, price range, requested amenities, propertyType, hasBookableTour, hasSpecialOffer, location) INTO the summary opener (rule 3b) — NOT into the bullets. The opener should describe what every result has in common; bullets show only what differs (name + price + unique offer/highlight). Skip filters the user did not ask about. If the user named no filters, fall back to the search location (e.g. "in <city>"). (3b) On pageNumber=1, the opener depends on listings.length: • 1 result: "<Property Name> matched your search criteria of <filters>." e.g. "The Atlantic Buckhead matched your search criteria of pet-friendly 2-bed rentals in Atlanta under $2,000." • 2 results: "<Property A> and <Property B> matched your search criteria of <filters>." e.g. "The Atlantic Buckhead and MA Gardens matched your search criteria of rentals with a gym in Brooklyn." • 3+ results: "There are various places with <filters> — here are the top 3." e.g. "There are various places with pet-friendly 2-bed rentals in Atlanta under $2,000 — here are the top 3." DO NOT mention totalResults or any specific number to the user — use "various places" regardless of the actual count when there are 3+. Always refer to the results as "rentals" (never "matches" or "listings") inside <filters>. (4) If totalResults is 0, tell the user naturally and suggest broadening filters. (5) Do not call listing.details automatically — wait for the user to select a property. (6) Never call this tool during an active lead or tour flow — use the listingKey already in context. (7) Set viewMode='map' WHENEVER the user's message mentions a map in ANY form — not just the exact phrase "show me on map". Trigger on any of: "map", "on the map", "on a map", "map view", "see on map", "show on map", "plot on map", "pin", "markers", "where are they", "where is this on the map", "nearby on map", and similar phrasings. Omit viewMode (or set to 'list') only when the user makes no map reference at all. viewMode controls the UI rendering only — pageSize is always 50 regardless of viewMode.

search.listings

Resolves a search term to a property or location. Call this in two scenarios: 1. User mentions a specific property/apartment name → typeahead identifies the property → leads to residentialForRent → listing.details (full property detail) 2. User searches by neighborhood, POI, zip code, or address (anything that is NOT a plain city name) → typeahead resolves it, then routes based on MatchType: - Property address → if resolved to a property (MatchType 1, 4, 13, or 20) → residentialForRent → listing.details - Neighborhood / POI / zip / street → resolves to city+state → search.listings IMPORTANT: If the user mentions a specific property name (e.g. "Enzo", "Avalon", "Camden"), always call this tool — even if they also mention a city like "in Irvine". The city is location context for the property search, not the search target itself. Only use search.listings directly when the user searches by city name ALONE with no specific property name. Examples that MUST call this tool: - find me Enzo apartment in Irvine (property name → leads to listing.details) - show me Avalon apartments near Austin (property name → leads to listing.details) - 123 Main St, Irvine CA (property address → MatchType 1/4/13/20 → residentialForRent → listing.details) - apartments in Turtle Rock (neighborhood → resolves to city+state → search.listings) - near Irvine Spectrum (POI → resolves to city+state → search.listings) - apartments near 92612 (zip code → resolves to city+state → search.listings) - near UCI (POI → resolves to city+state → search.listings) Examples that should NOT call this tool (use search.listings instead): - apartments in Irvine (city name only — no specific property name) - 2BR in Newport Beach (city name only — no specific property name) When calling this tool: - Set keyword to the property name, neighborhood, POI, zip code, or address only. Do NOT include words like "apartment", "near", "in" in keyword. Examples: "Enzo apartment in Irvine" → keyword: "Enzo"; "near UCI" → keyword: "UCI" - Include stateCode when you can infer it, in this order: 1. Explicitly stated in the current prompt ("in Irvine" → "CA", "in Austin" → "TX") 2. User's current location — if the host provides the user's location, use that state 3. Prior conversation context — state from the most recent search or location mentioned 4. No state context available → omit stateCode and call the tool anyway. If multiple properties are returned across states, the user will pick from the disambiguation list. - Include centerPoint when you have coordinates from a prior search result. After receiving the result, route based on count and MatchType: - If count=0 (no results found): If the user's original prompt contains a city name: call search.listings with { location: { city, administrativeArea1, countryCode: "US" } } extracted from the prompt, plus all user-specified filters (bedrooms, price range, amenities — do NOT drop them). If no city is available in the prompt: tell the user no results were found for their search term and ask them to refine it (check spelling, try a different name, or search by city instead). - If MatchType is a Property type (1, 4, 13, or 20): If count=1: call residentialForRent immediately with the returned matchKey. If count>1: the result has status="awaiting_selection" and a disambiguationId. Present the numbered displayOptions list to the user and wait. Do NOT call residentialForRent or any other tool — there is no matchKey. After the user picks, call typeahead.resolve with the disambiguationId and the user's selection. That returns the matchKey and MatchType. Then call residentialForRent with those values. - If MatchType is any other value (neighborhood, POI, zip code, etc.): typeahead has resolved the search term to a city+state — now call search.listings: If city and state are present: call search.listings with { location: { city, administrativeArea1, countryCode: "US" } } AND all user-specified filters from the original prompt (bedrooms, price range, amenities — do NOT drop them) If city or state is missing: ask the user which city they want to search in, then call search.listings with the user's answer AND all user-specified filters from the original prompt

typeahead