Skip to main content
Glama
chrischall

homes-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Resolve a street address to a homes.com property URL

homes_get_by_address
Read-onlyIdempotent

Resolve a US street address to its canonical homes.com property URL and hash. Uses optional price bounds to disambiguate fuzzy fallback search; returns verified match or no-listing/retry status.

Instructions

Resolve a US street address to its canonical homes.com property URL + opaque property hash. Pass address (street), city, state, and optional zip. Walks three rungs: first the structured smartsearch typeahead (POST /routes/res/consumer/smartsearch/autocomplete/ — the primary rung, the same address-suggest API homes.com's search box fires, returning the real /property/// URL directly), then a slug-routed page (parsing the embedded Schema.org JSON-LD — both the CollectionPage search-results shape and the single-RealEstateListing detail redirect), and finally a city/zip search page with street-token fuzzy match. Every candidate is verified against the input with a whole-token street match (plus a unit guard so a multi-unit building resolves to the exact unit, not a neighbour). Optional price_min / price_max (USD) bound ONLY the city/zip search-fallback rung — when an address is ambiguous or the typeahead misses and you know the listing's rough price, this narrows the area search (homes.com ?price-min=/?price-max= filter) so the fuzzy matcher picks from fewer, more-relevant candidates; omit for unchanged unbounded behaviour. Returns { url, property_hash, street_address, matched_via, resolved: true } on success — matched_via is 'typeahead' for the structured-API hit, 'slug' for a direct routing hit, 'search_fallback' for the search-page fuzzy match — or { resolved: false, error: 'no listing found' } when homes.com has no match (so the higher-level unified canonical-URL lookup can degrade gracefully). A retryable { resolved: false, status: 'timeout' | 'blocked', retryable: true } means homes.com never answered (bridge timeout) or refused (sign-in / AWS WAF challenge / HTTP 403-429) — NOT a confirmed miss; for blocked, have the user open homes.com and clear the challenge, then retry. KNOWN FAILURE MODE: rural addresses and very-new construction can still miss because homes.com hasn't indexed them yet. Compare the returned street_address against your input to confirm. For larger batches (≥ 3 addresses), prefer homes_resolve_addresses. Read-only; safe to call repeatedly.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
zipNoZIP code (optional; improves precision when present).
cityYesCity (e.g. "Lake Lure").
stateYes2-letter US state code (e.g. "NC").
addressYesStreet address (e.g. "126 Sleeping Bear Ln").
price_maxNoOptional upper price bound (USD). Applied ONLY to the search-fallback rung (homes.com's `?price-max=` filter). Useful when an address is ambiguous or the typeahead misses and you know the listing's rough price — improves disambiguation/recall. Omit for unbounded fallback.
price_minNoOptional lower price bound (USD). Applied ONLY to the city/zip search-fallback rung — bounds that area search with homes.com's `?price-min=` filter so an ambiguous address resolves against a narrower candidate set. Ignored by the typeahead/slug rungs (a single known address has nothing to narrow). Omit for unbounded fallback. Must be <= price_max when both are given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.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. First observedv1.1.1

TDQS

A4.9/5.0
Behavior5/5

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

ReadOnlyHint, OpenWorldHint, and IdempotentHint already signal safety, and the description adds substantial behavioral context beyond those annotations: the three resolution rungs, exact return shapes, retryable timeout/blocked states, the known failure mode for rural/new construction, and the instruction to compare the returned street_address against input. Nothing contradicts the annotations.

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?

Although long, every sentence earns its place: purpose is front-loaded, followed by mechanism, parameter behavior, return contracts, retry semantics, failure modes, and batching guidance. There is no filler; the density is justified by the tool's complexity and the absence of an output schema.

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 tool with no output schema, the description fully specifies success and error shapes, matched_via values, timeout/blocked semantics, known failure modes, and batch-size routing to a sibling. Nothing needed for correct invocation or result interpretation 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, but the description adds meaningful semantics beyond the schema: it explains that price_min/price_max bind ONLY the city/zip search-fallback rung, clarifies how the typeahead/slug rungs ignore them, and describes the unit guard and whole-token street-match verification. This extra context helps an agent decide which parameters matter for a given resolution.

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 US street address to its canonical homes.com property URL + opaque property hash.' It clearly differentiates from siblings by naming the batch alternative ('For larger batches (≥ 3 addresses), prefer homes_resolve_addresses') and by describing the multi-rung resolution mechanism, so an agent can distinguish it from search or property-lookup tools.

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 states exactly when to call this tool, when not to, and what alternative to use: 'For larger batches (≥ 3 addresses), prefer homes_resolve_addresses.' It also explains when optional parameters should be used ('when an address is ambiguous or the typeahead misses') and when they should be omitted ('Omit for unchanged unbounded behaviour').

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