Homesage.ai MCP

Run Property Search

run_property_search

Read-only

What it returns

The full set of properties matching your investment filters — each with valuation, investment metrics, condition, and location detail. This is the charged database search.

⚠️ Cost — read before calling

1 credit per property returned. A search that matches 1,200 properties costs 1,200 credits. Charging is all-or-nothing: if the balance can't cover the whole set, nothing is charged and the call returns 402.

Always call preview_property_search first, show the user the count and cost, and get an explicit yes before calling this. Never run a broad or location-only search without confirming the cost.

When to use it

After preview_property_search and explicit user confirmation of the credit cost.
To pull a curated, filtered list of investment properties for an area.

Required filters

Same as preview_property_search: a location (city/county/ZIP — NEVER a whole state: state-wide queries time out before returning), a property_status, and at least one investment filter (or allow_location_only=true to waive only the investment filter). Send the SAME filters you previewed so the cost matches.

Pricing

1 credit per matching property, charged all-or-nothing on success. 400/401/402 cost 0 credits.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "location": "<location>",
      "property_status": "<property_status>"
    },
    "name": "run_property_search"
  }
}

Input Schema

Name	Required	Description
`to`	No	Sold-search only: latest sold date (YYYY-MM-DD).
`dom`	No	Days-on-market ceiling (for-sale only).
`from`	No	Sold-search only: earliest sold date (YYYY-MM-DD).
`auction`	No	Which catalogue to search; OMIT it for MLS listings (the default, which hides auction-only homes). `off_mls` = only off-MLS auction homes (Auction.com, Xome, Hubzu, no MLS listing). MLS and off-MLS are separate searches: an MLS listing's returns are at its list price and an off-MLS home's at its expected winning bid, so never merge or rank the two in one list. On off-MLS homes the price filters read the published bid, and `cap_rate_` and `cash_on_cash_` read the cap rate and cash-on-cash at the max bid; `property_condition` and `pfs_*` exclude them. Send the same value you previewed.
`gap_max`	No	Maximum Value Gap percentage.
`gap_min`	No	Minimum Value Gap as a PERCENTAGE (`15` = 15%): the spread between the full-potential value and the list price, relative to the list price. FOR-SALE ONLY: sold listings carry no value for it, so combining this with `property_status=sold` returns no results.
`pfs_max`	No	Maximum Seller Motivation Score (1–100).
`pfs_min`	No	Minimum Seller Motivation Score — the Price Flexibility Score, 1–100: how much negotiating room the asking price has, higher = more flexible. FOR-SALE ONLY: sold listings carry no value for it, so combining this with `property_status=sold` returns no results.
`roi_max`	No	Maximum projected ROI percentage.
`roi_min`	No	Minimum projected ROI percentage.
`location`	Yes	A JSON-encoded array of one or more area objects. City: `{"type":"city","city":"Austin","state_code":"TX"}`; county: `{"type":"county","county":"Travis County","state_code":"TX"}`; ZIP: `{"type":"postal_code","zip_code":"78704","state_code":"TX"}`. State-wide scope is not supported — a state-level area times out instead of returning. When the user asks about a whole state or a huge metro, pick the specific city, county, or ZIP that best serves their goal (or run a few targeted searches) yourself; never surface a 'narrow your area' error to the user. Several area objects in one array are searched together, so a multi-ZIP or multi-city search is one preview and one charged call.
`lpfp_max`	No	Maximum LP/ARV percentage (`85` = listed at no more than 85% of full potential).
`lpfp_min`	No	Minimum LP/ARV — the list price as a PERCENTAGE of the property's full-potential (after-repair) value, 1–100, lower is better (`80` = listed at 80% of full potential). FOR-SALE ONLY: sold listings carry no value for it, so combining this with `property_status=sold` returns no results.
`price_max`	No	Maximum price in USD.
`price_min`	No	Minimum price in USD.
`sale_type`	No	Pipe-delimited auction sale types: `foreclosure\|bank_owned\|other`.
`cap_rate_max`	No	Maximum cap rate as a percentage; use a negative value to find cash-flow-negative properties.
`cap_rate_min`	No	Minimum cap rate as a PERCENTAGE (`6.5` = 6.5%), not a ratio. Negatives are valid. Only properties with a verified rent carry this metric — about 35% of for-sale listings — and the rest are absent from the results rather than treated as zero. FOR-SALE ONLY: sold listings never carry it, so combining this with `property_status=sold` returns no results.
`property_type`	No	Pipe-delimited: `detached\|townhouse\|apartment\|multi family\|other`.
`also_at_auction`	No	`true` keeps only MLS listings that are also up for auction on Auction.com, Xome or Hubzu. Use with `auction` omitted.
`property_status`	Yes	Listing status to search. `active`/`pending` search live for-sale listings; `sold` searches historical sales (enables the `from`/`to` date range); `any` = active + pending.
`cash_on_cash_max`	No	Maximum cash-on-cash return as a percentage.
`cash_on_cash_min`	No	Minimum cash-on-cash return as a PERCENTAGE (`4` = 4%). Negatives are valid. Only properties with a verified rent carry this metric — about 35% of for-sale listings — and the rest are absent from the results rather than treated as zero. FOR-SALE ONLY: sold listings never carry it, so combining this with `property_status=sold` returns no results.
`monthly_rent_max`	No	Maximum estimated monthly rent in whole USD.
`monthly_rent_min`	No	Minimum estimated monthly rent in whole USD.
`rent_to_price_max`	No	Maximum monthly rent as a ratio of price (`0.02` = 2%/mo).
`rent_to_price_min`	No	Minimum monthly rent as a RATIO of price (`0.007` = 0.7%/mo).
`property_condition`	No	Pipe-delimited: `excellent\|good\|outdated\|very poor\|poor\|unlivable`.
`published_bid_only`	No	`true` leaves out auction homes whose opening bid is not published yet.
`allow_location_only`	No	Waive ONLY the investment-filter requirement (location + status still required). Use with care — can match thousands of properties.
`auction_within_days`	No	Only homes whose next auction falls within the next N days: `7`, `30` or `90`.
`investment_potential_min`	No	Minimum Investment Potential score (0–100), for-sale only. Ignored when `investment_potential_grades` is also sent — the grades win — so send one or the other.
`investment_potential_grades`	No	Pipe-delimited (for-sale only): `excel\|high\|med\|low\|noPot`.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well past the annotations (readOnlyHint/openWorldHint/destructiveHint) by disclosing the credit model: 1 credit per matched property, all-or-nothing charging, a 402 when balance is insufficient, and 0-credit cost for 400/401/402. It also warns that state-wide queries time out and tells the agent to narrow silently, which is exactly the kind of behavioral context annotations cannot 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?

Headings front-load return value and then cost, which is the right priority ordering, and each section is scannable. Minor redundancy: '1 credit per property' is stated in the Cost section and again under Pricing, and the all-or-nothing rule appears twice, costing a little tightness.

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?

Despite 33 parameters, the agent needs only the preview-then-confirm workflow and the required filter rules to call this correctly, and both are fully covered. With an output schema present the description does not need to explain return shape, and annotations cover the safety profile, so nothing material 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 schema carries parameter definitions and the baseline is 3. The description still adds cross-tool meaning the schema cannot: required filter composition (location + status + one investment filter, or `allow_location_only`), the prohibition on state-level locations, and the instruction to send identical filters to the preview so the charge matches.

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 and states exactly what comes back (valuation, investment metrics, condition, location), then immediately distinguishes itself from `preview_property_search` as 'the charged database search'. An agent can route between the two siblings without opening either schema.

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?

Has an explicit 'When to use it' section naming the prerequisite (a prior `preview_property_search` plus explicit user confirmation of cost) and the exclusion (never run a broad or location-only search without confirming cost). It also instructs the agent to reuse the previewed filters so cost matches, which is real when-to-use guidance rather than generic filler.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?