Skip to main content
Glama
homes-mcp

homes-mcp

by chrischall

Project cumulative buy-vs-rent cost over N years

homes_estimate_rent_vs_buy
Read-onlyIdempotent

Compare the total cost of buying a home versus renting over N years, factoring in PITI, maintenance, appreciation, and opportunity cost to find the break-even year.

Instructions

Project the cumulative cost of buying a home versus renting a comparable place over N years. Accounts for down payment, closing costs, monthly PITI, maintenance (~1%/yr default), appreciation (~3%/yr default), rent growth (~3%/yr default), and the opportunity cost of the down payment + closing costs (renter invests it at investment_return_rate, default 6%/yr). P&I stops once the loan term ends. Each year is the buyer's net position if they sold that year (cash out minus equity) versus the renter's net cost, so break-even year is independent of the horizon. Returns year-by-year cumulative net costs, break-even year, and the net difference at horizon (default horizon 7y). No network — pure local math. Same math contract as zillow_estimate_rent_vs_buy. NOTE: caller must supply monthly_rent — homes.com does not publish rental estimates anywhere on its consumer site (no rent_zestimate analogue, no comparable-rentals endpoint). For a rent estimate to plug in here, use zillow_get_property (its rent_zestimate field) or redfin_get_comparable_rentals.

Input Schema

NameRequiredDescriptionDefault
home_priceYes
hoa_monthlyNo
down_paymentYes
monthly_rentYes
horizon_yearsNo
interest_rateYes
loan_term_yearsNo
insurance_annualNo
maintenance_rateNo
rent_growth_rateNo
appreciation_rateNo
closing_cost_rateNo
property_tax_rateNo
selling_cost_rateNo
investment_return_rateNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.1.7
    • changedInput schema / properties / horizon_years / maximum
      Previous value: -9007199254740991New value: +100
    • changedInput schema / properties / loan_term_years / maximum
      Previous value: -9007199254740991New value: +50
  2. Changed2 schema fields changedv2.1.3
    • addedInput schema / properties / monthly_rent / exclusiveMinimum
      Added value: +0
    • removedInput schema / properties / monthly_rent / minimum
      Removed value: -0
  3. Changed1 schema field changedv2.0.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  4. First observedv1.1.1

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/no-network, yet the description adds substantial behavior: pure local math, the specific modeled cash flows, default rates for maintenance/appreciation/rent growth/investment return, that P&I stops at loan term end, and that break-even is horizon-independent. This is rich context beyond the structured fields.

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?

Long but dense, with the core purpose front-loaded before the detailed cost model. Nearly every sentence adds decision-relevant information; a few default-value restatements are slightly verbose but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-param, no-output-schema analytics tool, the description explains the return shape (year-by-year cumulative net costs, break-even year, net difference at horizon) and the key required input, which is the main gap for an agent. Remaining omissions are some undocumented optional params.

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 0% across 15 params, so the description carries the burden. It supplies defaults and meaning for several (maintenance ~1%/yr, appreciation ~3%/yr, rent growth ~3%/yr, investment_return_rate 6%, horizon 7y, down payment, closing costs), but leaves many undocumented (hoa_monthly, insurance_annual, property_tax_rate, selling_cost_rate, monthly_rent units). Partial compensation only.

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?

States a specific verb (project) and resource (cumulative buy-vs-rent cost over N years), and pins the scope with 'same math contract as zillow_estimate_rent_vs_buy'. An agent can distinguish it from homes_calculate_mortgage or homes_calculate_affordability without reading schemas.

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?

Explicitly names where to get the required monthly_rent (zillow_get_property's rent_zestimate, redfin_get_comparable_rentals), which is strong routing. However it doesn't state when this tool is preferred over sibling calculators or any exclusion conditions, so it stops short of full when/when-not guidance.

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