Skip to main content
Glama
chrischall

zillow-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Resolve an address to its Zillow canonical URL + zpid

zillow_get_by_address
Read-onlyIdempotent

Resolves free-text addresses to Zillow property URLs and zpids, using multi-step fallbacks to handle rural or locality-mismatched locations. Provide a price range for reliable matches.

Instructions

Resolve a free-text address (with optional city/state/zip) to its Zillow canonical homedetails URL and zpid. IMPORTANT: for rural / mountain-MLS / locality-mismatched addresses (the search-fallback rung is often the ONLY rung that hits), ALWAYS pass price_min and price_max if you have any sense of the property's price band — without them the city/state search can't disambiguate and the call returns { resolved: false }. The price params are not optional niceties; they are frequently load-bearing. Tries up to 5 rungs: (1) direct resolver hit, (2) autocomplete typeahead — Zillow's own canonical address suggestions, whole-token street-matched then resolved to a zpid (high recall), (3) bidirectional street-token swap ("Rd" <-> "Road", "Hts" <-> "Heights", "Bluebird" <-> "Blue Bird"), (4) locality remap — city-drop + locality-alias substitution when the caller-supplied city fails (real-world cases: Lake Lure <-> Rutherfordton, Beech/Sugar Mountain <-> Banner Elk), (5) city/state search fallback bounded by the price band. Returns via: "direct" | "autocomplete" | "suffix_expansion" | "locality_remap" | "search_fallback" so the caller knows how the match was made; when the locality remap fires, queried_city (what you sent) and resolved_city (what Zillow returned) are both set so the caller can see the substitution. Degrades to { resolved: false } when ALL rungs miss — does not throw. Read-only, no auth required.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
zipNoZIP code (e.g. "28746").
cityNoCity name (e.g. "Lake Lure").
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.
stateNoTwo-letter state code (e.g. "NC").
addressYesStreet address (e.g. "126 Sleeping Bear Ln").
price_maxNoUpper bound for the search-fallback rung. Pair with `price_min` — same load-bearing role for rural/remapped-locality addresses.
price_minNoLower bound for the search-fallback rung. Frequently load-bearing: for rural / locality-mismatched addresses this is often the only rung that hits, and without a price band it cannot disambiguate. Pass it if you have ANY sense of the price band.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
  2. 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"
+}
  3. First observedv0.11.1

TDQS

A4.8/5.0
Behavior5/5

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

The description discloses the multi-rung resolution algorithm (direct, autocomplete, suffix expansion, locality remap, search fallback), the via field that reports which rung matched, the queried_city/resolved_city substitution visibility, and the degrade-to-{resolved:false} behavior. It also states 'Read-only, no auth required,' which complements the readOnlyHint annotation. This goes well beyond the annotations' boolean hints.

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?

The description is dense but every sentence earns its place: the price-band warning is front-loaded, the rung list is compact, and the return contract is stated. It is longer than average, but the complexity of the tool (5 rungs, 2 special return fields, fallback behavior) justifies the length. Slight redundancy between the price_min schema description and the tool description is the only minor waste.

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 7-param tool with no output schema, the description covers the resolution algorithm, the failure mode, the return contract (via, queried_city, resolved_city), and the auth/read-only profile. The view parameter's behavior is documented in the schema. Nothing an agent needs to call this correctly and interpret the result 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?

Schema coverage is 100%, so the baseline is 3. The description adds load-bearing context for price_min/price_max (disambiguation in search fallback) and explains the address/city/state interplay via the locality-remap rung. It doesn't add syntax details for zip/state/view, but the schema already covers those. The added price-band guidance and the rung-specific role of address components justify a 4.

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 opens with a specific verb and resource: 'Resolve a free-text address ... to its Zillow canonical homedetails URL and zpid.' This clearly distinguishes it from siblings like zillow_search_properties (search) and zillow_get_property (fetch by ID). The title reinforces the same purpose, and the description names the exact output artifacts (URL + zpid).

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?

The description gives explicit when-to-use guidance: it explains that for rural/mountain-MLS/locality-mismatched addresses, the search-fallback rung is often the only rung that hits, and instructs callers to ALWAYS pass price_min and price_max in those cases. It also names the fallback behavior when all rungs miss. This is actionable routing guidance beyond what the schema provides.

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