US MortgageCalculator

How AI agents calculate mortgages

A language model asked for a mortgage payment will usually produce a number. It is usually close, frequently wrong in the same three ways, and never auditable. This is what goes wrong, and what to do instead.

The problem is not the arithmetic

Models are better at the amortization formula than people expect. That is not where the error is.

Given a principal, a rate and a term, a capable model will apply the standard formula and land within a few dollars. The failure is upstream of the arithmetic: it answers the question it was asked rather than the question that was meant.

Without a tool
User: What's the monthly payment on a $400,000 house in New Jersey
      with 10% down at 6.5%?

Model (no tools): About $2,275 a month.

That $2,275 is a defensible answer to “what is the principal and interest payment”. It is not what anybody asking about a house wants to know. The real cost of that purchase is around $3,435 — half as much again — because New Jersey has the highest property tax rate in the country and a 10% down payment means mortgage insurance.

With a tool
User: What's the monthly payment on a $400,000 house in New Jersey
      with 10% down at 6.5%?

Model (calls calculate_mortgage) → $3,435.44 a month:
  principal & interest   $2,275.44
  property tax             $830.00   (2.49% NJ average)
  homeowners insurance     $150.00
  mortgage insurance       $180.00   (PMI, 10% down)
  HOA                        $0.00

The three failures, specifically

Property tax gets a national average, or nothing

Effective rates run from 0.28% in Hawaii to 2.49% in New Jersey — a spread of nearly nine to one. A model that applies “about 1%” is wrong by hundreds of dollars a month at either end, and it will not tell you it guessed.

Mortgage insurance disappears

Below 20% down, conventional loans carry PMI, FHA loans carry MIP that usually never cancels, and USDA carries an annual fee. Each is priced differently and each ends differently. Models routinely omit all of it, which understates the payment exactly when the borrower can least afford the surprise.

Figures are stated with confidence and no provenance

A number in prose cannot be checked. Was the rate current? Which year's FHA limits? Was PMI included? The answer reads identically whether it was computed carefully or approximated, and that is the part that makes it unsafe to act on.

What a calculation tool fixes

Not accuracy alone — auditability.

A tool call is a record. The arguments are visible, the response is structured, and both can be logged and replayed. When an agent tells someone their payment is $3,435, you can point at the call that produced it and at the assumptions it applied. That is the difference between a figure a person can act on and a figure that merely sounds right.

The call behind the answer
{
  "name": "calculate_mortgage",
  "arguments": {
    "homePrice": 400000,
    "downPaymentPercent": 10,
    "annualInterestRatePercent": 6.5,
    "loanTermYears": 30,
    "state": "New Jersey"
  }
}

Every response from this API carries the assumptions used alongside the result — the tax rate applied and which state it came from, how mortgage insurance was priced, what remains unmodelled. An agent that surfaces those turns a bare number into something a reader can challenge.

Connecting one

11 operations over MCP, or the same set as plain HTTP.

The fastest route is MCP: point a compatible client at https://www.usmortgagecalc.com/mcp and the calculators become tools with no further work. Configuration for Claude, Cursor and VS Code is two lines each. For frameworks that take OpenAI-style function definitions, the OpenAPI document can generate all 11 definitions at once.

There is no key, no account and no rate limit, and nothing about a request is stored — which matters more than usual here, because the inputs to a mortgage calculation are somebody's income and savings.

Designing the prompt around the tool

Three things worth putting in a system prompt.

  • Ask for the state. A mortgage question without a location is unanswerable to within several hundred dollars a month. Have the agent ask rather than assume.
  • Report the total, then the breakdown. People ask for “the payment” and mean the whole thing. Leading with principal and interest is technically responsive and practically misleading.
  • Pass the caveats through. Every response includes notes on what was assumed. An agent that drops them has converted a careful estimate into a bare claim.

Why the numbers here are reproducible

The engine has no access to a clock, a locale or a filesystem — those are not discouraged, they do not typecheck. Given the same arguments it returns the same result on any runtime and on any day, which is what makes a logged tool call worth logging. An amortization schedule comes back as month offsets rather than dates for the same reason: the engine does not know what today is, and a calculation that depends on when it ran cannot be replayed.

The same package runs the website, the REST API and the MCP server. An agent's answer and the page a person reads agree because they are the same computation, not because someone kept two implementations in step.