Housing Intel

Housing Market Snapshot

housing_market_snapshot

Read-onlyIdempotent

Get national housing market overview: mortgage rates, housing starts, Case-Shiller index, unemployment, construction employment. Optionally add metro-level prices (e.g., "Denver", "Atlanta"). For comparing Case-Shiller across multiple metros use case_shiller_metro_compare instead. THE COMPONENTS DO NOT SHARE A DATE — they are weekly, monthly and quarterly official statistics, each published on its own lag, so one call can span months of vintages. freshness states the span in days and names the oldest component; read it before comparing components against each other.

Input Schema

TableJSON Schema

Name	Required	Description
`_blsKey`	No	BLS registration key (optional — raises the shared quota; https://data.bls.gov/registrationEngine/)
`_fredKey`	No	FRED API key (https://fred.stlouisfed.org/docs/api/api_key.html)
`metro_name`	No	Metro area name for metro-level FHFA HPI (e.g., "Denver", "Atlanta"). Supports top 50 US metros. National data is always included.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Explanation of data scope and sources
`metro`	No	Metro name or 'National'
`zillow`	No
`freshness`	No
`metro_hpi`	No
`case_shiller`	No
`unemployment`	No
`mortgage_rate`	No
`snapshot_date`	No	Today's date in YYYY-MM-DD format
`housing_starts`	No
`owners_equiv_rent`	No
`construction_employment`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed47 schema fields changedSep 27, 2026

changedOutput schema / properties / case_shiller / properties / 3mo_trend / items / properties / value / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```
addedOutput schema / properties / case_shiller / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / case_shiller / properties / error
```
Removed value: -{
-  "type": "string"
-}
```
addedOutput schema / properties / case_shiller / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / case_shiller / properties / scope / enum
```
Removed value: -[
-  "national"
-]
```
addedOutput schema / properties / case_shiller / properties / smoothing
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / construction_employment / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / construction_employment / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / construction_employment / properties / scope / enum
```
Removed value: -[
-  "national"
-]
```
changedOutput schema / properties / construction_employment / properties / trend / items / properties / value / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```
removedOutput schema / properties / construction_employment / properties / unit / enum
```
Removed value: -[
-  "thousands"
-]
```

addedOutput schema / properties / freshness

Added value: +{
+  "properties": {
+    "as_of": {
+      "type": "string"
+    },
+    "components": {
+      "items": {
+        "properties": {
+          "age_days": {
+            "type": "number"
+          },
+          "cadence": {
+            "type": "string"
+          },
+          "component": {
+            "type": "string"
+          },
+          "observation_date": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "components_without_a_date": {
+      "items": {
+        "type": [
+          null,
+          "string"
+        ]
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    },
+    "newest_component": {
+      "type": "string"
+    },
+    "newest_observation_date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "oldest_age_days": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "oldest_component": {
+      "type": "string"
+    },
+    "oldest_observation_date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "span_days": {
+      "type": "number"
+    },
+    "statement": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / housing_starts / properties / 3mo_trend / items / properties / value / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```
addedOutput schema / properties / housing_starts / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / housing_starts / properties / error
```
Removed value: -{
-  "type": "string"
-}
```
addedOutput schema / properties / housing_starts / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / housing_starts / properties / scope / enum
```
Removed value: -[
-  "national"
-]
```
removedOutput schema / properties / housing_starts / properties / unit / enum
```
Removed value: -[
-  "thousands"
-]
```
addedOutput schema / properties / metro_hpi / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / metro_hpi / properties / current / description
```
Removed value: -"Latest metro HPI value"
```
removedOutput schema / properties / metro_hpi / properties / error
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / metro_hpi / properties / metro / description
```
Removed value: -"Metro name"
```
addedOutput schema / properties / metro_hpi / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
changedOutput schema / properties / metro_hpi / properties / recent_data / items / properties / value / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```
removedOutput schema / properties / metro_hpi / properties / series / description
```
Removed value: -"FRED series ID for metro FHFA HPI"
```
removedOutput schema / properties / metro_hpi / properties / trend / enum
```
Removed value: -[
-  "rising",
-  "falling",
-  "stable"
-]
```
removedOutput schema / properties / metro_hpi / properties / yoy / properties / change / description
```
Removed value: -"Year-over-year absolute change"
```
removedOutput schema / properties / metro_hpi / properties / yoy / properties / pctChange / description
```
Removed value: -"Year-over-year percent change"
```

changedOutput schema / properties / metro_hpi / type

Previous value: -[
-  "object",
-  "null"
-]New value: +[
+  "null",
+  "object"
+]

addedOutput schema / properties / mortgage_rate / properties / 4wk_ago_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
addedOutput schema / properties / mortgage_rate / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / mortgage_rate / properties / error

Removed value: -{
-  "description": "Error message if data unavailable",
-  "type": "string"
-}

addedOutput schema / properties / mortgage_rate / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / mortgage_rate / properties / scope / enum
```
Removed value: -[
-  "national"
-]
```
removedOutput schema / properties / mortgage_rate / properties / trend / enum
```
Removed value: -[
-  "rising",
-  "falling",
-  "stable"
-]
```

changedOutput schema / properties / mortgage_rate / type

Previous value: -"object"New value: +[
+  "object",
+  "null"
+]

addedOutput schema / properties / owners_equiv_rent / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / owners_equiv_rent / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / owners_equiv_rent / properties / scope / enum
```
Removed value: -[
-  "national"
-]
```
changedOutput schema / properties / owners_equiv_rent / properties / trend / items / properties / value / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```

changedOutput schema / properties / snapshot_date / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

addedOutput schema / properties / unemployment / properties / cadence
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / unemployment / properties / observation_date
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
removedOutput schema / properties / unemployment / properties / scope / enum
```
Removed value: -[
-  "national"
-]
```
changedOutput schema / properties / unemployment / properties / trend / items / properties / value / type
```
Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / zillow / properties / error

Removed value: -{
-  "description": "Error message if Zillow data unavailable",
-  "type": "string"
-}

removedOutput schema / properties / zillow / properties / scope / enum
```
Removed value: -[
-  "metro",
-  "national"
-]
```

Changed1 schema field changedAug 8, 2026

addedInput schema / properties / _blsKey

Added value: +{
+  "description": "BLS registration key (optional — raises the shared quota; https://data.bls.gov/registrationEngine/)",
+  "type": "string"
+}

Changed2 schema fields changedAug 4, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_fredKey": "your-housing-intel-api-key"
-  },
-  {
-    "_fredKey": "your-housing-intel-api-key",
-    "metro_name": "Denver"
-  }
-]New value: +[
+  {},
+  {
+    "metro_name": "Denver"
+  }
+]

changedInput schema / required

Previous value: -[
-  "_fredKey"
-]New value: +[]

Changed1 schema field changedMay 28, 2026
- changedOutput schema / properties / metro_hpi / type
```
Previous value: -"object"New value: +[
+  "object",
+  "null"
+]
```

Changed19 schema fields changedMay 24, 2026

addedOutput schema / properties / case_shiller / properties / current / description
```
Added value: +"Latest Case-Shiller index value"
```
addedOutput schema / properties / construction_employment / properties / current / description
```
Added value: +"Construction employment in thousands"
```
addedOutput schema / properties / housing_starts / properties / 3mo_trend / items / properties / date / description
```
Added value: +"ISO date YYYY-MM-DD"
```

changedOutput schema / properties / housing_starts / properties / current / description

Previous value: -"Current housing starts value"New value: +"Latest housing starts in thousands"

changedOutput schema / properties / metro / description

Previous value: -"Metro area name (National or requested metro)"New value: +"Metro name or 'National'"

addedOutput schema / properties / metro_hpi / properties / current / description
```
Added value: +"Latest metro HPI value"
```
addedOutput schema / properties / metro_hpi / properties / metro / description
```
Added value: +"Metro name"
```

changedOutput schema / properties / metro_hpi / properties / series / description

Previous value: -"FRED series ID"New value: +"FRED series ID for metro FHFA HPI"

addedOutput schema / properties / metro_hpi / properties / yoy / properties / change / description
```
Added value: +"Year-over-year absolute change"
```
addedOutput schema / properties / metro_hpi / properties / yoy / properties / pctChange / description
```
Added value: +"Year-over-year percent change"
```
changedOutput schema / properties / mortgage_rate / properties / 4wk_ago / description
```
Previous value: -"Rate from 4 weeks ago"New value: +"Mortgage rate 4 weeks ago"
```

changedOutput schema / properties / mortgage_rate / properties / current / description

Previous value: -"Current mortgage rate (%)"New value: +"Current 30-year mortgage rate (percent)"

changedOutput schema / properties / mortgage_rate / properties / error / description

Previous value: -"Error message if unavailable"New value: +"Error message if data unavailable"

changedOutput schema / properties / note / description

Previous value: -"Data scope note"New value: +"Explanation of data scope and sources"

addedOutput schema / properties / owners_equiv_rent / properties / current / description
```
Added value: +"Owners' equivalent rent index"
```

changedOutput schema / properties / snapshot_date / description

Previous value: -"ISO date of snapshot"New value: +"Today's date in YYYY-MM-DD format"

addedOutput schema / properties / unemployment / properties / current / description
```
Added value: +"Current unemployment rate (percent)"
```

addedOutput schema / properties / zillow

Added value: +{
+  "properties": {
+    "error": {
+      "description": "Error message if Zillow data unavailable",
+      "type": "string"
+    },
+    "home_value_index": {
+      "properties": {
+        "date": {
+          "description": "ISO date of observation",
+          "type": "string"
+        },
+        "note": {
+          "description": "Description of metric",
+          "type": "string"
+        },
+        "value": {
+          "description": "ZHVI value in USD",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "inventory": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "value": {
+          "description": "For-sale inventory (smoothed)",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "median_sale_price": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "value": {
+          "description": "Weekly median sale price in USD",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "new_listings": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "value": {
+          "description": "Monthly new listings",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "region": {
+      "description": "Region name (CBSA label or 'National')",
+      "type": "string"
+    },
+    "rent_index": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "value": {
+          "description": "ZORI value in USD/month",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "sales_count": {
+      "properties": {
+        "date": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        },
+        "value": {
+          "description": "Monthly sales count",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "scope": {
+      "description": "Whether data is metro-specific or national",
+      "enum": [
+        "metro",
+        "national"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "snapshot_date",
-  "metro",
-  "note",
-  "mortgage_rate",
-  "housing_starts",
-  "case_shiller",
-  "unemployment",
-  "owners_equiv_rent",
-  "construction_employment"
-]

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "case_shiller": {
+      "properties": {
+        "3mo_trend": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "value": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "current": {
+          "type": "number"
+        },
+        "error": {
+          "type": "string"
+        },
+        "scope": {
+          "enum": [
+            "national"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "construction_employment": {
+      "properties": {
+        "current": {
+          "type": "number"
+        },
+        "error": {
+          "type": "string"
+        },
+        "scope": {
+          "enum": [
+            "national"
+          ],
+          "type": "string"
+        },
+        "trend": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "value": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "unit": {
+          "enum": [
+            "thousands"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "housing_starts": {
+      "properties": {
+        "3mo_trend": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "value": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "current": {
+          "description": "Current housing starts value",
+          "type": "number"
+        },
+        "error": {
+          "type": "string"
+        },
+        "scope": {
+          "enum": [
+            "national"
+          ],
+          "type": "string"
+        },
+        "unit": {
+          "enum": [
+            "thousands"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "metro": {
+      "description": "Metro area name (National or requested metro)",
+      "type": "string"
+    },
+    "metro_hpi": {
+      "properties": {
+        "current": {
+          "type": "number"
+        },
+        "error": {
+          "type": "string"
+        },
+        "metro": {
+          "type": "string"
+        },
+        "recent_data": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "value": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "series": {
+          "description": "FRED series ID",
+          "type": "string"
+        },
+        "trend": {
+          "enum": [
+            "rising",
+            "falling",
+            "stable"
+          ],
+          "type": "string"
+        },
+        "yoy": {
+          "properties": {
+            "change": {
+              "type": "number"
+            },
+            "pctChange": {
+              "type": "number"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "mortgage_rate": {
+      "properties": {
+        "4wk_ago": {
+          "description": "Rate from 4 weeks ago",
+          "type": "number"
+        },
+        "current": {
+          "description": "Current mortgage rate (%)",
+          "type": "number"
+        },
+        "error": {
+          "description": "Error message if unavailable",
+          "type": "string"
+        },
+        "scope": {
+          "enum": [
+            "national"
+          ],
+          "type": "string"
+        },
+        "trend": {
+          "enum": [
+            "rising",
+            "falling",
+            "stable"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "note": {
+      "description": "Data scope note",
+      "type": "string"
+    },
+    "owners_equiv_rent": {
+      "properties": {
+        "current": {
+          "type": "number"
+        },
+        "error": {
+          "type": "string"
+        },
+        "scope": {
+          "enum": [
+            "national"
+          ],
+          "type": "string"
+        },
+        "trend": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "value": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "snapshot_date": {
+      "description": "ISO date of snapshot",
+      "type": "string"
+    },
+    "unemployment": {
+      "properties": {
+        "current": {
+          "type": "number"
+        },
+        "error": {
+          "type": "string"
+        },
+        "scope": {
+          "enum": [
+            "national"
+          ],
+          "type": "string"
+        },
+        "trend": {
+          "items": {
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "value": {
+                "type": "number"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "snapshot_date",
+    "metro",
+    "note",
+    "mortgage_rate",
+    "housing_starts",
+    "case_shiller",
+    "unemployment",
+    "owners_equiv_rent",
+    "construction_employment"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "_fredKey": "your-housing-intel-api-key"
+  },
+  {
+    "_fredKey": "your-housing-intel-api-key",
+    "metro_name": "Denver"
+  }
+]

First observedApr 22, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses a subtle and important behavioral trait: components do not share the same date because they are weekly, monthly, and quarterly series with separate publication lags. It further explains that `freshness` states the span in days and identifies the oldest component, which is essential for correct interpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core purpose and components appear first, the alternative routing second, and the crucial date-vintage warning last. Every sentence earns its place, and the CAPS warning is used sparingly for a genuinely important caveat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists and parameters are fully documented, the description covers what an agent needs to select and invoke the tool correctly. It explains optional metro pricing, names the comparison sibling, and highlights the vintage/freshness behavior, leaving no significant operational gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds an example for metro_name and mentions that national data is always included, both already present in the schema. It does not meaningfully augment parameter meaning beyond the structured definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('Get national housing market overview') and enumerates the exact components included: mortgage rates, housing starts, Case-Shiller index, unemployment, and construction employment. It also differentiates itself from case_shiller_metro_compare by stating that metro-level comparison is handled there instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs when to use an alternative ('For comparing Case-Shiller across multiple metros use case_shiller_metro_compare instead'). It also gives clear usage context: national data is always present, metro-level prices can be added optionally, and the freshness field should be read before comparing components.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Housing Intel tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.