Homesage.ai MCP

Get Comparable Sales

get_comps

Read-only

What it returns

A ranked list of comparable sold properties within a search radius of the subject — each comp scored on similarity (size, beds/baths, year built, distance, condition delta) with the sale price and date. Powers AVM and ARV computations.

When to use it

Build a comps table on a property report page.
Validate AVM against the comparable set it's derived from.
Power custom value models with raw comp inputs.

Performance

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

Pricing

5 credits.

FAQ

How are comps ranked?

By a weighted similarity score that favors smaller size/feature deltas and shorter geographic distance. Sold date recency is a strong negative weight on older sales.

Does it adjust for condition?

Yes — if both the subject and comp have AI-condition scores, prices are adjusted up/down for the condition delta.

Fallback parameters

You can pass user-supplied values for the attributes the comp model uses, as fallbacks: Homesage.ai data is always used when available; your value is used only when our record is missing that field — so verified data is never overridden. Supported fallbacks: total_size, bedrooms, bathrooms, property_type. Only total_size can unblock an otherwise-empty result; the others just refine comp matching. year_built is intentionally not a factor in the comp/ARV model.

Every response includes a field_sources object telling you where each value came from: homesage (our data), user_provided (your fallback), or unavailable.

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": {
      "property_address": "<property_address>"
    },
    "name": "get_comps"
  }
}

Input Schema

Name	Required	Description
`bedrooms`	No	Fallback bedroom count. Refines comp matching when Homesage.ai is missing it; used only as a fallback.
`bathrooms`	No	Fallback bathroom count. Refines comp matching when Homesage.ai is missing it; used only as a fallback.
`total_size`	No	Fallback square footage. Used only when Homesage.ai has no size on record — supplying it unblocks an otherwise-empty result. Verified Homesage.ai data is never overridden.
`property_type`	No	Fallback property type, e.g. `single_family`. Refines comp matching when Homesage.ai is missing it; used only as a fallback.
`property_address`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Beyond the readOnly/openWorld annotations, the description discloses behavior that matters operationally: a slow endpoint requiring a 60-second client timeout and response caching, a 5-credit cost, and the non-override fallback rule with field_sources provenance. A minor gap is that result count, radius defaults, and pagination limits are never stated.

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?

Markdown headings front-load 'What it returns' before usage and cost, which suits scanning by an agent or reader. The FAQ format is somewhat heavy for a small payload — pricing and ranking detail could be tighter — but no section is filler.

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 read-only endpoint with an output schema present and only one required parameter, the description covers return composition, ranking logic, performance expectations, cost, and fallback semantics. An agent has everything needed to call it correctly and interpret the result.

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 80%, so the baseline is 3, and the description clearly earns above that by explaining precedence (Homesage data always wins, user values only fill gaps), that only total_size can unblock an otherwise-empty result, and that year_built is deliberately excluded from the comp model. That is meaning the schema alone does not convey.

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 opening section states a specific verb and resource — a ranked list of comparable sold properties within a search radius of the subject — and enumerates the ranking inputs (size, beds/baths, year built, distance, condition delta). This clearly separates it from sibling bulk/zip-level tools like get_sold_properties_by_zip and get_full_report.

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 'When to use it' section gives three concrete scenarios (report comps table, AVM validation, custom value models), which is strong positive guidance. It stops short of naming an explicit alternative or a when-not-to-use condition relative to the many sibling valuation endpoints.

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?