Homesage.ai MCP

Get Fix-and-Flip Return

get_flip_return

Read-only

What it returns

A fix-and-flip return summary for the property — four numbers:

total_project_cost — the all-in cost of the flip: purchase price, purchase costs, renovation, contingency, holding, and selling costs. Financing costs are added only when cash_or_financed=financed.
profit — after-repair value (ARV) minus total_project_cost.
resale_roi — profit as a percent of the project cost (see the FAQ for the exact denominator). Negative when the deal loses money.
max_recommended_renovation_budget — the renovation spend that still leaves a 7%-of-ARV cushion above the property's current estimated value: 93% of ARV minus the current estimated value.

Differs from renovation-return, which values the renovation alone, by charging the whole project: purchase, holding, selling, and (optionally) financing.

When to use it

Underwrite flip candidates with a standard model.
Sort lead lists by projected flip ROI.

Pricing

3 credits.

FAQ

What purchase price does it assume?

The current listing price for an active listing. For an off-market property, the property's current estimated value stands in for the price.

What does the cost model include?

Purchase costs: 3% of the purchase price.
Renovation: Homesage.ai's stored renovation estimate for the property. Without one, square footage × a per-square-foot factor set by the property's assessed condition and its state.
Contingency: 3% of the renovation estimate.
Holding: 0.5% of the purchase price per month, for a 4-month project.
Selling costs: 8% of ARV.

What financing terms are assumed?

None by default: the model is a cash purchase. Pass cash_or_financed=financed to add financing on a loan of the purchase price minus the downpayment percent (default 20%): 2 points on the loan plus 7% annual interest over the 4-month hold. interest_rate and loan_term are validated but do not change the result today.

Does it deduct agent commissions?

Yes. Selling costs are a flat 8% of ARV that covers agent commission and closing costs together; the two are not itemized.

How is `resale_roi` calculated?

Profit divided by the project cost excluding the contingency line, as a percent: -4.61 means −4.61%.

Where does ARV come from?

From recent sales of comparable homes in good or excellent condition, size-adjusted and averaged. See renovation-return for the method and comps for the comparable set.

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

Input Schema

Name	Required	Description	Default
`sqft`	No	Overrides 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.
`loan_term`	No	Loan term in years. Validated as an integer but not used by the current flip model, which assumes a 4-month hold. Defaults to 30.
`downpayment`	No	Down payment as a percent of the purchase price. Used only when `cash_or_financed=financed`; the loan is the remainder. Defaults to 20.
`interest_rate`	No	Annual interest rate in percent. Validated as a number but not used by the current flip model, which applies a fixed 7% on financed deals. Defaults to 4.5.
`cash_or_financed`	No	Purchase basis. `cash` (default) charges no financing. `financed` adds loan points and interest to the project cost; see the FAQ for the terms. Any other value returns 400.	cash
`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.6/5.0

Behavior5/5

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

Annotations already declare readOnly/openWorld/non-destructive, and the description goes well beyond that: it discloses the 3-credit cost, the full cost-model percentages, the default cash assumption, the exact financed terms (2 points + 7% over a 4-month hold), and the honest caveat that `interest_rate` and `loan_term` are validated but ignored. It also flags error behavior (non-numeric returns 400) and what it does not itemize (commission vs. closing costs).

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 with headers, bullets and a clearly scoped FAQ, so an agent can skim to the relevant part. It runs long, though, and some content is duplicated — the financing terms appear in both the FAQ and the `cash_or_financed`/`downpayment` schema entries, and the 'cost model' bullets repeat constraints already captured in the parameter docs.

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 financial-model tool with six parameters and a large set of hidden assumptions, the description covers everything an agent needs to call it correctly and interpret the numbers: pricing, assumed purchase price, ARV source, cost-line definitions, the ROI denominator, and which parameters are inert today. Nothing material is left to guesswork.

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 83%, so the baseline is 3; the description earns above that by supplying financed-deal mechanics the schema only alludes to (loan = purchase price minus downpayment percent, 2 points, fixed 7% over 4 months) and by explaining when `sqft` actually takes effect (only absent a stored renovation estimate). It adds less for `property_address`, which is described nowhere in either field, leaving the address-format requirement implicit.

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 and resource ('A fix-and-flip return summary for the property') and enumerates the four exact output fields (total_project_cost, profit, resale_roi, max_recommended_renovation_budget). It explicitly separates itself from the sibling `renovation-return`, so an agent can pick between the two 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

A dedicated 'When to use it' section gives two concrete scenarios (underwriting flip candidates, sorting leads by projected ROI), and the 'Differs from renovation-return' line supplies the alternative-routing rule. It stops short of stating when not to use it (e.g., for rentals, where get_long_term_rental or get_short_term_rental apply), which keeps it below a 5.

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