cashflow-mcp-server

Installment plan terms

cashflow_loan_terms

Read-onlyIdempotent

Compute level monthly loan payments, total paid, and interest cost, with optional amortization schedule. Handles zero-rate plans and matches spreadsheet PMT(rate/12, nper, -pv).

Instructions

Compute the level monthly payment that amortizes a principal, plus the total paid and the interest it costs.

Matches the spreadsheet PMT(rate/12, nper, -pv) convention, including the zero-rate case, so the output can be checked against Excel cell by cell.

Note the rate convention: loans divide the annual rate by 12, they do not compound it. This tool divides. Discounting elsewhere in this server compounds. Mixing the two is the most common error in a hand-built model.

Args:

principal (number): Amount financed.
term_months (integer): Number of level payments. 0 means paid in cash.
annual_rate (number): Nominal annual rate, e.g. 0.12 for 12% APR. Use 0 for an interest-free plan.
include_amortization (boolean): Return the per-month interest and principal split. Default false.

Returns: monthlyPayment, totalPaid, interestPaid, and optionally an amortization schedule of { month, payment, interest, principal, balance }.

Examples:

Use when: "What is the payment on 3.5 million over 36 months at 12%?"
Use when: "How much interest does the 36-month plan cost versus 24 months interest-free?"

Input Schema

TableJSON Schema

Name	Required	Description
`principal`	Yes	Amount financed.
`annual_rate`	No	Nominal annual rate, divided by 12 per month. 0 is interest-free.
`term_months`	Yes	Number of level payments. 0 means paid in cash.
`include_amortization`	No	Return the per-month interest and principal split.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`totalPaid`	Yes
`monthlyRate`	Yes
`amortization`	No
`interestPaid`	Yes
`monthlyPayment`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 22, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare the tool read-only and idempotent. The description adds valuable behavioral detail beyond that: it matches spreadsheet PMT(rate/12, nper, -pv), handles the zero-rate case, and divides the annual rate by 12 rather than compounding it. This is exactly the kind of context that prevents incorrect invocation or misinterpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then the critical rate convention, then arguments, return values, and examples. Every sentence adds value: the PMT convention, the rate warning, and the examples are all substantive and non-redundant.

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?

Given the output schema exists and annotations cover safety, the description is complete: it explains what the tool computes, the important rate convention, the optional amortization output, and provides realistic usage examples. Nothing an agent needs to call this correctly is missing.

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 100%, and the Args section mostly restates the schema descriptions (principal, term_months, annual_rate, include_amortization). The global rate-convention warning is useful but not parameter-specific, so the description adds little meaning beyond what the schema already provides.

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?

Purpose is stated with a specific verb and resource: 'Compute the level monthly payment that amortizes a principal, plus the total paid and the interest it costs.' The reference to spreadsheet PMT and the rate-convention warning clearly distinguish it from sibling cash-flow tools that analyze flows, run sensitivity, or convert rates.

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 concrete 'Use when' examples and explicitly warns against mixing the loan rate division convention with compounding discounting used elsewhere in the server. This gives clear context for when the tool is appropriate, though it does not name sibling alternatives or provide an explicit when-not-to-use list.

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

Deploy Server