Deterministic time-value and fund-performance tools — FV/PV, CAGR, annuities, perpetuities, loan payments, payback, DPI/RVPI/TVPI.
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_npv for value creation and calculate_irr for return. 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?
The annotations already signal readOnlyHint=true and idempotentHint=true, so the description's job is to add behavioral detail. It does this well by explaining that an explicit error is returned when discounted cash flows never recover the investment, and by clarifying that the time-0 flow is not discounted. No contradiction with annotations exists.
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 section labels and front-loads the definition and formula. It is somewhat repetitive around the no-payback error case, appearing under both BEHAVIOUR and RETURNS, but overall each section earns its place and the length is justified for a financial calculation with specific input conventions.
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 the two-parameter schema, no output schema, and read-only annotations, the description is complete. It covers the formula, parameter formats, edge-case behavior, return shape, and explicit guidance about when not to use the tool. An agent has everything needed to 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?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description repeats the schema guidance about decimal rates and ordered cash flows, and adds a worked example, but it does not introduce meaningfully new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.
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 tool's purpose: calculating the discounted payback period using the time value of money. It distinguishes this from the sibling tool calculate_payback_period by explicitly highlighting the difference between nominal and discounted payback, and names calculate_npv and calculate_irr as alternatives for different decisions.
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 provides explicit WHEN TO USE and WHEN NOT TO USE sections, including the exact conditions under which to choose this tool over calculate_payback_period, calculate_npv, and calculate_irr. This gives an agent clear decision criteria for tool selection.
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 series of multiple cash flows (use calculate_npv or an 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the BEHAVIOUR section adds meaningful detail beyond them: pure deterministic calculation, no side effects, no network/storage access, identical inputs produce identical outputs, and explicit errors for undefined mathematical cases. This is valuable operational context that annotations alone do not capture.
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 uses clear labeled sections (WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and every sentence adds essential information. It is longer than typical tool descriptions, but the length is justified by the need to cover usage boundaries, formula, error behavior, and parameter semantics for a math tool.
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 RETURNS section correctly specifies the JSON shape including the future_value field and inputs echo. The description covers the full calling contract: formula, parameter semantics, edge cases, error behavior, and sibling routing, so an agent has everything needed to invoke the 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?
While schema coverage is 100%, the description enriches all three parameters with practical examples: present_value may be negative for a liability, rate must be a decimal not percentage points, and rate must share frequency with periods. These nuances are partly in the schema but are reinforced and contextualized in the description.
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 names a precise verb and resource — calculating future value of a single lump sum with compounding — and backs it with the explicit formula FV = PV x (1 + r)^n. It explicitly contrasts itself with related siblings like calculate_present_value, calculate_npv, and annuity tools, so an agent can distinguish it without opening 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?
The WHEN TO USE section gives concrete scenarios: projecting investments, cash balances, or liabilities under compound growth. The WHEN NOT TO USE section names specific alternatives (calculate_npv, annuity tools, calculate_present_value) and the conditions that should route to them, making selection unambiguous.
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. Useful alongside NPV/IRR, 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_npv or calculate_irr for those). 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?
Although annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: it returns an explicit error if the investment is never recovered, discloses that cash flows after payback are ignored, and describes the return shape. This goes well beyond the annotations and helps the agent predict edge-case behavior.
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, behavior, returns, parameters), which makes it scannable. It is somewhat verbose and repeats the explicit-error behavior in both BEHAVIOUR and RETURNS, but every section adds useful routing or behavioral information.
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?
There is no output schema, so the description appropriately documents the return format as a JSON object with payback_period_years and inputs, plus the error case. It also covers the input format, constraints, formula, and decision-usability caveats. Nothing critical 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?
Schema description coverage is 100%, so the schema already documents the cash_flows parameter. The description does add a clarifying example and reiterates the format and constraints, but mostly repeats what the schema states. This matches the baseline of 3 for high schema coverage.
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 payback period' and defines exactly what it measures, including the fractional final year and the cumulative cash-flow recovery rule. It also distinguishes itself from time-value-aware tools by explicitly stating that it 'ignores the time value of money.' The formula and example further anchor what the tool does.
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. It positions the tool as a liquidity/risk screen, warns against using it as the sole investment criterion, and names calculate_npv and calculate_irr as alternatives for profitability and time-value considerations. 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 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 component of a DCF (Gordon Growth Model). WHEN NOT TO USE: Do NOT use for finite cash-flow streams (use calculate_annuity_present_value or calculate_npv), 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description does not contradict them. It adds value beyond annotations by explicitly stating no side effects, no network/storage access, deterministic identical outputs, and detailed error behavior for division by zero or invalid inputs. It slightly repeats annotation content but still contributes meaningful operational 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?
Although lengthy, the description is tightly organized with labeled sections: formula, when to use, when not to use, behaviour, returns, and parameters. Each sentence carries load-bearing information, and the most critical constraints are front-loaded. There is no filler or repetition beyond what aids clarity.
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?
There is no output schema, but the description explicitly states the return shape as a JSON object with perpetuity_value and inputs. All three parameters are fully documented with defaults, constraints, and examples. The tool is a pure calculation, so the description covers everything an agent needs 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?
Schema coverage is 100%, so the schema already documents all parameters clearly. The description still adds useful nuance: it gives concrete value examples, clarifies the decimal-versus-percentage requirement in plain language, states the default for growth_rate, and reinforces the required relationship between rate and growth_rate. This goes beyond a bare schema dump.
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 a perpetuity.' It precisely defines the object as a constant or constant-growth cash flow received forever, and provides both formulas. This is clearly distinguishable from sibling tools like calculate_annuity_present_value because it anchors on the perpetual, infinite-horizon nature of the cash flow.
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 is exemplary: it has an explicit 'WHEN TO USE' section listing perpetual income contexts, and a 'WHEN NOT TO USE' section naming calculate_annuity_present_value and calculate_npv for finite cash-flow streams. It also warns specifically against setting growth_rate >= rate, which is a critical mathematical precondition. 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.
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_npv) 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?
Annotations already mark the tool as readOnly and idempotent, and the description adds valuable detail beyond that: pure deterministic calculation, no side effects or network/storage access, and explicit error behavior for division by zero, non-finite inputs, and undefined combinations. This enriches the agent's understanding of what will happen at runtime.
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 labeled sections and front-loaded purpose. However, the PARAMETERS section duplicates the schema's property descriptions nearly verbatim, adding length without introducing new information. Overall it is organized and each section has a clear role.
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?
There is no output schema, so the RETURNS section appropriately describes the response shape (present_value and inputs). The description also covers error behavior, period/rate frequency alignment, and all required parameters. Nothing critical 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?
Schema coverage is 100% — the input schema already documents all three parameters with the same examples and constraints. The description repeats the parameter information rather than adding meaning beyond the schema, though the formula context and the emphasis on not passing percentage points do reinforce correct usage.
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 exactly what the tool does — discounts a single future lump sum — and provides the formula. It explicitly distinguishes itself from related siblings like calculate_annuity_present_value and calculate_perpetuity_value, so an agent can select it correctly without opening 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?
Dedicated WHEN TO USE and WHEN NOT TO USE sections name specific alternatives (calculate_npv, annuity, perpetuity tools) and the exact conditions under which each should be chosen instead. This is explicit routing guidance, 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 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 (use IRR or MOIC-with-hold-period for time-adjusted 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?
Annotations already declare readOnly, idempotent, and non-destructive hints, but the description adds valuable behavioral detail: no side effects, no network/storage access, deterministic output, and explicit error handling for division by zero or non-finite inputs. This goes well beyond the structured annotations and defines expected edge-case behavior.
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 caps-locked sections and is easy to scan. However, the formula is effectively stated twice: once in the opening sentence and again in the explicit 'Formula:' line, which is mild redundancy. Overall, every major section earns its place.
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 is fully self-contained: it defines the formula, explains when to use and avoid the metric, describes behavior and error handling, specifies the return JSON shape, and documents all three required parameters. Since there is no output schema, the explicit RETURNS section fills that gap completely.
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 descriptions in the schema already include examples and constraints. The description repeats these details and adds formula context, but it does not provide substantial new parameter-level meaning beyond what the schema already documents.
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 names a specific calculation (TVPI), states the exact formula, and clarifies what the result means ('total multiple of a fund or investment including both realised and unrealised value'). It also connects to sibling tools by noting it is equivalent to DPI + RVPI, making it easy to distinguish from the other calculate_* tools.
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 the intended context (headline multiple for PE/VC fund performance), and the WHEN NOT TO USE section explicitly warns against comparing different vintages and recommends alternatives (IRR or MOIC-with-hold-period). This gives an agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Each tool targets a mathematically distinct calculation (single-sum PV/FV, annuity, perpetuity, payback, fund multiples). The descriptions include explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections with cross-references, making it unambiguous which tool applies to which scenario.
All tool names follow the exact pattern verb_noun with the consistent 'calculate_' prefix (e.g., calculate_present_value, calculate_payback_period). The naming convention is uniform across the entire set.
11 tools is well within the ideal range for a focused domain. Each tool addresses a distinct calculation relevant to time-value-of-money and fund performance, with no redundant entries.
The set covers many core calculations but is missing NPV and IRR, which are explicitly referenced as the recommended tools in several descriptions (e.g., payback periods, TVPI). This creates a notable gap that could lead agents to follow cross-references to non-existent tools.