Mortgage Terms Comparison
compare_mortgage_termsRead-onlyIdempotent
Calculation, not advice. Verify with a professional before acting. Compare two fixed-rate mortgage options side-by-side: 15 vs 30 year, different rates, points vs no points, or any two terms. Shows total interest, monthly payment breakdown (with tax, insurance, PMI, HOA), equity buildup, and, critically, what happens if you take the cheaper mortgage and invest the monthly savings. Finds the break-even investment return rate. Includes tax deduction analysis (itemizing vs standard deduction), PMI auto-removal tracking per the Homeowners Protection Act, and after-tax net worth comparison. Note: ARM (adjustable-rate) mortgages are not yet supported.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| toolArguments | Yes | JSON object with these parameters: home_price: decimal > 0, <= 1,000,000,000 (REQUIRED) down_payment_pct: decimal 0-100 as percentage (optional, default 20) down_payment_amount: decimal >= 0 (optional; overrides down_payment_pct if provided) option_a (REQUIRED object): - label: string (optional; auto-generated if omitted) - annual_rate_pct: decimal 0-20 as percentage, e.g. 6.25 (REQUIRED) - term_years: int 1-40 (REQUIRED) - is_arm: bool (optional, default false; ARM not yet supported) - points: decimal 0-4 (optional, default 0; discount points bought, each = 1% of loan) - points_rate_reduction_pct: decimal 0-1.0, PERCENTAGE POINTS reduction per point (optional, default 0.25) option_b (REQUIRED object): - same shape as option_a - Must differ from option_a on at least one of: term_years, annual_rate_pct, or points property_tax_annual: decimal >= 0 (optional, default 0; for true monthly cost) home_insurance_annual: decimal >= 0 (optional, default 0) pmi_monthly: decimal >= 0, <= 1,000,000,000 (optional, default 0; PMI if < 20% down) pmi_removal_ltv_pct: decimal 50-100 (optional). When omitted, PMI is modeled as removed at the 78% HPA automatic-termination threshold. Provide a value (e.g. 80) to model borrower-requested removal at that LTV (whichever of 78% or your value is reached first). Either way PMI also stops at the statutory amortization midpoint of each option's own term (12 U.S.C. §4901(7), §4902(c)), which this value cannot postpone. hoa_monthly: decimal >= 0 (optional, default 0) invest_the_difference: bool (optional, default true). When true, both options deploy the same total budget every month: the higher option's P&I plus any extra_monthly_payment plus the month-1 PMI both carry. The cheaper-mortgage holder invests the payment gap each month; an option that stops paying PMI earlier invests the freed cash; the option with the lower upfront points cost invests the difference at month 0; after payoff the full budget goes to investments. See comparison_basis in the response. investment_return_pct: decimal 0-30 as percentage, an EFFECTIVE ANNUAL rate; the monthly compounding step is (1+pct/100)^(1/12)-1 (optional; defaults to the cited Senaro long-run S&P 500 nominal return, about 10%) tax_bracket_pct: decimal 0-50 as percentage (optional; enables after-tax investment return and mortgage interest deduction analysis; the after-tax comparison credits each option's annual deduction savings to its investments at year end) standard_deduction: decimal (optional. Defaults to the IRS basic standard deduction for tax_year + filing_status. TY2026: 16100 single, 32200 married, 24150 head_of_household. TY2025: 15750 single, 31500 married, 23625 head_of_household. Source: Rev. Proc. 2025-32) filing_status: 'single' | 'married' | 'head_of_household' (optional) tax_year: int, 2025 or 2026 (optional, default 2026; selects the IRS standard-deduction table for the itemize-vs-standard analysis) extra_monthly_payment: decimal >= 0, <= 1,000,000,000 (optional, default 0; extra principal applied equally to BOTH options) time_horizon_years: int 1-40 (optional; default: max of both term_years) full_schedule: bool (optional, default false; compact amortization by default) closing_cost_pct: decimal 0-20 as percentage of loan amount (optional, default: Urban Institute loan-size regressive schedule (~4.6% at $97K loan down to ~1.4% at $679K), points excluded. Pass 0 to model zero closing costs) |