Skip to main content
Glama

valuation-api

by io.finance-tools.api
OverviewDiscussionsAdmin
This connector has been deprecated

Superseded by valuation-api on valuation.finance-tools.io (fresh connector with focused 12-tool set and current TDQS eval)

calculate_irr

Read-onlyIdempotent

Calculate the Internal Rate of Return (IRR), MOIC and an IRR sensitivity table for a single lump-sum equity investment that returns one exit value after a whole-year hold period. WHEN TO USE: you have an upfront investment amount, a single exit value and a hold period in whole years (standard PE/VC single-exit scenario) and need the annualised return, the money multiple, or a return stress-test. The result also includes a plain-language interpretation benchmarked against VC/PE/public-market return hurdles. WHEN NOT TO USE: for cash-flow streams with multiple intermediate distributions (use calculate_npv or calculate_moic on the full cash-flow array), or when you only need the sensitivity grid (use calculate_irr_sensitivity). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access, no randomness; idempotent and non-destructive; identical inputs always produce identical outputs. IRR is solved over the cash-flow schedule [-investment, 0, ..., exit_value] via Newton-Raphson with bisection fallback. RETURNS: JSON object with concept, definition, formula, calculation (irr as a percentage string, moic as a multiple, cash_flows array), interpretation, and sensitivity (byMultiple, byHoldPeriod). PARAMETERS: initial_investment (number > 0, currency units), exit_value (number > 0, same currency units), hold_period (integer >= 1 whole years), currency (optional string: GBP default, USD, EUR, JPY, CHF — display only, no conversion).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
currencyNoOptional display currency code. Defaults to GBP. Used only for formatting output labels — no FX conversion is performed.GBP
exit_valueYesValue returned at exit, same currency units as initial_investment, e.g. 250000. Must be positive.
hold_periodYesHolding period in whole years, e.g. 5. Must be a positive integer (1, 2, 3, ...).
initial_investmentYesAmount invested up front, in currency units, e.g. 100000. Must be positive.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond annotations that already mark it read-only, idempotent, and non-destructive, the description discloses that the tool performs a pure deterministic calculation with no side effects, network, storage, or randomness, and gives the exact cash-flow schedule and Newton-Raphson-with-bisection solution method. This gives an agent a concrete, trustworthy behavioral model.

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

Conciseness4/5

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

Well-structured with labelled sections and front-loaded purpose, but slightly verbose: 'idempotent and non-destructive; identical inputs always produce identical outputs' repeats the same idea, and the BEHAVIOUR line packs several near-synonymous claims. Still, every section earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is self-sufficient despite lacking an output schema: it enumerates the JSON return fields, explains the interpretation output, gives parameter constraints, and routes to siblings in edge cases. An agent has all needed context to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description's PARAMETERS block mostly restates schema constraints; it adds the 'same currency units' relationship and currency display-only nuance, but these are already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and deliverable ('Calculate the Internal Rate of Return (IRR), MOIC and an IRR sensitivity table') and bounds the tool by the exact deal shape it accepts: single lump-sum investment, one exit value, whole-year hold. This directly differentiates it from calculate_irr_sensitivity, calculate_npv, and calculate_moic, which appear as siblings.

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

Usage Guidelines5/5

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

Includes explicit WHEN TO USE and WHEN NOT TO USE sections naming sibling tools as alternatives: calculate_npv or calculate_moic for multi-distribution cash-flow streams, calculate_irr_sensitivity when only the grid is needed. This is the clearest possible routing guidance.

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

All valuation-api toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources