Trade Me Property

This tool provides the Trade Me location hierarchy for use in property for sale searches. When you call it, you will receive the three-tier location taxonomy from Trade Me, enabling you to discover valid location IDs for use in searching for properties for sale using the search_residential_properties tool. The location hierarchy is: - Region (top level) → District (middle) → Suburb (most granular) Each location includes: • A Unique numeric ID (for use in the search_residential_properties tool, these numeric ID's are never shown to users) • A Human-readable location name • It's child locations (regions contain districts, districts contain suburbs) • Any adjacent suburbs (for suburb-level locations) Use this tool when you need to: • Find district or suburb IDs for use in searches for properties for sale (NOT regions - region IDs are already provided in search_residential_properties tool parameters) • Resolve ambiguous location names (e.g., "Te Atatū" has Peninsula and South suburbs) • Discover all districts within a region • Find all suburbs within a district • Explore nearby/adjacent suburbs • Support cross-region searches using multiple suburb IDs **DO NOT** use this tool when: • Looking up region IDs - these are already documented in the region_id parameter description • The user is speaking at region level only (region IDs are pre-provided) • A simple clarifying question can resolve the user's intent without needing IDs • The user has not yet chosen a specific area • To search for rental properties - this is important! USER-FACING LANGUAGE (**IMPORTANT**): • **NEVER** expose technical terms like "suburb_id", "district_id", "region_id" when asking users for clarification • **ALWAYS** Use natural language: "Which area did you mean: Te Atatū Peninsula or Te Atatū South?" • **NOT**: "I need the suburb_id for Te Atatū. Here are the options..." • **DO NOT** show raw taxonomy or long lists unless the user asks for them • When listing options, provide short, summarised sets and offer to expand • When a clarifying question is asked (e.g., for ambiguous names), present the options and immediately suggest the next action: "Which area did you mean: Te Atatū Peninsula or Te Atatū South? Selecting one will allow me to start your property search." CROSS-REGION AND CROSS-DISTRICT SEARCHES: When searches span multiple regions OR multiple districts, CALL THIS TOOL WITHOUT region_id: Call with region_id=None when: • Multiple regions: "properties in Auckland and Wellington" • Multiple districts across regions: "beach suburbs in North Island" • Exploratory/broad searches: "coastal towns", "near universities", "ski towns" • Any search needing suburb IDs from different districts or regions Why omit region_id: • Returns **COMPLETE** nationwide taxonomy (all regions → all districts → all suburbs) • Enables extraction of suburb IDs from anywhere in New Zealand • suburb_id parameter accepts lists spanning multiple districts AND regions Example workflow: User: "Beach properties across North Island" 1. Call get_property_location_taxonomy(region_id=None) ← Get everything 2. Search taxonomy for coastal suburbs in Auckland, Bay of Plenty, Gisborne regions 3. Extract suburb IDs from multiple regions: [268, 412, 589, 701, 823, ...] 4. Call search_residential_properties(suburb_id=[268, 412, 589, 701, 823, ...]) Single region vs cross-region: • Single region: CAN filter with region_id=1 (gets only Auckland districts/suburbs) • Cross-region/district: MUST use region_id=None (gets all locations nationwide) Handling unknown/misspelled locations: • Suggest possible matches or nearby well-known areas • If unclear, ask the user what area it is near before calling the tool Decision flow (when to call tool vs when to ask for clarification): 1. Region name (e.g., "Auckland") → **DO NOT** call tool (region IDs are pre-provided in search parameters) 2. Unambiguous district/suburb name → Call tool to get numeric ID (search requires IDs, not names) 3. Ambiguous name (e.g., "Te Atatū") → Call tool first, detect multiple matches, then ask user which one 4. Colloquial/landmark name → Ask for clarification → call tool to get ID 5. District where suburbs are needed → Call tool to list suburbs 6. "Nearby suburbs" → Call tool (adjacency information) 7. Multiple areas across regions → Call tool once to get all suburb IDs → combine into comma-separated string 8. Misspellings/unknown → Suggest matches → call tool to confirm KEY INSIGHT: The search tool requires numeric IDs, not location names. The *immediate and only purpose* of calling this tool is to efficiently and conversationally retrieve the IDs needed to perform the property search and then generate market insights for the user. **ALWAYS** focus on natural, friendly communication and avoid exposing internal identifiers.

This tool searches for properties for sale in New Zealand which are displayed on an interactive map with markers. When you call it, you will receive: • An interactive map widget with markers showing the location of the properties for sale, each with basic information (location, price, bedrooms, bathrooms, etc.) • An aggregated summary of the results (e.g., how listings are distributed by price range, bedrooms, bathrooms, property type, and location) Use the interactive map to help the user understand what properties are for sale in that area. **ALWAYS** use the summary statistics to immediately provide a one-sentence market insight with a suggested refinement after displaying the map. DO NOT use this tool to search for rental properties - this is important! Users will describe the kinds of properties they want in natural, conversational language. Your role is to understand their intent and translate it into an effective property search to show them on a map. Interpret location, property needs, and lifestyle requirements broadly and flexibly: • Understand all forms of location references—specific suburbs, broader areas, regions, informal names, and landmarks ("near Britomart", "North Shore area", "around Mt Albert"). If the location is unclear or ambiguous, ask a brief clarifying question and use the get_property_location_taxonomy tool to resolve it. • CROSS-REGION AND CROSS-DISTRICT SEARCHES: While region_id and district_id accept only single values, the suburb_id parameter accepts multiple comma-separated suburb IDs that can span across different regions and districts. This enables powerful cross-region searches: – "Beach properties across North Island" → Use taxonomy to find beach suburb IDs from Auckland, Bay of Plenty, Gisborne, etc. → Pass as suburb_id="268,412,589,..." – "Properties near universities nationwide" → Find suburbs near all major universities → Combine suburb IDs – "Coastal towns in New Zealand" → Identify coastal suburbs across all regions → Single search with multiple suburb IDs – Format: suburb_id="268,269,270" (comma-separated, no spaces) – This is the recommended approach for any search spanning multiple regions or districts • Use bedroom and bathroom counts when explicitly stated ("4 bedrooms"), and infer reasonable minimums when the user describes their situation more generally ("big enough for my family"). • Translate price expectations from natural language ("under $1m", "less than $700k", "between $850k and $1.2m") into sensible price ranges. • Identify property types when they are mentioned (house, apartment, townhouse, land). If the user does not specify a type, keep the search broad. • Capture features, qualities, and lifestyle preferences using keywords—e.g., pool, view, large backyard, renovated, double garage, entertaining space, motorway access, or proximity to transport—especially when the concept cannot be expressed through structured filters. • If a feature is captured by a filter (e.g. `num_bathrooms`), **DO NOT** use the same concept as a keyword unless the user adds a descriptive quality to it (e.g., "luxury bathroom" *would* be a keyword). • Treat school and zoning requirements as location intent. Use the suburbs commonly associated with the school and include the school name in keywords when helpful. Be transparent if zoning cannot be enforced precisely. • Users often give multiple requirements at once. Apply structured filters where possible and use keywords for anything not directly supported. When something cannot be expressed exactly (e.g., "short walk to transport"), approximate sensibly and communicate this briefly if needed. • Phrase clarifications naturally ("Do you mean the Ponsonby suburb or the wider central Auckland area?") and never expose internal parameters or IDs to the user. Every response MUST conclude with a single, relevant question or a clear call-to-action to encourage further refinement or exploration.