io.github.simonmak-ascent/fair-value

Discounted cash flow valuation

valuation_dcf

Read-onlyIdempotent

Value going-concern firms by discounting projected free cash flows to present value, returning fair value per share plus WACC and terminal value. Supply assumptions or omit to derive from market data.

Instructions

Value a company by discounting projected free cash flows to present value. Supply explicit assumptions, or omit them to derive from current market data. Use this for going-concern cash-flow businesses; for asset-heavy holding companies use valuation_nav, and for peer-based pricing use valuation_cca. Returns fair value per share plus the WACC and terminal value.

Input Schema

TableJSON Schema

Name	Required	Description
`wacc`	No	Weighted average cost of capital as a decimal.
`years`	No	Projection horizon in years (default 5).
`ticker`	Yes	Equity ticker, e.g. 'AAPL' or '9988.HK'.
`nwc_pct`	No	Change in net working capital as a fraction of revenue (decimal).
`revenue`	No	Base-year revenue in the reporting currency.
`net_debt`	No	Total debt minus cash and equivalents.
`tax_rate`	No	Effective corporate tax rate as a decimal.
`capex_pct`	No	Capital expenditure as a fraction of revenue (decimal).
`growth_rate`	No	Annual revenue growth rate as a decimal (e.g. 0.05).
`ebitda_margin`	No	EBITDA as a fraction of revenue (decimal).
`terminal_growth`	No	Perpetuity growth rate applied to terminal value (decimal).
`depreciation_pct`	No	Depreciation as a fraction of revenue (decimal).
`shares_outstanding`	No	Diluted shares outstanding.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Error detail, present only when status='error'.
`steps`	No	Ordered computation steps, when the method reports them.
`value`	No	Primary result: a number for scalar tools, an object for valuation tools.
`method`	No	Method or tool name that produced the result.
`status`	Yes	'ok' on success, 'error' on failure.
`ticker`	No	Ticker the result pertains to, when applicable.
`assumptions`	No	Inputs and assumptions used, echoed for traceability.
`formula_ref`	No	Formula or standards reference for the method.
`data_timestamp`	No	ISO-8601 UTC timestamp of the underlying data, when fetched.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 3, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already establish readOnlyHint, idempotentHint, and openWorldHint, so safety behavior is covered by structured fields. The description adds useful context about the fallback ('omit them to derive from current market data') and the response shape ('fair value per share plus the WACC and terminal value'). It does not disclose what happens with partial assumption sets or error conditions, but with annotations covering the safety profile and an output schema present, a 3 is appropriate.

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

Conciseness5/5

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

Three sentences, zero waste: purpose first, then the assumption-vs-derived behavior, then sibling routing, then return values. Information is front-loaded and every sentence earns its place.

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

Completeness4/5

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

Given a 13-param tool with an existing output schema and annotations, the description covers purpose, fallback behavior, sibling alternatives, and return values. It could note anything about the granularity of the derived market data or whether partial assumptions are supported, but it is otherwise complete for correct invocation.

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

Parameters3/5

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

Schema coverage is 100% with per-parameter descriptions for all 13 fields, so the schema carries the parameter burden. The description adds only the high-level insight that assumptions can be supplied or omitted, without explaining syntax or precedence. Baseline 3 is correct.

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

Purpose5/5

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

The description states a specific verb+resource ('Value a company by discounting projected free cash flows to present value') and explicitly differentiates from two named siblings: valuation_nav for asset-heavy holding companies and valuation_cca for peer-based pricing. An agent can disambiguate among the 35 valuation_* siblings without opening any schema.

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?

Explicitly names when to use this tool ('going-concern cash-flow businesses') and provides two concrete alternatives with the conditions that select them. This is textbook routing guidance.

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