apartment-hunter: Skill for Codex

Apartment Search Skill

Overview

You have access to the Apartment Hunter MCP server which provides tools for searching, analyzing, and monitoring rental apartments in Kazakhstan. The primary data source is krisha.kz, but the library is designed for additional sources too.

When to use

Use this skill when the user:

• wants apartments found by natural-language preferences;
• asks what changed since the latest ingestion run;
• describes listing jargon in plain language;
• needs help turning fuzzy preferences into profile filters;
• asks whether a listing phrase is good, bad, neutral, or ambiguous.

Workflow

1. Setting Up Search Profiles

Before searching, the user should create a search profile that defines their criteria:

Use create_search_profile with parameters like:
- sources: ["krisha.kz"] unless the user requests another enabled source
- city: "Алматы" or "Астана"
- districts: ["Бостандыкский"] if the user clearly names districts
- rooms: [1, 2] for 1-2 room apartments
- price_min / price_max: in KZT (tenge)
- area_min / area_max: in m²
- owner_only: true to exclude agencies
- min_score: minimum LLM quality score (0-10)
- polygons: list of polygons, where each polygon is a list of [lat, lon] points.
### CRITICAL RULE FOR KRISHA.KZ: Always Use Polygons for Location-Based Search
Text search on krisha.kz for specific streets or landmarks is highly inaccurate and returns false positives from other districts.
When a user asks for a specific street (e.g. "Makataeva") or landmark (e.g. "Megapark"):
1. First, find the coordinates using a web search or maps tool.
2. Draw a closed polygon around the target area. A polygon is a list of `[lat, lon]` points forming a closed loop (first point must equal last point, or the system closes it automatically).
3. Pass `polygons` to `create_search_profile`. The polygon is sent directly to krisha.kz as a server-side geographic filter (`areas=p...`), so only listings physically located inside the polygon are returned.
   - Do NOT rely on `keywords` for geographic filtering — krisha.kz text search returns false positives from apartments that merely mention the street/landmark in their description ("10 minutes from Megapark", etc.).
   - `keywords` are only appropriate when the user explicitly wants to filter by text in the listing description (e.g., specific amenities or building name).