Skip to main content
Glama
chrischall

zillow-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search Zillow listings

zillow_search_properties
Read-onlyIdempotent

Search Zillow property listings by city, ZIP, neighborhood, or address with filters for price, beds, baths, status, and home type. Returns matching homes with details, Zestimate, and URLs.

Instructions

Search Zillow listings by location (city, ZIP, neighborhood, or address) and optional filters (status, price band, beds/baths minimums, home types). Returns matching properties with price, beds/baths, sqft, Zestimate, status, image, and homedetails URL. Works with city/ZIP-level queries (filtered against your criteria) AND with full-address or street-only queries (returns the listings Zillow resolves to directly — filters are not applied in this single-round-trip path; use zillow_get_by_address for the cleanest one-shot address → zpid lookup). Throws LocationNotResolved if Zillow can't pin either a region or matching listings for the input (instead of silently falling back to your default search region). Heads up: Zillow renders ~40 listings per page server-side; this tool auto-paginates by default when limit exceeds that, walking subsequent pages and concatenating results (set auto_paginate: false to opt out and get the single-page response). For dense markets, price-band the search to enumerate fully. Does NOT return Zestimate history — use zillow_get_zestimate_history for that. Read-only; safe to call repeatedly.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
viewNoResponse shape: "compact" (default) drops fields the response already carries elsewhere; "full" returns every field this server understands. compact strips image/avatar URLs from the response; "full" returns Zillow's payload untouched. No field projection: this server has no verified record of which Zillow fields matter, and inventing one would risk dropping a field a caller needs.
limitNoMax listings to return (default 40, max 1000). When > 40 and `auto_paginate` is true (the default), the tool walks Zillow's pagination server-side and aggregates pages until `limit` is reached, an empty page is returned, or a page adds no new listings. Zillow caps each search response at ~40 listings (issue #54).
statusNoListing status. Default for_sale.
beds_minNo
locationYesFree-text location: city, ZIP, neighborhood, or address (e.g. "Brooklyn, NY", "94110", "Park Slope")
baths_minNo
price_maxNo
price_minNo
home_typesNoRestrict to one or more home types.
map_boundsNoOptional map viewport (lat/lng box) to intersect with the location — use to tile dense markets.
include_metaNoWhen true, return {meta, results}: meta carries Zillow's own total_result_count, pages fetched, listings dropped by the filter/home-type guards, and `truncated` (more matches exist than were returned).
auto_paginateNoWhen true (default), aggregate across Zillow's paginated search responses until `limit` is reached. Pass `false` to disable pagination — only one Zillow page is fetched (~40 listings).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.2.0
    • addedInput schema / properties / include_meta
      Added value: +{
+  "description": "When true, return {meta, results}: meta carries Zillow's own total_result_count, pages fetched, listings dropped by the filter/home-type guards, and `truncated` (more matches exist than were returned).",
+  "type": "boolean"
+}
    • addedInput schema / properties / map_bounds
      Added value: +{
+  "description": "Optional map viewport (lat/lng box) to intersect with the location — use to tile dense markets.",
+  "properties": {
+    "east": {
+      "type": "number"
+    },
+    "north": {
+      "type": "number"
+    },
+    "south": {
+      "type": "number"
+    },
+    "west": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "north",
+    "south",
+    "east",
+    "west"
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changedv1.1.2
    • changedInput schema / properties / limit / description
      Previous value: -"Max listings to return (default 40). When > 40 and `auto_paginate` is true (the default), the tool walks Zillow's pagination server-side and aggregates pages until either `limit` is reached or an empty page is returned. Zillow caps each search response at ~40 listings (issue #54)."New value: +"Max listings to return (default 40, max 1000). When > 40 and `auto_paginate` is true (the default), the tool walks Zillow's pagination server-side and aggregates pages until `limit` is reached, an empty page is returned, or a page adds no new listings. Zillow caps each search response at ~40 listings (issue #54)."
    • changedInput schema / properties / limit / maximum
      Previous value: -9007199254740991New value: +1000
  3. 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"
  4. Changed1 schema field changedv0.13.0
    • addedInput schema / properties / view
      Added value: +{
+  "description": "Response shape: \"compact\" (default) drops fields the response already carries elsewhere; \"full\" returns every field this server understands. compact strips image/avatar URLs from the response; \"full\" returns Zillow's payload untouched. No field projection: this server has no verified record of which Zillow fields matter, and inventing one would risk dropping a field a caller needs.",
+  "enum": [
+    "compact",
+    "full"
+  ],
+  "type": "string"
+}
  5. First observedv0.11.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/open-world, but the description goes well beyond them: error behavior (throws LocationNotResolved rather than silently defaulting), the ~40-listings-per-page server cap and auto-pagination semantics, and the fact that filters are skipped on the address path. That is exactly the behavioral context annotations cannot express.

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

Conciseness4/5

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

Front-loads purpose, then routings, then caveats, with no filler sentences. It is long and leans on parenthetical asides, but nearly every clause carries actionable information, so it stays just short of over-verbose.

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?

For a 12-param open-world search with no output schema, the description names the returned fields, the meta behavior (total_result_count, pages fetched, truncated), pagination edge cases, and failure mode. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

With 67% schema coverage, the description still adds real meaning: the interaction between `limit` and `auto_paginate`, what `view: compact` strips (image/avatar URLs), and that `map_bounds` exists to tile dense markets. A few params (beds_min, baths_min, price_min/max) get no extra context, keeping it below 5.

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?

Opens with a specific verb+resource ('Search Zillow listings by location...and optional filters') and enumerates the filter dimensions and return fields, so an agent knows exactly what it produces. It also explicitly distinguishes itself from zillow_get_by_address and zillow_get_zestimate_history.

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?

Gives explicit routing rules: city/ZIP queries get filters applied, full-address queries do not, and zillow_get_by_address is named as the cleaner one-shot address lookup. It adds a tactical recommendation (price-band dense markets) and names the alternative for Zestimate history.

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

Deploy Server

Other Tools