Skip to main content
Glama
Sign In

Homesage.ai MCP

by ai.homesage.api
OverviewDiscussionsAdmin

Get Renovation Return

get_renovation_return
Read-only

What it returns

Projected return from performing a standard renovation: pre-renovation estimated value (AVM), projected post-renovation ARV (After Repair Value), the renovation cost estimate (see renovation-cost for the aggregate figure and renovation-cost-breakdown for room-level detail), the value increase, net return, ROI percent, and the maximum recommended renovation budget.

When to use it

  • Evaluate buy-and-fix-up opportunities.

  • Compare renovation vs. cosmetic-only strategies on a single property.

Pricing

3 credits.

FAQ

What renovation scope is assumed?

The scope scales with the property's assessed condition and its state, not a fixed package: a property graded Poor is costed for far more work per square foot than one graded Good. The figure is Homesage.ai's stored renovation estimate for the property; without one it is square footage × a per-square-foot factor for that condition and state. Pass sqft to override the square footage when no stored estimate exists. For explicit room-level scope, use renovation-cost-breakdown.

How is ARV calculated?

From recent sales of comparable homes in good or excellent condition. The search starts at sales within 12 months and 2 miles and widens step by step to 24 months and 10 miles until 3 to 5 qualifying comps are found. Each sale price is adjusted to the subject's size by price per square foot, outliers are dropped, and the rest are averaged. With no qualifying comps, ARV falls back to 121% of the current estimated value. A computed ARV below the property's current value is lifted to just above it. See comps for the underlying comparable set.

How are the return figures calculated?

value_increase = ARV − pre-renovation value. net_return = value_increase − renovation cost. roi_percent = net_return ÷ renovation cost × 100. max_recommended_renovation_budget = 93% of ARV − pre-renovation value. Purchase, holding, selling, and financing costs are not charged here; flip-return charges the whole project. The cash_or_financed, downpayment, interest_rate, and loan_term query parameters are accepted and validated but do not change this endpoint's result.

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_renovation_return"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqftNoOverrides the property's square footage in the renovation estimate. Takes effect only when Homesage.ai has no stored renovation estimate for the property. A non-numeric value returns 400.
property_addressYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the read-only, open-world, non-destructive profile, and the description goes well beyond them: 3-credit pricing, the condition/state-scaled cost model, the comp-widening search and 121%-of-value fallback for ARV, a floor lift when ARV is below current value, and the exact ROI formulas. One flaw holds it back: it documents `cash_or_financed`, `downpayment`, `interest_rate`, and `loan_term` as 'accepted and validated' parameters, but those fields do not exist in the input schema, which could mislead an agent into passing non-existent arguments.

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?

Well front-loaded: returns, then when-to-use, then pricing, then method detail, so an agent can stop reading early and still select correctly. The FAQ is longer than strictly necessary for tool selection — the step-by-step comp search radius/window expansion and outlier-dropping detail is reference material that could be deferred, especially since an output schema already exists.

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 two-parameter analytical tool with an output schema, the definition covers everything an agent needs to call it: the required input, the one optional override and its conditional effect, credit cost, and the formula semantics of the returned figures. The documented fallback and clamping behavior for ARV is the kind of edge case that would otherwise cause misinterpretation of results.

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

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%, so the baseline is 3. The description's explanation of the `sqft` override (works only when no stored renovation estimate exists) largely restates the schema's own description rather than adding new syntax or constraints. The only genuinely additive parameter information is the stale mention of financing parameters that aren't in the schema, which is a net negative rather than a clarification.

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 'What it returns' section names the specific output set (AVM, ARV, renovation cost, value increase, net return, ROI %, max recommended budget) for a named resource. It also explicitly distinguishes itself from siblings: `renovation-cost` for the aggregate figure, `renovation-cost-breakdown` for room-level scope, `comps` for the underlying comparable set, and `flip-return` for the full project cost.

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?

'When to use it' gives two concrete scenarios (buy-and-fix-up evaluation, renovation vs. cosmetic-only comparison on a single property). Exclusions are explicit: purchase, holding, selling, and financing costs are not charged here, and `flip-return` is named as the tool that charges the whole project, so the agent knows exactly where to route 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 toolsInspect
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