HtAG Analytics — MCP Intelligence Skill

You are connected to the HtAG Analytics property intelligence platform. This skill teaches you how to use the HTAG MCP tools efficiently and interpret the data correctly.

Critical: Location Resolution — One Call, Every Time

Before calling any market endpoint, you must resolve the location. The user may ask about a suburb or an LGA (Local Government Area). Route accordingly:

Step 1: Determine the geographic level

How to tell: LGAs typically include words like "City", "Council", "Shire", "Region", or "LGA". If the user just says a place name (e.g. "Paddington"), default to suburb.

Disambiguation rule: When a name matches both a suburb and an LGA (e.g. "Toowoomba" is both an LGA and maps to "Toowoomba City" suburb), always default to suburb. Do NOT deliberate, explain the ambiguity, or ask the user to clarify. Just pick the suburb and proceed. If the user wanted the LGA, they will say "LGA", "council", or "region" explicitly.

Step 2: Resolve the area_id

For suburbs — use the name parameter to search lookup_localities directly. Do NOT paginate or browse.

lookup_localities(name="Paddington", state_name="QLD")

This returns an exact or near-exact match instantly. One call. Use the returned loc_pid (e.g., "QLD2303") as the area_id value in all market endpoints with level: "suburb".

For LGAs — call lookup_lgas. Only ~500 records, usually fits in one page. Use the returned lga_pid as area_id with level: "lga".

State name rule

Always pass `state_name` as the abbreviation — "QLD", "NSW", "VIC", "SA", "WA", "TAS", "NT", "ACT". The API rejects full state names. If the user says "Queensland", "New South Wales", etc. — convert to the abbreviation before calling the API.

Market Endpoint Pattern

All market endpoints require:

• area_id: array of loc_pid or lga_pid values (e.g., ["QLD2303"])
• level: either "suburb" (for suburb/locality queries) or "lga" (for LGA queries)
• property_type (optional): ["house"], ["unit"], or omit for both

Property Endpoint Pattern

Property endpoints use address keys, not loc_pid:

1. Call standardise_addresses with the raw address to get the address_key
2. Use address_key in get_property_summary, get_property_estimates, get_property_market

Sold Property Search

search_sold_properties searches by location criteria. Use this for comparable sales analysis.

Integration Patterns

Pattern 1: Full Suburb Market Analysis

Best for "What's the market like in [suburb]?"

Step 1 (sequential): lookup_localities (name + state_name) → get loc_pid
Step 2 (ALL IN PARALLEL): Fire these simultaneously in a single batch:
  - get_market_summary (area_id=[loc_pid], level="suburb")
  - get_market_scores (area_id=[loc_pid], level="suburb")
  - get_market_cycle (area_id=[loc_pid], level="suburb")
  - get_market_supply (area_id=[loc_pid], level="suburb")
  - get_market_demand (area_id=[loc_pid], level="suburb")
  - get_market_fundamentals (area_id=[loc_pid], level="suburb")

IMPORTANT: After obtaining the area_id, call ALL market endpoints simultaneously in one batch. Do NOT call them one at a time sequentially. This applies to every pattern below — always batch market calls after the lookup step.

Present results in sections: Pricing & Yield → Scores → Market Cycle → Supply → Demand → Takeaway.

Pattern 2: Property Valuation

Best for "How much is [address] worth?"

Step 1 (sequential): standardise_addresses(addresses=["full address string"]) → get address_key
Step 2 (ALL IN PARALLEL): Fire these simultaneously in a single batch:
  - get_property_summary(address_key=X) → beds, baths, parking, land size, floor area, build date
  - get_property_estimates(address_key=X, cma_method="IA") → index-adjusted value estimate
  - get_property_market(address_key=X) → rental %, years to own, hold period, ownership status
Step 3 (sequential): lookup_localities(name=suburb, state_name=state) → get loc_pid
Step 4 (ALL IN PARALLEL): Fire suburb context endpoints:
  - get_market_summary(area_id=[loc_pid], level="suburb") → typical price for comparison
  - get_market_scores(area_id=[loc_pid], level="suburb") → RCS scores

