Homesage.ai MCP

Bulk Property Search

bulk_property_info

Read-only

What it returns

Paginated search across all US residential properties matching geo + price + bed/bath/sqft/year-built/DOM/lot filters. Each result row carries ROI-relevant fields (AVM bands, financing/holding/project-cost breakdowns, potential ROI) — designed to feed investor screening dashboards, not detail pages.

When to use it

Build investor screening with multi-criteria filters (e.g. "active listings under $300k in zip 65802 with potential_roi > 0.15").
Generate market reports: average AVM, average days on market, count of matches.
Seed a recommendation engine with filtered candidate pools.

Performance

This is a slow endpoint — use a 60-second client timeout and cache responses.

Pricing

1 credit per property in the response. A page with 50 properties costs 50 credits. Use page_size to cap cost — for screening UI, smaller pages with manual paginate-on-demand is the cost-effective pattern.

Errors

Status	Meaning
400	Invalid filter values (e.g. `min_price > max_price`, non-numeric `beds_max`).
401	Authentication failed.
402	No subscription or insufficient credits for the page size requested.
503 / 504	Backend datastore unavailable or query timed out.

FAQ

What's the difference between `property_status: "Active"` and `"Sold"`?

Active queries residential_for_sale. Sold queries residential_sold (same backing as the dedicated sold-by-zip endpoint). Both share the same response shape.

Why is `dom` calculated rather than stored?

The MLS doesn't always carry days-on-market natively. When the field is absent, the endpoint computes it from list_date to sold_date (or to "now" for active listings).

Can I filter by neighborhood?

Not directly. Filter by city + state + zip; the response includes a neighborhood field for client-side post-filtering.

Is `avm_confidence` a percentage?

A 0.0–1.0 float. Higher = the AVM model is more confident in the band. Filter on avm_confidence > 0.7 for high-quality estimates only.

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": "bulk_property_info"
  }
}

Input Schema

Name	Required	Description
`dom`	No	Days-on-market ceiling: only listings listed within the last N days. Active listings only.
`zip`	No	5-digit US ZIP code to search within. At least one of `zip`, `city`, or `state` is required.
`city`	No	City name to search within. At least one of `zip`, `city`, or `state` is required.
`page`	No	1-based page number. Defaults to 1.
`state`	No	2-letter US state code. At least one of `zip`, `city`, or `state` is required.
`dom_min`	No	Days-on-market floor: only listings listed at least N days ago. Active listings only.
`beds_max`	No	Maximum bedroom count.
`beds_min`	No	Minimum bedroom count.
`sqft_max`	No	Maximum living area in square feet.
`sqft_min`	No	Minimum living area in square feet.
`baths_max`	No	Maximum bathroom count.
`baths_min`	No	Minimum bathroom count (halves allowed, e.g. `1.5`).
`page_size`	No	Items per page. Defaults to 10, capped at 100. Caps your per-call credit cost — pass it explicitly so the cost of the call is known before it runs.
`lot_sqft_max`	No	Maximum lot size in square feet.
`lot_sqft_min`	No	Minimum lot size in square feet.
`property_type`	No	Comma-delimited property types. One or more of: `detached,townhouse,condo/co-op/apartment,multi family,duplex,mobile,farm,land,other`.
`updated_since`	No	Only properties whose record changed after this ISO-8601 timestamp (`YYYY-MM-DDTHH:MM:SSZ`).
`year_built_max`	No	Latest year built.
`year_built_min`	No	Earliest year built.
`price_range_max`	No	Maximum list price in USD.
`price_range_min`	No	Minimum list price in USD.
`property_status`	No	Listing status: `Active` (the default) searches live for-sale listings; `Sold` searches closed sales. Both return the same row shape.
`property_condition`	No	Pipe-delimited condition grades. One or more of: `excellent\|good\|outdated\|poor\|very poor\|unlivable`.
`investment_potential`	No	Comma-delimited investment-potential labels. One or more of: `excellent,high,good,n/p`.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the readOnly/openWorld annotations, it discloses the operational traits that actually change how an agent calls it: a slow endpoint requiring a 60-second timeout and caching, per-property credit pricing with page_size as the cost lever, and an error table mapping 400/401/402/503/504 to concrete causes. It also clarifies that Active vs Sold switch the backing dataset, which is behavior no annotation could convey.

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?

Headers front-load the highest-value sections (what it returns, when to use, performance, pricing) so an agent can stop reading early, and the error table and FAQ are scannable. It is long for a tool description and a couple of FAQ entries (DOM computation) are nice-to-know rather than decision-relevant, but little is genuinely wasted.

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 24-parameter, open-world, paid, slow endpoint, the description covers the full calling picture: what a row contains, relative cost, timeout and caching expectations, failure modes, and the filter-to-dataset mapping. An output schema exists, so not restating every return field is correct, and nothing an agent needs to call this safely 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 real meaning on the parameters that are ambiguous: property_status maps to residential_for_sale vs residential_sold, dom may be computed from list_date when MLS lacks it, avm_confidence is a 0.0–1.0 float with a >0.7 filtering tip, and page_size is framed as a cost control. It leaves most range filters (beds, sqft, lot, year_built) to the schema, which is appropriate given they are self-describing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a specific verb and resource: a paginated search over US residential properties with geo/price/bed-bath/sqft/year-built/DOM/lot filters, and explicitly frames the output as screening-dashboard rows rather than detail pages, which separates it from get_property_info-style tools. It never names its closest siblings (run_property_search, preview_property_search), so an agent must infer the boundary from those tools' own descriptions.

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?

Three concrete when-to-use scenarios are given (multi-criteria screening, market report aggregates, seeding a recommendation pool), which is well above the usual vague guidance. There is no explicit when-not or named alternative, so the agent is not told when to prefer preview_property_search or run_property_search instead.

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

All Homesage.ai MCP tools Inspect

Try in Browser