Deterministic time-value-of-money and fund-performance tools for AI agents — future value, present value, CAGR, annuities, perpetuities, loan payments, payback, discounted payback, DPI, RVPI and TVPI via Model Context Protocol. Useful for corporate finance, financial projections, financial analysis, quantitative analysis, financial formulas and financial modeling.
Scored across 11 tools
Each tool maps to a distinct financial formula. The present value variants are clearly separated by single-amount vs annuity vs perpetuity, and DPI/RVPI/TVPI are distinguished by their realized vs unrealized components.
All 11 tools follow the exact same calculate_<metric> snake_case pattern with a consistent verb prefix and noun-like suffix, making the toolset highly predictable.
11 tools is well-scoped for a specialized financial/TVM calculator. Each tool earns its place and there is no redundant duplication.
The set covers many core TVM and fund-performance formulas, but notable standard calculations are missing: NPV, IRR, future value of an annuity, and annuity due/growing annuity variants. The payback tools also reference return analysis that is not implemented.
Calculate the present value of an ordinary annuity: a series of equal payments received (or paid) at the END of each period, discounted at a given rate. Formula: Annuity PV = PMT x (1 - (1 + r)^-n) / r. WHEN TO USE: Use to value a fixed stream of level payments (e.g. lease income, lottery-style payouts, bond coupons held to maturity, or a stream of loan repayments received). WHEN NOT TO USE: Do NOT use for payments at the START of each period (annuity due — adjust by multiplying by (1 + r)), for growing payments (growing annuity), or for perpetual streams (use calculate_perpetuity_value). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { annuity_present_value: number (currency), inputs }. PARAMETERS: payment (required): Payment amount per period, e.g. 50000. Must be > 0 for a normal inflow annuity. rate (required): Periodic discount rate as a decimal, e.g. 0.06 = 6% (never pass percentage points). Use rate = 0 for an undiscounted sum. periods (required): Number of payments/periods, e.g. 10. Must be >= 1.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Periodic discount rate as a decimal, e.g. 0.06 = 6% (never pass percentage points). Use rate = 0 for an undiscounted sum. | |
| payment | Yes | Payment amount per period, e.g. 50000. Must be > 0 for a normal inflow annuity. | |
| periods | Yes | Number of payments/periods, e.g. 10. Must be >= 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description goes further by stating 'pure deterministic calculation — no side effects, no network or storage access' and explicitly defining error behavior for division by zero or non-finite inputs. This adds meaningful context beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized with clear sections (definition, formula, when to use, when not to use, behavior, returns, parameters). Every sentence earns its place, and key usage constraints are front-loaded before the parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explicitly stating the return format (JSON object with annuity_present_value and inputs). All three parameters, their constraints, and edge cases are covered. The sibling context is addressed with clear exclusion criteria, making the tool self-contained for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying the rate=0 use case ('undiscounted sum'), reiterating that rate must be a decimal not percentage points, and documenting the return object shape with 'inputs'. These details go slightly beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Calculate the present value of an ordinary annuity') and precisely defines the payment timing ('END of each period'). It is clearly distinguishable from sibling tools like calculate_perpetuity_value, and the formula removes any ambiguity about the calculation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete examples (lease income, lottery-style payouts, bond coupons). It names alternatives (annuity due adjustment, growing annuity, calculate_perpetuity_value) and leaves no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the Compound Annual Growth Rate (CAGR): the smoothed annual growth rate that takes a beginning value to an ending value over a given number of years. Formula: CAGR = (End Value / Begin Value)^(1/n) - 1. WHEN TO USE: Use to state multi-year growth as a single comparable annualised rate (revenue growth, asset growth, fund performance) — the standard "growth per year" figure. WHEN NOT TO USE: Do NOT use when the beginning value is zero or negative (undefined), or when you need period-by-period volatility rather than a smoothed rate. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { cagr: decimal (e.g. 0.201 = 20.1%), cagr_pct: number (e.g. 20.1), inputs }. PARAMETERS: begin_value (required): Value at the START of the period, e.g. 100000. Must be > 0. end_value (required): Value at the END of the period, e.g. 250000. Must be > 0. periods (required): Number of years between the two values, e.g. 5. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| periods | Yes | Number of years between the two values, e.g. 5. Must be > 0. | |
| end_value | Yes | Value at the END of the period, e.g. 250000. Must be > 0. | |
| begin_value | Yes | Value at the START of the period, e.g. 100000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description goes beyond these by adding a dedicated BEHAVIOUR section: pure deterministic calculation, no side effects, no network/storage access, identical inputs produce identical outputs, and explicit error handling for division by zero or non-finite inputs. This is rich, non-redundant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (formula, when to use, when not to use, behaviour, returns, parameters), making it scannable and front-loaded with the core purpose. It is somewhat long due to repeating parameter details already present in the schema, but every section otherwise serves a distinct purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description specifies the exact JSON return shape with examples, the formula, input constraints, error behavior, and ideal use cases. An agent has everything needed to invoke the tool correctly and interpret the result accurately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions and exclusiveMinimum for all three parameters. The description's PARAMETERS section largely repeats the schema text, adding no new semantic meaning beyond the structured definitions. Baseline 3 applies because the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Calculate the Compound Annual Growth Rate'), includes the formula, and defines the metric as a smoothed annual growth rate. This clearly distinguishes it from sibling financial calculators such as calculate_future_value or calculate_present_value, making selection unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete examples (revenue growth, asset growth, fund performance) and clear exclusions (zero/negative beginning value, need for period-by-period volatility). This gives an agent direct decision criteria for when to invoke this tool versus not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the discounted payback period: how many years until the DISCOUNTED cumulative cash flows recover the initial investment, incorporating the time value of money. Formula: Discounted payback = the year t where cumulative discounted cash flow turns positive. WHEN TO USE: Use when you want a payback-style risk screen that still respects the cost of capital — a project can pay back nominally but never on a discounted basis. WHEN NOT TO USE: Do NOT use for the final go/no-go decision (it still ignores flows after payback); use calculate_payback_period for the nominal (undiscounted) recovery view and combine with profitability and return analysis for the full decision. BEHAVIOUR: If discounted cumulative cash flow never turns positive, an explicit error is returned rather than a number. RETURNS: JSON object { discounted_payback_period_years: number (e.g. 4.2), inputs }. If the discounted flows never recover the investment, returns an explicit error stating no payback occurs. PARAMETERS: cash_flows (required): Ordered cash flows starting at time 0 (first element is the initial investment, typically negative), e.g. [-250000, 50000, 75000, 100000, 125000]. The time-0 flow is not discounted. rate (required): Discount rate as a decimal, e.g. 0.10 = 10% (never pass percentage points). Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Discount rate as a decimal, e.g. 0.10 = 10% (never pass percentage points). Must be >= 0. | |
| cash_flows | Yes | Ordered cash flows starting at time 0 (first element is the initial investment, typically negative), e.g. [-250000, 50000, 75000, 100000, 125000]. The time-0 flow is not discounted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior, and the description adds substantial detail beyond that: it discloses the explicit error condition when cumulative discounted cash flows never recover, and describes the exact return shape. This gives the agent useful behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (purpose, formula, when to use, behavior, returns, parameters). Despite being detailed, every section adds necessary information and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's behavior, return value, error condition, and parameter semantics. Since there is no output schema, it appropriately explains the JSON result shape and provides a concrete example, leaving no critical gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter details from the schema rather than adding new semantic information, though the examples and the warning about passing decimal rather than percentage points are helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Calculate') and resource ('discounted payback period'), clearly defining the concept and formula. It explicitly distinguishes itself from the nominal payback calculation, making it easy to differentiate from calculate_payback_period.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains dedicated WHEN TO USE and WHEN NOT TO USE sections. It specifies appropriate use as a payback-style risk screen and explicitly warns against using it for final go/no-go decisions, naming calculate_payback_period as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Distributions to Paid-In capital (DPI): cumulative distributions returned to investors divided by paid-in capital — the realised multiple of a fund or investment. Formula: DPI = Total Distributions / Paid-In Capital. WHEN TO USE: Use for private equity / venture fund reporting to show how much cash investors have actually received back relative to what they put in. WHEN NOT TO USE: Do NOT use to measure total performance — DPI ignores unrealised residual value (pair with RVPI; TVPI = DPI + RVPI captures both). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { dpi: number (e.g. 0.8 = 0.8x of paid-in returned as cash), inputs }. PARAMETERS: distributions (required): Cumulative distributions returned to investors, e.g. 800000. Must be >= 0. paid_in (required): Paid-in capital contributed by investors, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| paid_in | Yes | Paid-in capital contributed by investors, e.g. 1000000. Must be > 0. | |
| distributions | Yes | Cumulative distributions returned to investors, e.g. 800000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses that this is a pure deterministic calculation, has no side effects, accesses no network or storage, and returns explicit errors for division by zero or non-finite inputs. This gives the agent a complete safety and failure-mode picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for formula, usage, non-usage, behavior, returns, and parameters. Every sentence is intentional, and the key formula and usage guidance are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately specifies the JSON return shape including the dpi value and inputs. It also covers error behavior, parameter constraints, and relationships to sibling metrics, so nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters and their constraints. The description mainly restates the same information with examples, adding little semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the metric (DPI), gives the formula, and frames it as the realised multiple returned to investors. It explicitly differentiates DPI from RVPI and TVPI, which are sibling tools, so an agent can pick the correct one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The WHEN TO USE section specifies private equity/venture fund reporting, and WHEN NOT TO USE states that DPI should not be used for total performance because it ignores unrealised value. It also names RVPI and TVPI as the complementary alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the future value of a single lump sum: what a present amount grows to at a given rate over a given number of periods, with compounding. Formula: FV = PV x (1 + r)^n. WHEN TO USE: Use to project what an investment or cash balance will be worth at a future date under compound growth (e.g. an invested lump sum, or a liability growing at a stated rate). WHEN NOT TO USE: Do NOT use for a series of multiple, uneven cash flows — this tool compounds a single present amount. For level periodic payment streams use the annuity tool, or when you need the required starting amount (use calculate_present_value). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { future_value: number (currency), inputs }. PARAMETERS: present_value (required): Starting amount in currency units, e.g. 100000. May be negative for a liability. rate (required): Periodic rate as a decimal, e.g. 0.08 = 8% per period (never pass percentage points). Rate and periods must share frequency (annual/annual or monthly/monthly). periods (required): Number of compounding periods, e.g. 5. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Periodic rate as a decimal, e.g. 0.08 = 8% per period (never pass percentage points). Rate and periods must share frequency (annual/annual or monthly/monthly). | |
| periods | Yes | Number of compounding periods, e.g. 5. Must be >= 0. | |
| present_value | Yes | Starting amount in currency units, e.g. 100000. May be negative for a liability. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that it is a pure deterministic calculation with no side effects, network, or storage access, and that invalid inputs return explicit errors. No contradiction with annotations; it reinforces them with concrete detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than strictly necessary because the PARAMETERS section largely duplicates the input schema. However, it is well-structured with labeled sections, front-loads the core definition and formula, and the added length is purposeful for avoiding rate-unit mistakes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter deterministic calculation with no output schema, the description is complete: it states the return shape ({ future_value, inputs }), covers edge cases (division by zero, non-finite inputs, undefined combinations), and specifies parameter constraints. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description repeats much of the schema's parameter documentation, but it adds the formula, which clarifies the algebraic relationship among present_value, rate, and periods, and gives worked examples for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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—'Calculate the future value of a single lump sum'—and includes the formula FV = PV x (1 + r)^n. It also distinguishes itself from sibling tools by explicitly saying it compounds a single present amount, not a cash-flow series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Dedicated WHEN TO USE and WHEN NOT TO USE sections give explicit conditions, including excluded use cases (multiple uneven cash flows) and the correct alternatives (annuity tool, calculate_present_value). It also specifies the rate/period frequency matching requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the level periodic payment (PMT) that fully amortises a loan: the constant payment per period covering principal and interest over the loan term. Formula: PMT = P x [r(1 + r)^n] / [(1 + r)^n - 1]. WHEN TO USE: Use to size loan/mortgage payments, check affordability, or reverse-engineer what a borrower can service — given principal, periodic rate and number of periods. WHEN NOT TO USE: Do NOT use for interest-only facilities, balloon structures with uneven payments, or when you need the total interest paid rather than the payment itself. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { loan_payment: number (currency per period), inputs }. PARAMETERS: principal (required): Loan principal amount, e.g. 500000. Must be > 0. rate (required): Periodic interest rate as a decimal, e.g. 0.005 = 0.5% monthly for a 6% annual rate (never pass percentage points). Must match period frequency. periods (required): Total number of payments, e.g. 60 for a 5-year monthly loan. Must be >= 1.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Periodic interest rate as a decimal, e.g. 0.005 = 0.5% monthly for a 6% annual rate (never pass percentage points). Must match period frequency. | |
| periods | Yes | Total number of payments, e.g. 60 for a 5-year monthly loan. Must be >= 1. | |
| principal | Yes | Loan principal amount, e.g. 500000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: pure deterministic calculation, no side effects, no network or storage access, idempotent and non-destructive behavior, and explicit error returns for invalid mathematical inputs. This is consistent with the readOnlyHint, idempotentHint, and destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but well organized with clear labeled sections: formula, when to use, when not to use, behavior, returns, and parameters. Critical information is front-loaded, and every section serves a distinct purpose for correct tool invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description appropriately defines the return shape as a JSON object with loan_payment and inputs. It also covers the formula, parameter constraints, edge-case error behavior, and exclusions. Nothing material is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with constraints and examples, so the baseline is strong. The description adds extra value through the formula, the warning about passing decimal rates rather than percentage points, and the relationship between periods and loan term.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: calculating the level periodic payment (PMT) that fully amortises a loan. It includes the formula, clarifies the payment covers principal and interest, and is clearly distinguishable from the other finance calculator siblings by its fully-amortising loan focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes both WHEN TO USE and WHEN NOT TO USE sections. It specifies appropriate use cases like mortgage sizing and affordability checks, and explicitly excludes interest-only facilities, balloon structures, and requests for total interest paid. This gives an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the payback period: how many years (including a fractional final year) until cumulative cash flows recover the initial investment, ignoring the time value of money. Formula: Payback = the year t where cumulative cash flow turns positive. WHEN TO USE: Use as a quick liquidity/risk screen — shorter payback means capital is at risk for less time. Use it only as a screening input, never as the sole investment criterion. WHEN NOT TO USE: Do NOT use as the primary decision metric — it ignores cash flows after payback, profitability, and the time value of money (use calculate_discounted_payback_period when you need a time-value-adjusted recovery measure). BEHAVIOUR: If cumulative cash flow never turns positive, an explicit error is returned ("investment is never recovered within the provided cash flows") rather than a number. RETURNS: JSON object { payback_period_years: number (e.g. 3.4), inputs }. If the cash flows never recover the investment, returns an explicit error stating no payback occurs. PARAMETERS: cash_flows (required): Ordered cash flows starting at time 0 (first element is the initial investment, typically negative), e.g. [-250000, 50000, 75000, 100000, 125000]. Must contain at least one negative (investment) followed by inflows.
| Name | Required | Description | Default |
|---|---|---|---|
| cash_flows | Yes | Ordered cash flows starting at time 0 (first element is the initial investment, typically negative), e.g. [-250000, 50000, 75000, 100000, 125000]. Must contain at least one negative (investment) followed by inflows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with those. It adds substantial behavioral detail beyond them: the exact error behavior when cumulative cash flows never turn positive, the return format (JSON object with payback_period_years and inputs), and the fact that TVM is intentionally ignored.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections (WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and front-loaded with the core definition. However, the no-recovery error case is stated twice (in BEHAVIOUR and again in RETURNS), and the formula sentence partially overlaps with the opening definition, making it slightly redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and no output schema, the description fully compensates: it documents the exact input format, the edge case of non-recovery, the return object shape, and the intended use context. Nothing an agent needs to correctly invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema description already documents the cash_flows array, the time-0 convention, the example array, and the requirement of a negative investment followed by inflows. The description's PARAMETERS section repeats this rather than adding new meaning, so it provides no additional value beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Calculate the payback period' with the precise condition under which it is computed (until cumulative cash flows recover the initial investment, ignoring time value of money). It explicitly names the alternative sibling calculate_discounted_payback_period, making it unambiguous which tool is which.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description has dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections, clearly framing the tool as a screening input rather than a sole decision metric and directing users to calculate_discounted_payback_period when time-value adjustment is needed. This provides explicit exclusions and alternatives, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the present value of a perpetuity: a constant (or constant-growth) cash flow received forever, discounted at a required rate. Formula: Perpetuity PV = CF / r; Growing perpetuity PV = CF / (r - g). WHEN TO USE: Use to value perpetual streams such as preferred dividends, ground rents, endowment-style income, or the terminal-value leg of a discounted-cash-flow valuation (Gordon Growth Model). WHEN NOT TO USE: Do NOT use for finite cash-flow streams (use calculate_annuity_present_value), and do NOT set growth_rate >= rate — the formula is undefined there (it implies an infinite value). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { perpetuity_value: number (currency), inputs }. PARAMETERS: cash_flow (required): Periodic cash flow received forever, e.g. 30000. Must be > 0 for a normal perpetuity. rate (required): Required return / discount rate as a decimal, e.g. 0.08 = 8% (never pass percentage points). Must be strictly greater than growth_rate. growth_rate (optional): OPTIONAL perpetual growth rate of the cash flow as a decimal, e.g. 0.03 = 3% (never pass percentage points). Defaults to 0 (no growth). Must be strictly less than rate.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Required return / discount rate as a decimal, e.g. 0.08 = 8% (never pass percentage points). Must be strictly greater than growth_rate. | |
| cash_flow | Yes | Periodic cash flow received forever, e.g. 30000. Must be > 0 for a normal perpetuity. | |
| growth_rate | No | OPTIONAL perpetual growth rate of the cash flow as a decimal, e.g. 0.03 = 3% (never pass percentage points). Defaults to 0 (no growth). Must be strictly less than rate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explaining the tool is a pure deterministic calculation with no side effects, no network/storage access, and idempotent behavior. It also discloses error behavior for division by zero, non-finite inputs, and undefined combinations, which is critical for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but front-loaded with the core formula and use cases, then organizes behavior, returns, and parameters into labeled sections. Minor redundancy exists because the parameter details largely repeat the input schema, but the explicit parameter warnings are worth having inline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description documents the return shape as a JSON object with perpetuity_value and inputs, covers all three parameters with constraints and defaults, includes formulas, and specifies error handling. For this tool's complexity, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds valuable semantic depth: it gives worked examples (30000, 0.08, 0.03), stresses using decimals rather than percentage points, and clarifies the growth_rate default and the required relationship between rate and growth_rate. This lifts it above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates the present value of a perpetuity, specifying both constant and growing variants with explicit formulas. It also distinguishes itself from related tools by naming calculate_annuity_present_value as the alternative for finite streams and by mentioning Gordon Growth Model usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit WHEN TO USE guidance with concrete examples (preferred dividends, ground rents, terminal value) and WHEN NOT TO USE with a named sibling tool. It also warns against the undefined mathematical case where growth_rate >= rate, giving clear operational boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the present value of a single future amount: what a future lump sum is worth today discounted at a given rate over a given number of periods. Formula: PV = FV / (1 + r)^n. WHEN TO USE: Use to discount a single known future cash flow back to today (e.g. a future exit value, a balloon payment, or a single future receipt). WHEN NOT TO USE: Do NOT use for multiple cash-flow streams (use calculate_payback_period or calculate_discounted_payback_period for series recovery) or for perpetual/annuity streams (use the perpetuity or annuity tools). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { present_value: number (currency), inputs }. PARAMETERS: future_value (required): Future amount in currency units, e.g. 250000. May be negative for a future payment. rate (required): Discount rate as a decimal, e.g. 0.10 = 10% per period (never pass percentage points). Rate and periods must share frequency. periods (required): Number of discounting periods, e.g. 5. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Discount rate as a decimal, e.g. 0.10 = 10% per period (never pass percentage points). Rate and periods must share frequency. | |
| periods | Yes | Number of discounting periods, e.g. 5. Must be >= 0. | |
| future_value | Yes | Future amount in currency units, e.g. 250000. May be negative for a future payment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds concrete behavioral guarantees: 'pure deterministic calculation', 'no side effects, no network or storage access', and 'identical inputs always produce identical outputs'. It also discloses error behavior for division by zero, non-finite inputs, and undefined mathematical combinations, which is genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (WHEN TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and front-loads the core definition and formula. The PARAMETERS section is somewhat redundant with the schema's property descriptions, which adds length without adding information, but the overall organization remains clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stateless calculation tool with three primitive required parameters and no output schema, the description is complete: it covers the formula, input units and frequency matching, exclusions, deterministic behavior, error cases, and the expected return JSON shape. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter guidance in the description is nearly verbatim from the schema (e.g. 'Discount rate as a decimal, e.g. 0.10...', 'Must be >= 0', 'May be negative for a future payment'). The description adds no meaning beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Calculate the present value of a single future amount') and reinforces it with the explicit formula PV = FV / (1 + r)^n. It clearly scopes the tool to a single lump sum, which distinguishes it from sibling tools handling multiple cash-flow streams, annuities, and perpetuities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit WHEN TO USE and WHEN NOT TO USE sections. It names the alternatives directly (calculate_payback_period and calculate_discounted_payback_period for series recovery; perpetuity/annuity tools for streams), leaving no ambiguity about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Residual Value to Paid-In capital (RVPI): the current (unrealised) value of remaining assets divided by paid-in capital. Formula: RVPI = Residual Value / Paid-In Capital. WHEN TO USE: Use for fund reporting to show the unrealised multiple still held in the portfolio (mark-to-market or fair value of remaining investments). WHEN NOT TO USE: Do NOT use alone as a performance measure — residual value is an estimate, not cash (combine with DPI for the full TVPI picture). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { rvpi: number (e.g. 1.2 = 1.2x of paid-in still held), inputs }. PARAMETERS: residual_value (required): Current fair value of remaining (unrealised) investments, e.g. 1200000. Must be >= 0. paid_in (required): Paid-in capital contributed by investors, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| paid_in | Yes | Paid-in capital contributed by investors, e.g. 1000000. Must be > 0. | |
| residual_value | Yes | Current fair value of remaining (unrealised) investments, e.g. 1200000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by describing pure deterministic behavior, no side effects, no network/storage access, idempotence, and error handling for division by zero or non-finite inputs. The description does not contradict the readOnlyHint, idempotentHint, or destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear labeled sections, front-loads the formula, and every sentence earns its place. It is detailed without being verbose or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter calculator with no output schema, the description provides the return shape, examples, parameter constraints, error behavior, and usage context. Nothing essential is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds a small but meaningful layer: the formula relationship between the parameters, numeric interpretation (1.2 = 1.2x of paid-in still held), and concrete examples in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States exactly what the tool calculates with a definition and formula: RVPI = Residual Value / Paid-In Capital. It clearly names the resource and calculation, and the DPI/TVPI references help distinguish it from sibling calculators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit WHEN TO USE and WHEN NOT TO USE sections give direct guidance: use for fund reporting of unrealised multiple, but not alone as a performance measure, and combine with DPI for TVPI. This actively routes the agent to correct vs incorrect usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Total Value to Paid-In capital (TVPI): (distributions + residual value) divided by paid-in capital — the total multiple of a fund or investment including both realised and unrealised value. Formula: TVPI = (Distributions + Residual Value) / Paid-In Capital. WHEN TO USE: Use as the headline multiple for private equity / venture fund performance (equivalent to DPI + RVPI). WHEN NOT TO USE: Do NOT use TVPI to compare funds of different vintages/ages — it ignores the time value of money; combine it with a time-adjusted return analysis for cross-vintage comparison. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { tvpi: number (e.g. 2.0 = 2.0x total value on paid-in), inputs }. PARAMETERS: distributions (required): Cumulative distributions returned to investors, e.g. 800000. Must be >= 0. residual_value (required): Current fair value of remaining investments, e.g. 1200000. Must be >= 0. paid_in (required): Paid-in capital, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| paid_in | Yes | Paid-in capital, e.g. 1000000. Must be > 0. | |
| distributions | Yes | Cumulative distributions returned to investors, e.g. 800000. Must be >= 0. | |
| residual_value | Yes | Current fair value of remaining investments, e.g. 1200000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description reinforces and extends these by stating 'pure deterministic calculation — no side effects, no network or storage access' and additionally discloses error behavior ('Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error'), which structured annotations cannot convey. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Though longer than typical, every section (formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) is clearly labeled and earns its place. The core definition and formula are front-loaded, and no sentence is redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description fully compensates by specifying the return shape ('JSON object { tvpi: number (e.g. 2.0 = 2.0x total value on paid-in), inputs }') along with the formula, use/non-use cases, side-effect-free behavior, error handling, and per-parameter constraints. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — all three parameters carry descriptions, examples, and constraints (paid_in > 0, distributions and residual_value >= 0). The description's PARAMETERS section largely restates the schema rather than adding new semantic meaning, so the high-coverage baseline of 3 applies. The formula does clarify how parameters combine, but that is formula context, not new per-parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Calculate Total Value to Paid-In capital (TVPI)') plus the complete formula. The 'equivalent to DPI + RVPI' note and the label 'headline multiple for private equity / venture fund performance' clearly distinguish it from sibling calculation tools like calculate_dpi and calculate_rvpi without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains explicit WHEN TO USE and WHEN NOT TO USE sections: use as the headline PE/VC performance multiple, but do not use for cross-vintage comparison because 'it ignores the time value of money.' It also names a complement ('time-adjusted return analysis') for the exclusion case, giving an agent actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
calculate_annuity_present_valuecalculate_cagrcalculate_discounted_payback_periodcalculate_dpicalculate_future_valuecalculate_loan_paymentcalculate_payback_periodcalculate_perpetuity_valuecalculate_present_valuecalculate_rvpicalculate_tvpiDeterministic company valuation and corporate finance tools for AI agents — IRR, NPV, MOIC, DCF, WACC, enterprise value, EV multiples, CAPM, beta and sensitivity analysis via Model Context Protocol. Useful for financial analysis, equity analysis, quantitative analysis, financial projections, financial formulas and financial modeling.
Deterministic finance tools for AI agents — IRR, NPV, MOIC, DCF, WACC and sensitivity.
Deterministic profitability and market-value analysis tools for AI agents — margins, ROA, ROE, ROCE, ROIC, EPS, P/E, P/B, dividend yield and payout ratio via Model Context Protocol. Useful for corporate finance, equity analysis, financial analysis, quantitative analysis, financial formulas and financial modeling.
Deterministic liquidity and leverage ratio tools for AI agents — current, quick and cash ratios, defensive interval, debt-to-equity, debt-to-assets, equity multiplier and interest coverage via Model Context Protocol. Useful for corporate finance, credit analysis, financial analysis, financial formulas and financial modeling.
Add one secure layer between your agents and this server.