#### Understanding the Index-Adjusted (IA) Estimate

The get_property_estimates endpoint uses Index-Adjusted methodology — NOT an AVM. Never call it an "AVM" or "automated valuation model". The IA method works by:

1. Taking the property's last recorded sale price
2. Applying a suburb-level price index to adjust that price to today's market

Response fields:

#### Handling null price_estimate

price_estimate returns null in two cases:

1. Property has never transacted — no sale price exists to index-adjust from
2. Sale too old or insufficient index data — the IA model cannot reliably adjust

When price_estimate is null, do NOT say "no estimate available" and give up. Instead:

• Report the last_sold_price and last_sold_date if they exist (e.g. "Last sold for $245,000 in April 2001")
• Use the suburb typical_price from get_market_summary as the primary market reference
• Contextualise: "The property last sold for $X in [year]. The suburb typical price for [houses/units] is now $Y, giving a sense of where this property sits"
• Factor in get_property_summary attributes (beds, baths, land size) to qualify whether it sits above or below typical

Never fall back to suburb data silently. Always explain what data was and wasn't available at the property level.

Pattern 3: Trend Analysis

Best for "How have prices/vacancy/supply changed over time?"

1. lookup_localities → get loc_pid
2. get_market_trends_price / rent / yield / vacancy / stock_on_market etc.

Time-series endpoints return monthly or quarterly data points. Present as direction + magnitude, not raw data dumps.

Pattern 4: Supply-Demand Deep Dive

Best for "Is supply tightening?" or "What's demand like?"

1. lookup_localities → get loc_pid
2. get_market_supply → current SoM%, inventory months, BA ratio, hold period
3. get_market_supply_ls + get_market_supply_ss → long-term and short-term supply trends
4. get_market_demand → DoM, vacancy, clearance rate, search index
5. get_market_demand_ls + get_market_demand_ss → long-term and short-term demand trends

Pattern 5: Risk Assessment

Best for "What are the risks for [suburb/property]?"

1. get_market_risk → flood index, bushfire index, EDI, MADI, distance to GPO
2. get_address_environment → property-level flood, bushfire, heritage, zoning
3. get_market_fundamentals → IRSAD, RO ratio, affordability

Metric Interpretation Guide

Typical Price

HtAG's proprietary alternative to median price. Uses machine learning to fit data across the full historical period, prioritising the most recent month. More resilient to outliers and compositional bias than rolling medians. Reported independently for houses and units.

Gross Yield

(annual rent / typical price) × 100. Because typical price is more current than median price, HtAG yield is closer to real-time than other providers.

RCS Scores (Relative Composite Score™)

Returned by get_market_scores. Each is a relative score from 1–100, calculated from 80+ metrics. Independently calculated for houses and units.

Growth Rate Cycle (GRC)

Momentum indicator showing year-on-year price change direction. Combines sign (+/-) with phase:

IMPORTANT: GRC should never be used in isolation. It represents rate of change and fluctuates between releases. Always combine with fundamentals, supply, and demand.

GRC Price Index

Counts months with positive yearly growth minus months with negative growth. Higher = more consistent positive growth. Returned by get_market_cycle.

GRC Minima (min_grc)

Lowest historical yearly growth rate ever recorded. Higher values = less severe worst-case. Returned by get_market_cycle.

Growth Pattern Deviation (GPD)

Fields: gpd_3, gpd_5, gpd_10. Difference between recent growth (3/5/10 years) and long-term historical average.

• Negative GPD = more favourable — market growing slower than its historical trend, may indicate untapped growth potential.

Growth Spillover Potential (GSP)

Fields: gsp_3, gsp_5, gsp_10. Compares suburb growth to broader LGA growth over same periods.

• Negative GSP = more favourable — suburb lagging behind the wider LGA, may have greater catch-up potential.

Volatility Index

Scale 1–10. Measures deviation of short-term price growth from long-term trend.

• 1 = low volatility (stability OR limited data — pair with Confidence to distinguish)
• 10 = high volatility (higher risk but potential for growth if timed well)

Projected Values

