cashflow-mcp-server

Evaluate a contract

cashflow_evaluate_contract

Read-onlyIdempotent

Evaluate a contract's viability by generating a monthly cash flow schedule and computing IRR, NPV, payback, MOIC, ROI, working capital, break-even, and financing costs.

Instructions

Expand a contract into a month-by-month cash flow schedule and compute the metrics that follow from it: IRR, NPV, simple and discounted payback, MOIC, ROI, working capital, break-even volume, and the financing cost of any asset paid in installments.

Use this as the main entry point whenever someone asks whether a deal, contract, lease, managed-service agreement or equipment purchase is worth doing.

Args:

model (object): The contract. Call cashflow_model_template first if you are unsure how to shape it.
schedule_detail ('none' | 'annual' | 'monthly'): How much of the schedule to return. Default 'annual'. Ask for 'monthly' only when a specific month matters; a 60-month contract returns 61 rows.
response_format ('markdown' | 'json'): Default 'markdown'.

Returns: metrics (IRR, NPV, payback, MOIC, ROI, EBITDA), financing, workingCapital, breakeven, annual rollup, optional schedule, and warnings.

irrAnnual is null when the flows have no reportable IRR, with the reason in irrUnavailableReason. Treat null as "no IRR exists", never as zero. paybackMonth is null when the investment is never recovered within the term.

Examples:

Use when: "Is this 5-year service contract worth signing?"
Use when: "What is the IRR and payback on this equipment deal?"
Don't use when: comparing two or more variants (use cashflow_compare_contracts)
Don't use when: stress-testing assumptions (use cashflow_run_sensitivity)

Error handling: Returns a validation error naming the offending field if the model is malformed.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`model`	Yes
`response_format`	No	'markdown' for a readable report, 'json' for the full structured result. Structured data is returned either way in structuredContent.	markdown
`schedule_detail`	No	How much of the cash flow schedule to include. 'annual' rolls it up by contract year and is almost always enough. 'monthly' can be hundreds of rows, so ask for it only when a specific month is in question.	annual

Output Schema

TableJSON Schema

Name	Required	Description	Default
`annual`	Yes
`metrics`	Yes
`schedule`	No
`warnings`	Yes
`breakeven`	Yes
`financing`	Yes
`scheduleDetail`	Yes
`workingCapital`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 22, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't restate safety. It adds valuable behavioral nuance beyond annotations: null semantics for irrAnnual (with irrUnavailableReason) and paybackMonth, and error handling that names the offending field on malformed input. This transparency helps agents interpret results correctly and handle failures gracefully.

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 longer than a single sentence but well-structured with sections for purpose, args, examples, and error handling. Each section earns its place, and the core scoping statement is front-loaded. The length is justified by the tool's complexity, and there's no filler or repetition.

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 (nested model object, many fields), the description provides enough to call it correctly: it points to cashflow_model_template for shaping the model, explains null returns, and describes error handling. The output schema is present, so return details are covered elsewhere. It's comprehensive without being exhaustive.

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?

Schema coverage is 67%, so the description must add meaning beyond the schema. It does: for schedule_detail it warns that 'monthly' can return 61 rows for a 60-month contract and should only be requested when a specific month matters; for response_format it clarifies that structured data is always returned in structuredContent. It also advises calling cashflow_model_template when unsure how to shape the model. These add practical guidance over the schema's bare descriptions.

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: 'Expand a contract into a month-by-month cash flow schedule and compute the metrics that follow from it,' naming IRR, NPV, payback, MOIC, ROI, working capital, break-even, and financing cost. It then declares itself the 'main entry point' for evaluating deals, which clearly distinguishes it from siblings like cashflow_compare_contracts and cashflow_run_sensitivity. The purpose is unambiguous and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases ('Use when: Is this 5-year service contract worth signing?') and explicit non-use cases with alternatives ('Don't use when: comparing two or more variants (use cashflow_compare_contracts)'). This is exactly the when/when-not guidance agents need, with sibling tools named. Nothing is left to inference.

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

Deploy Server