Skip to main content
Glama
chrischall

homes-mcp

by chrischall

Project cumulative buy-vs-rent cost over N years

homes_estimate_rent_vs_buy
Read-onlyIdempotent

Project cumulative buy vs rent costs over N years, factoring down payment, mortgage, maintenance, appreciation, rent growth, and opportunity cost. Get year-by-year net position, break-even year, and net difference.

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

TableJSON 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.3
    • addedInput schema / properties / monthly_rent / exclusiveMinimum
      Added value: +0
    • removedInput schema / properties / monthly_rent / minimum
      Removed value: -0
  2. 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"
  3. First observedv1.1.1

TDQS

A4.5/5.0
Behavior5/5

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

The description adds substantial behavioral context beyond the readOnly and idempotent annotations: it is pure local math, P&I stops at loan term end, each year reflects the buyer's net position if sold, break-even independence from the horizon, and enumerated defaults (maintenance ~1%, appreciation ~3%, rent growth ~3%, investment return 6%, horizon 7y). This gives an agent an accurate mental model of the calculation and its outputs without contradiction.

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?

The description is dense and front-loaded with the core purpose, and every sentence delivers useful information. The NOTE about monthly_rent is well-placed. It is slightly long and runs as one block of text, which could be improved with bullet points or clearer paragraph breaks, but it remains efficient for the complexity of the tool.

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?

Given the tool's complexity (15 parameters, no output schema), the description is quite complete: it explains the model, defaults, return values, and a critical external dependency. Minor gaps remain—units for rates and exact handling of omitted parameters are not stated—but overall the agent can invoke this tool correctly after reading the description.

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?

With 0% schema coverage, the description carries the parameter-documentation burden. It names many parameters (down payment, closing costs, monthly PITI, maintenance, appreciation, rent growth, investment return) and supplies defaults. It also explicitly flags monthly_rent as required. However, it omits some parameters (hoa_monthly, selling_cost_rate, loan_term_years) and does not clarify whether rates are fractions or percentages.

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 description opens with a specific verb and resource: 'Project the cumulative cost of buying a home versus renting a comparable place over N years.' It precisely defines the tool's scope and adds model details, and the mention of 'Same math contract as zillow_estimate_rent_vs_buy' plus 'No network — pure local math' clearly separates it from calculator/compare siblings like homes_calculate_mortgage and homes_compare_properties.

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 description gives explicit usage context: it states a hard prerequisite ('caller must supply monthly_rent'), explains why (homes.com does not publish rental estimates), and routes the agent to alternative sources for that input. It does not explicitly state when not to use this tool versus other siblings, but the prerequisite callout provides clear guidance.

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