Skip to main content
Glama
zillow-mcp

zillow-mcp

by chrischall

Get Zillow price history for a property

zillow_get_price_history
Read-onlyIdempotent

Fetch a property's listing-price history—listed, price changes, pending, sold—by Zillow zpid or homedetails URL, returning raw and normalized event arrays.

Instructions

Listing-price events for a property — listings, price changes, pending, sold, etc. — by zpid or homedetails URL. Returns two parallel arrays: events (raw Zillow shape with event strings and MLS attribution) and events_normalized (cross-MCP shared shape with a fixed type enum: Listed/PriceChange/Pending/Contingent/Sold/Withdrawn/Relisted/Delisted). The normalized form lets callers merge histories across real-estate MCPs without re-implementing taxonomy. Sourced from the same homedetails page as zillow_get_property. For some listings (commonly non-Showcase) Zillow omits the history from the server-rendered page; then events is empty and an explanatory note is returned — distinct from a genuine no-history.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "zillow_get_price_history"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNoZillow homedetails URL or path
zpidNoZillow Property ID

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.4
    • changedInput schema / properties / zpid / anyOf
      Previous value: -[
      -  {
      -    "exclusiveMinimum": 0,
      -    "maximum": 9007199254740991,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "string"
      -  }
      -]New value: +[
      +  {
      +    "exclusiveMinimum": 0,
      +    "maximum": 9007199254740991,
      +    "type": "integer"
      +  },
      +  {
      +    "pattern": "^\\d+$",
      +    "type": "string"
      +  }
      +]
  2. Changed1 schema field changedv1.0.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  3. First observedv0.11.1

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already mark this read-only/idempotent, and the description adds substantial non-structured context: the dual return arrays, the fixed normalized `type` enum, and the important edge case where Zillow omits history (empty `events` plus explanatory `note`, distinct from genuine no-history).

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?

Front-loads the core purpose, then the return shape, then the edge case, in four tight sentences with no filler. The em-dash clauses carry real information rather than padding.

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?

With no output schema, the description fully carries the burden: it explains both return arrays, the normalized enum, and the failure/empty case. An agent has everything needed to call and interpret the result.

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 coverage is 100%, so both parameters (url, zpid) are already documented in the schema. The description only restates the two lookup keys without adding format or precedence guidance (e.g., which key wins if both are supplied).

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?

States a specific verb and resource ('Listing-price events for a property') plus the full event taxonomy and the two lookup keys. It is immediately distinguishable from siblings like zillow_get_zestimate_history and zillow_get_tax_history.

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

Usage Guidelines4/5

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

Gives clear context: use zpid or homedetails URL, and notes it is sourced from the same page as zillow_get_property. It does not explicitly state exclusions (e.g., 'use zestimate_history instead for value estimates'), so routing is implied rather than spelled out.

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