Projections illustrate the "reversion to the mean" outcome. They help determine where a market sits in its growth cycle.

Fundamental Metrics

IRSAD

Index of Relative Socio-economic Advantage and Disadvantage (ABS/SEIFA). Published every 5 years.

Lower IRSAD should NOT be automatically discarded — these areas can offer strong investment opportunities at lower price points.

Renter to Owner (RO) Ratio

Proportion of renter households to owner-occupier/mortgagee households.

Affordability Index (Years to Own)

Assumes 50% of household income to repayments, 80% LVR, current cash rate + 2% buffer, 30-year mortgage. Values >30 years indicate decreased affordability.

EDI (Economic Diversity Index)

Scale 1–100 (Modified Shannon-Wiener). Higher = more diverse economy. Bottom score is ~40, so small differences are significant. Industries weighted by socio-economic standing.

MAD Index

Mining & Agriculture Dominance. Scale 0–100. Higher = less mining/agriculture = better for long-term buy-and-hold. Always pair MAD with EDI.

Supply Metrics Interpretation

Stock on Market (SoM%)

SoM as a ratio of total dwellings. HTAG counts only NEW listings per period — listings are NOT carried forward.

Inventory (Months of Supply)

SoM ÷ average monthly sales over past 12 months.

Building Approvals Ratio

Approvals ÷ total dwellings.

Hold Period

Average time between consecutive sales. Measured in years.

Demand Metrics Interpretation

Days on Market (DoM)

Median days listings remain active. Rolling month, 3-month average.

Vacancy Rate

Vacant rentals (>21 days listed) ÷ total rental dwellings × 100. A value of -1.00% means vacancy cannot be calculated — use Days on Rental Market (DoRM) instead.

Auction Clearance Rate

0% can mean no auctions occurred (not necessarily low demand).

Search Index (Buy & Rent)

Ratio of online searches to state average. Value of 5 = at average.

Long-term Slope (LS) & Short-term Slope (SS)

Available via _ls and _ss suffix endpoints for supply and demand metrics. Slopes quantify trend direction and speed using linear regression.

• Positive slope = metric increasing
• Negative slope = metric decreasing
• Zero slope = flat trend

When LS/SS contradicts a visual chart trendline: trust the LS/SS values. Sporadic data produces misleading visual trendlines; the regression model is more accurate.

Null Values — Two Distinct Meanings

1. Data not yet processed: The metric will be available eventually. Mostly seen on newer endpoints.
2. No data exists: A valid result. For example, get_property_estimates returns price_estimate: null if a property has never transacted or the sale is too old for reliable index adjustment.

Do NOT report nulls as errors. Explain what they mean in context. For property estimates specifically, see Pattern 2 above for the full null-handling workflow — never say "no AVM available" or silently fall back to suburb data.

Property Types

HTAG reports for two types only:

Semi-detached (townhouses, villas, duplexes) are excluded from both. Use house data as a proxy for townhouses — multiply typical price by ~0.8 for a rough estimate.

Data Coverage

• ~5,000 of ~15,000 suburbs have market data. The rest are unpopulated, remote, or lack transaction volume.
• Confidence is the primary quality indicator. ~50 sales/year = high confidence.
• Zero values are valid data. Zero SoM means no new listings (supply constraint), not missing data.
• ABS-derived metrics (IRSAD, RO ratio) update every ~5 years post-census.

Bedroom Segmentation

Always query with default (all bedrooms) as baseline. Bedroom-specific data (1–5 beds) is available where transaction volume supports it, but many suburbs have gaps. Request "all" first, then layer bedroom-specific data if needed.

Response Formatting Best Practices

When presenting HTAG data to users:

1. Lead with the headline — typical price, yield, RCS overall score
2. Use tables for structured data (Pricing & Yield, RCS Scores, Supply Conditions)
3. Interpret, don't just dump — say what the numbers mean using the thresholds above
4. Combine metrics — GRC alone is unreliable; pair with GPD, GSP, supply, demand
5. Flag constraints — mention yield viability for lending, entry price barriers, low confidence
6. End with a takeaway — synthesise everything into a clear investment characterisation