Skip to main content
Glama
chrischall

zillow-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Bulk-resolve addresses → Zillow zpids

zillow_resolve_addresses
Read-onlyIdempotent

Resolve up to 100 free-text or structured addresses to Zillow zpids and canonical URLs in one call, with price hints for disambiguation and fallback resolver for rural or locality-mismatched rows.

Instructions

Resolve up to 100 free-text or structured addresses to Zillow zpids + canonical URLs in one call. Each row may be a bare string or {address, city?, state?, zip?, price_hint?}. IMPORTANT: price_hint (USD) is frequently load-bearing — for rural / mountain-MLS / locality-mismatched rows the search-fallback rung is often the ONLY rung that hits, and without a price band it cannot disambiguate. The resolver derives a ±0.5% band from the hint. Always pass price_hint for any row where you have a sense of the price. Runs the same 5-rung resolver as zillow_get_by_address (direct → autocomplete-typeahead → suffix-expansion → locality-remap → search-fallback) — bulk and single walk the same ladder via the shared resolver, so they match the same partition for the same inputs. Locality-remap rung handles real-world mountain-MLS cases (Lake Lure <-> Rutherfordton, Beech/Sugar Mountain <-> Banner Elk) where Zillow indexes the parent locality; when it fires, queried_city (what you sent) and resolved_city (what Zillow returned) are both set so the caller can see the substitution. Concurrent fan-out — a 60-address batch returns in roughly one round trip instead of 60. Per-row error capture so one bad address never fails the batch. confidence is "exact" for direct hits, "autocomplete" / "suffix_expansion" / "locality_remap" / "search_fallback" for retries, "none" when all rungs missed. The whole call is bounded by an overall hard deadline (issue #98), like zillow_bulk_get: a single slow/hung row never wedges the server — when the deadline is reached any unsettled row is returned with error_kind: "pending" (distinct from a real miss) and the response carries a pending count so you can re-run just those addresses. Every lookup is paced by the same per-host requests-per-minute throttle as zillow_bulk_get so a big batch does not trip Zillow's PerimeterX bot-wall. If the wall is hit, the remaining rows stop querying Zillow and come back with error_kind: "bot_challenge" (never a plain miss), and the response carries a { blocked, retry_after_s } envelope so you can re-run them later. Other failed rows carry error_kind timeout / bridge_down / protocol / other. Read-only, no auth required.

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.
addressesYesFree-text addresses (e.g. "126 Sleeping Bear Ln, Lake Lure, NC") or structured rows. 1..100.

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.7/5.0
Behavior5/5

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

This is unusually transparent. It discloses concurrent fan-out, a hard overall deadline, per-row error capture, bot-wall challenges with blocked/retry_after_s, rate throttling, rung-wise confidence values, and locality remapping behavior. The readOnly/idempotent annotations are consistent with 'Read-only, no auth required,' so there is no contradiction.

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 long but dense and front-loaded: purpose, limit, and the critical price_hint warning come first. Some redundancy exists in repeatedly cross-referencing zillow_bulk_get and the shared resolver, but each sentence still contributes behavioral or operational context.

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 carries the full burden of explaining return semantics, and it largely succeeds. It defines all confidence values, enumerates error_kind values including 'pending' and 'bot_challenge,' and documents the pending count and blocked envelope. This is complete enough for an agent to call the tool correctly and handle failure modes.

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

Parameters5/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, but the description adds substantial param-level value. It explains that price_hint is frequently the only disambiguator, derives a ±0.5% band from it, and clarifies the bare-string vs structured-object address forms. This goes well beyond the schema's type 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 opens with a specific verb and resource: 'Resolve up to 100 free-text or structured addresses to Zillow zpids + canonical URLs in one call.' It clearly distinguishes itself from the single-address sibling zillow_get_by_address by framing this as the bulk variant and explicitly stating both share the same 5-rung resolver.

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?

The description gives strong practical guidance: 'Always pass price_hint for any row where you have a sense of the price' and explains why it is load-bearing. It names zillow_get_by_address as the single-address alternative and notes that bulk and single walk the same resolver ladder, but it does not explicitly state a when-not condition such as 'for one address, prefer zillow_get_by_address.'

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