Skip to main content
Glama

Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Compute Forward DCF

compute_dcf
Read-onlyIdempotent

Forward discounted-cash-flow valuation (two-stage Gordon-growth model): caller provides growth + WACC + terminal assumptions, returns per-share intrinsic value (value_per_share_cents, cents of result.reporting_currency — USD for US filers, the filer's own currency otherwise; never converted) + 5×5 sensitivity grid. In prose quote result.metrics_display verbatim (value_per_share is the per-share value in currency units, e.g. "$249.17"; each grid cell carries value_per_share_display), never the cents. Pulls FCF base + net debt + shares from R2; caller can override any field. Definitions (consistent with get_financial_ratios / get_capital_allocation_profile): FCF base = operating_cash_flow − capex (absolute USD); net_debt = total_debt − (cash + short-term investments), long-term marketable securities not netted; result.net_debt_basis says whether it was reported or an assumption (debt_assumed_zero keeps known cash when debt is undisclosed). Shares resolve via a fallback chain (valuation row → fact CommonSharesOutstanding → net_income/eps_diluted), reported as result.shares_source. The pulled inputs are echoed in result.inputs_echo with their source lineage so the valuation is reproducible and traceable. result.inputs_provenance cites the source fact_id of every input pulled from the filings, and the FCF base (when it is operating_cash_flow − capex from cited facts) carries a derived_id: cite those for the inputs. The valuation outputs rest on your assumptions, so no filing backs the ASSUMPTIONS, but the arithmetic is checkable: when every input was pulled from cited facts (fcf_source "trend", no fcf_base_override or shares_override), result.outputs_provenance.value_per_share.derived_id is the id of the value per share, and each result.sensitivity_table cell carries its own derived_id; the id states your assumptions (WACC, growth, terminal growth, years), so cite the id beside the figure you quote and the fact-check recomputes it exactly. An overridden input, a three_statement run or a degenerate model ships with no id: quote those as your own assumptions, never as a verified figure. A null value_per_share_cents means the model is degenerate (e.g. WACC ≤ terminal growth, or FCF base ≤ 0) or a required input was unavailable — it is NOT a zero valuation; the reason field explains. Use the returned figures exactly. Use this when you want to drive the assumptions yourself; for the pipeline's pre-computed DCF/DDM value and inputs (no assumptions needed) use get_valuation_metrics instead. Does NOT persist a report — use create_report (report_type:'reverse_dcf') for that.

fcf_source (default "trend"): "trend" compounds a single FCF base by stage1_growth_rate every year (the original behavior, unchanged). "three_statement" instead runs a full linked Income Statement / Balance Sheet / Cash Flow projection (project_three_statement's engine) and feeds its year-by-year FCF stream into the same PV math — stage1_growth_rate is then ignored (kept for echo only) because revenue growth + margins drive FCF instead of a flat compounding rate. The projection detail (including per-year tie_out_ok) is returned in three_statement_detail when used. Tier: sp500+.

Input Schema

NameRequiredDescriptionDefault
waccNoDiscount rate. Default 0.09.
tickerYesStock ticker symbol of the company to value, e.g. AAPL, MSFT, BRK.B.
as_of_dateNoPoint-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT). Omit to use the latest knowable inputs.
fcf_sourceNo"trend" (default): compound fcf_base by stage1_growth_rate every year (unchanged original behavior). "three_statement": derive the FCF stream from a full linked 3-statement projection instead — see the tool description for details.trend
stage1_yearsNoNumber of explicit high-growth projection years before the terminal stage (3–15). Defaults to 5.
shares_overrideNoOverride shares outstanding. Leave unset to use R2-derived.
fcf_base_overrideNoOverride the auto-pulled FCF base (USD). Leave unset to use R2-derived.
stage1_growth_rateYesStage-1 FCF growth rate (e.g. 0.12 = 12%/yr).
terminal_growth_rateNoLong-run growth. Default 0.025.
three_statement_assumptionsNoOnly used when fcf_source is "three_statement". Overrides for the underlying projection; unset fields use project_three_statement's defaults.

Output Schema

NameRequiredDescriptionDefault
_metaYesProvenance envelope — data lineage for every MCP response
resultYes
tickerYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / as_of_date / description
      Previous value: -"Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT); valuation.parquet inputs are best-effort PIT (filtered by created_at, its accepted_at proxy — no SEC acceptance timestamp exists for pipeline-computed valuations). Omit to use the latest knowable inputs."New value: +"Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT). Omit to use the latest knowable inputs."
  2. Changed1 schema field changed
    • changedOutput schema / properties / _meta / properties / cost_usd / properties / basis / description
      Previous value: -"payg_charge = real charge (agent-pay or your balance). payg_rate_card = indicative price, not billed."New value: +"payg_charge = real pay-per-call charge (a card or MPP payment through agent-pay). payg_rate_card = indicative price, not billed."
  3. Changed2 schema fields changed
    • changedOutput schema / properties / _meta / properties / cost_usd / properties / basis / description
      Previous value: -"payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed."New value: +"payg_charge = real charge (agent-pay or your balance). payg_rate_card = indicative price, not billed."
    • changedOutput schema / properties / _meta / properties / cost_usd / properties / billed / description
      Previous value: -"true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free."New value: +"true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value only: no charge was made for this call (it was within your plan)."
  4. Changed29 schema fields changed
    • changedInput schema / properties / as_of_date / description
      Previous value: -"Point-in-time cutoff for the reported inputs, YYYY-MM-DD: only filings accepted by this date, e.g. 2024-06-30."New value: +"Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT); valuation.parquet inputs are best-effort PIT (filtered by created_at, its accepted_at proxy — no SEC acceptance timestamp exists for pipeline-computed valuations). Omit to use the latest knowable inputs."
    • changedInput schema / properties / fcf_base_override / description
      Previous value: -"Starting free cash flow in USD, used instead of the reported figure; trend mode only, e.g. 95000000000."New value: +"Override the auto-pulled FCF base (USD). Leave unset to use R2-derived."
    • changedInput schema / properties / fcf_source / description
      Previous value: -"trend (default) grows starting free cash flow by stage1_growth_rate; three_statement projects linked statements instead, e.g. three_statement."New value: +"\"trend\" (default): compound fcf_base by stage1_growth_rate every year (unchanged original behavior). \"three_statement\": derive the FCF stream from a full linked 3-statement projection instead — see the tool description for details."
    • changedInput schema / properties / shares_override / description
      Previous value: -"Share count used instead of the reported figure, above zero, e.g. 15000000000."New value: +"Override shares outstanding. Leave unset to use R2-derived."
    • changedInput schema / properties / stage1_growth_rate / description
      Previous value: -"Yearly growth in the projection years as a decimal, -0.5 to 1: of free cash flow (trend) or of revenue (three_statement), e.g. 0.08."New value: +"Stage-1 FCF growth rate (e.g. 0.12 = 12%/yr)."
    • changedInput schema / properties / stage1_years / description
      Previous value: -"Number of projection years, 3 to 15; defaults to 5, e.g. 10."New value: +"Number of explicit high-growth projection years before the terminal stage (3–15). Defaults to 5."
    • changedInput schema / properties / terminal_growth_rate / description
      Previous value: -"Growth after the projection years as a decimal, -0.05 to 0.1; defaults to 0.025, e.g. 0.02."New value: +"Long-run growth. Default 0.025."
    • changedInput schema / properties / three_statement_assumptions / description
      Previous value: -"Overrides for three_statement mode; each unset field keeps its default, e.g. {\"tax_rate\": 0.25}."New value: +"Only used when fcf_source is \"three_statement\". Overrides for the underlying projection; unset fields use project_three_statement's defaults."
    • changedInput schema / properties / three_statement_assumptions / properties / cash_sweep_pct / description
      Previous value: -"Share of each year's free cash flow used to repay debt, 0 to 1; defaults to 0, e.g. 0.5."New value: +"Default 0."
    • changedInput schema / properties / three_statement_assumptions / properties / dividend_payout_pct / description
      Previous value: -"Share of each year's net income distributed as dividends, 0 to 1; defaults to 0, e.g. 0.3."New value: +"Default 0."
    • changedInput schema / properties / three_statement_assumptions / properties / interest_rate_on_debt / description
      Previous value: -"Interest rate on debt as a decimal, 0 to 0.5; defaults to 0.06, e.g. 0.05."New value: +"Default 0.06."
    • changedInput schema / properties / three_statement_assumptions / properties / tax_rate / description
      Previous value: -"Tax rate as a decimal, 0 to 1; defaults to 0.21, e.g. 0.25."New value: +"Default 0.21."
    • changedInput schema / properties / ticker / description
      Previous value: -"Ticker symbol or SEC CIK of the company to value, e.g. AAPL."New value: +"Stock ticker symbol of the company to value, e.g. AAPL, MSFT, BRK.B."
    • changedInput schema / properties / wacc / description
      Previous value: -"Discount rate as a decimal, 0.01 to 0.5; defaults to 0.09, e.g. 0.1."New value: +"Discount rate. Default 0.09."
    • addedOutput schema / properties / _meta / properties / cost_usd
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Per-call cost transparency. Omitted for subscription-only tools that have no PAYG-equivalent price.",
      +  "properties": {
      +    "amount_usd": {
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "basis": {
      +      "description": "payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed.",
      +      "enum": [
      +        "payg_charge",
      +        "payg_rate_card"
      +      ],
      +      "type": "string"
      +    },
      +    "billed": {
      +      "description": "true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free.",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "amount_usd",
      +    "billed",
      +    "basis"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / _meta / properties / data_plan
      Added value: +{
      +  "description": "Access plan: sample | sp500 | pro | full",
      +  "type": "string"
      +}
    • changedOutput schema / properties / _meta / properties / fundamentals_as_of / description
      Previous value: -"Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."New value: +"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."
    • addedOutput schema / properties / _meta / properties / last_updated
      Added value: +{
      +  "description": "ISO timestamp when the snapshot was exported",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / latency_ms
      Added value: +{
      +  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / _meta / properties / limit_warnings
      Added value: +{
      +  "description": "Soft-warning array for partial fulfillment. Each entry carries a stable subcode + remediation.options[]. AI agents pattern-match on subcode.",
      +  "items": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "code": {
      +        "const": "LIMIT_EXCEEDED",
      +        "type": "string"
      +      },
      +      "current_plan": {
      +        "type": "string"
      +      },
      +      "extensions": {
      +        "additionalProperties": {},
      +        "type": "object"
      +      },
      +      "limit_type": {
      +        "type": "string"
      +      },
      +      "limit_value": {},
      +      "remediation": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "contact_sales": {
      +            "type": "string"
      +          },
      +          "default_action": {
      +            "type": "string"
      +          },
      +          "options": {
      +            "items": {
      +              "additionalProperties": {},
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "pricing_page": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "options",
      +          "default_action",
      +          "pricing_page",
      +          "contact_sales"
      +        ],
      +        "type": "object"
      +      },
      +      "requested_value": {},
      +      "returned_value": {},
      +      "subcode": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "code",
      +      "subcode",
      +      "limit_type",
      +      "current_plan",
      +      "remediation"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / _meta / properties / payg_override
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Set when this single response was paid for via the agent-pay PAYG flow — the rate-limit / depth-limit checks were bypassed for this call only.",
      +  "properties": {
      +    "amount_cents": {
      +      "type": "number"
      +    },
      +    "entity_scope_hash": {
      +      "type": "string"
      +    },
      +    "meter": {
      +      "type": "string"
      +    },
      +    "quote_id": {
      +      "type": "string"
      +    },
      +    "retry_token_hash": {
      +      "type": "string"
      +    },
      +    "ticker_count": {
      +      "type": "number"
      +    },
      +    "tool": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "quote_id",
      +    "tool",
      +    "meter",
      +    "amount_cents",
      +    "ticker_count",
      +    "entity_scope_hash",
      +    "retry_token_hash"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / _meta / properties / rate_limit
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Caller's remaining budget",
      +  "properties": {
      +    "limit": {
      +      "type": "integer"
      +    },
      +    "remaining": {
      +      "type": "integer"
      +    },
      +    "reset_at": {
      +      "description": "ISO 8601 timestamp when the window resets",
      +      "type": "string"
      +    },
      +    "window": {
      +      "enum": [
      +        "minute",
      +        "hour"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "limit",
      +    "remaining",
      +    "reset_at",
      +    "window"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / _meta / properties / request_id
      Added value: +{
      +  "description": "Per-request correlation id (8-char)",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / schema_version
      Added value: +{
      +  "description": "Parquet schema version from manifest.json",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / snapshot
      Added value: +{
      +  "description": "Snapshot directory name (e.g. snapshot_20260420)",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / truncation / properties / current_plan
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / truncation / properties / upgrade_required_for
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / truncation / properties / upgrade_url
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / properties / _meta / required
      Previous value: -[
      -  "source",
      -  "pit_safe"
      -]New value: +[
      +  "data_plan",
      +  "schema_version",
      +  "snapshot",
      +  "last_updated",
      +  "source",
      +  "pit_safe"
      +]
  5. Changed29 schema fields changed
    • changedInput schema / properties / as_of_date / description
      Previous value: -"Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT); valuation.parquet inputs are best-effort PIT (filtered by created_at, its accepted_at proxy — no SEC acceptance timestamp exists for pipeline-computed valuations). Omit to use the latest knowable inputs."New value: +"Point-in-time cutoff for the reported inputs, YYYY-MM-DD: only filings accepted by this date, e.g. 2024-06-30."
    • changedInput schema / properties / fcf_base_override / description
      Previous value: -"Override the auto-pulled FCF base (USD). Leave unset to use R2-derived."New value: +"Starting free cash flow in USD, used instead of the reported figure; trend mode only, e.g. 95000000000."
    • changedInput schema / properties / fcf_source / description
      Previous value: -"\"trend\" (default): compound fcf_base by stage1_growth_rate every year (unchanged original behavior). \"three_statement\": derive the FCF stream from a full linked 3-statement projection instead — see the tool description for details."New value: +"trend (default) grows starting free cash flow by stage1_growth_rate; three_statement projects linked statements instead, e.g. three_statement."
    • changedInput schema / properties / shares_override / description
      Previous value: -"Override shares outstanding. Leave unset to use R2-derived."New value: +"Share count used instead of the reported figure, above zero, e.g. 15000000000."
    • changedInput schema / properties / stage1_growth_rate / description
      Previous value: -"Stage-1 FCF growth rate (e.g. 0.12 = 12%/yr)."New value: +"Yearly growth in the projection years as a decimal, -0.5 to 1: of free cash flow (trend) or of revenue (three_statement), e.g. 0.08."
    • changedInput schema / properties / stage1_years / description
      Previous value: -"Number of explicit high-growth projection years before the terminal stage (3–15). Defaults to 5."New value: +"Number of projection years, 3 to 15; defaults to 5, e.g. 10."
    • changedInput schema / properties / terminal_growth_rate / description
      Previous value: -"Long-run growth. Default 0.025."New value: +"Growth after the projection years as a decimal, -0.05 to 0.1; defaults to 0.025, e.g. 0.02."
    • changedInput schema / properties / three_statement_assumptions / description
      Previous value: -"Only used when fcf_source is \"three_statement\". Overrides for the underlying projection; unset fields use project_three_statement's defaults."New value: +"Overrides for three_statement mode; each unset field keeps its default, e.g. {\"tax_rate\": 0.25}."
    • changedInput schema / properties / three_statement_assumptions / properties / cash_sweep_pct / description
      Previous value: -"Default 0."New value: +"Share of each year's free cash flow used to repay debt, 0 to 1; defaults to 0, e.g. 0.5."
    • changedInput schema / properties / three_statement_assumptions / properties / dividend_payout_pct / description
      Previous value: -"Default 0."New value: +"Share of each year's net income distributed as dividends, 0 to 1; defaults to 0, e.g. 0.3."
    • changedInput schema / properties / three_statement_assumptions / properties / interest_rate_on_debt / description
      Previous value: -"Default 0.06."New value: +"Interest rate on debt as a decimal, 0 to 0.5; defaults to 0.06, e.g. 0.05."
    • changedInput schema / properties / three_statement_assumptions / properties / tax_rate / description
      Previous value: -"Default 0.21."New value: +"Tax rate as a decimal, 0 to 1; defaults to 0.21, e.g. 0.25."
    • changedInput schema / properties / ticker / description
      Previous value: -"Stock ticker symbol of the company to value, e.g. AAPL, MSFT, BRK.B."New value: +"Ticker symbol or SEC CIK of the company to value, e.g. AAPL."
    • changedInput schema / properties / wacc / description
      Previous value: -"Discount rate. Default 0.09."New value: +"Discount rate as a decimal, 0.01 to 0.5; defaults to 0.09, e.g. 0.1."
    • removedOutput schema / properties / _meta / properties / cost_usd
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "Per-call cost transparency. Omitted for subscription-only tools that have no PAYG-equivalent price.",
      -  "properties": {
      -    "amount_usd": {
      -      "minimum": 0,
      -      "type": "number"
      -    },
      -    "basis": {
      -      "description": "payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed.",
      -      "enum": [
      -        "payg_charge",
      -        "payg_rate_card"
      -      ],
      -      "type": "string"
      -    },
      -    "billed": {
      -      "description": "true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free.",
      -      "type": "boolean"
      -    }
      -  },
      -  "required": [
      -    "amount_usd",
      -    "billed",
      -    "basis"
      -  ],
      -  "type": "object"
      -}
    • removedOutput schema / properties / _meta / properties / data_plan
      Removed value: -{
      -  "description": "Access plan: sample | sp500 | pro | full",
      -  "type": "string"
      -}
    • changedOutput schema / properties / _meta / properties / fundamentals_as_of / description
      Previous value: -"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."New value: +"Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."
    • removedOutput schema / properties / _meta / properties / last_updated
      Removed value: -{
      -  "description": "ISO timestamp when the snapshot was exported",
      -  "type": "string"
      -}
    • removedOutput schema / properties / _meta / properties / latency_ms
      Removed value: -{
      -  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / _meta / properties / limit_warnings
      Removed value: -{
      -  "description": "Soft-warning array for partial fulfillment. Each entry carries a stable subcode + remediation.options[]. AI agents pattern-match on subcode.",
      -  "items": {
      -    "additionalProperties": true,
      -    "properties": {
      -      "code": {
      -        "const": "LIMIT_EXCEEDED",
      -        "type": "string"
      -      },
      -      "current_plan": {
      -        "type": "string"
      -      },
      -      "extensions": {
      -        "additionalProperties": {},
      -        "type": "object"
      -      },
      -      "limit_type": {
      -        "type": "string"
      -      },
      -      "limit_value": {},
      -      "remediation": {
      -        "additionalProperties": true,
      -        "properties": {
      -          "contact_sales": {
      -            "type": "string"
      -          },
      -          "default_action": {
      -            "type": "string"
      -          },
      -          "options": {
      -            "items": {
      -              "additionalProperties": {},
      -              "type": "object"
      -            },
      -            "type": "array"
      -          },
      -          "pricing_page": {
      -            "type": "string"
      -          }
      -        },
      -        "required": [
      -          "options",
      -          "default_action",
      -          "pricing_page",
      -          "contact_sales"
      -        ],
      -        "type": "object"
      -      },
      -      "requested_value": {},
      -      "returned_value": {},
      -      "subcode": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "code",
      -      "subcode",
      -      "limit_type",
      -      "current_plan",
      -      "remediation"
      -    ],
      -    "type": "object"
      -  },
      -  "type": "array"
      -}
    • removedOutput schema / properties / _meta / properties / payg_override
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "Set when this single response was paid for via the agent-pay PAYG flow — the rate-limit / depth-limit checks were bypassed for this call only.",
      -  "properties": {
      -    "amount_cents": {
      -      "type": "number"
      -    },
      -    "entity_scope_hash": {
      -      "type": "string"
      -    },
      -    "meter": {
      -      "type": "string"
      -    },
      -    "quote_id": {
      -      "type": "string"
      -    },
      -    "retry_token_hash": {
      -      "type": "string"
      -    },
      -    "ticker_count": {
      -      "type": "number"
      -    },
      -    "tool": {
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "quote_id",
      -    "tool",
      -    "meter",
      -    "amount_cents",
      -    "ticker_count",
      -    "entity_scope_hash",
      -    "retry_token_hash"
      -  ],
      -  "type": "object"
      -}
    • removedOutput schema / properties / _meta / properties / rate_limit
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "Caller's remaining budget",
      -  "properties": {
      -    "limit": {
      -      "type": "integer"
      -    },
      -    "remaining": {
      -      "type": "integer"
      -    },
      -    "reset_at": {
      -      "description": "ISO 8601 timestamp when the window resets",
      -      "type": "string"
      -    },
      -    "window": {
      -      "enum": [
      -        "minute",
      -        "hour"
      -      ],
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "limit",
      -    "remaining",
      -    "reset_at",
      -    "window"
      -  ],
      -  "type": "object"
      -}
    • removedOutput schema / properties / _meta / properties / request_id
      Removed value: -{
      -  "description": "Per-request correlation id (8-char)",
      -  "type": "string"
      -}
    • removedOutput schema / properties / _meta / properties / schema_version
      Removed value: -{
      -  "description": "Parquet schema version from manifest.json",
      -  "type": "string"
      -}
    • removedOutput schema / properties / _meta / properties / snapshot
      Removed value: -{
      -  "description": "Snapshot directory name (e.g. snapshot_20260420)",
      -  "type": "string"
      -}
    • removedOutput schema / properties / _meta / properties / truncation / properties / current_plan
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / _meta / properties / truncation / properties / upgrade_required_for
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / _meta / properties / truncation / properties / upgrade_url
      Removed value: -{
      -  "type": "string"
      -}
    • changedOutput schema / properties / _meta / required
      Previous value: -[
      -  "data_plan",
      -  "schema_version",
      -  "snapshot",
      -  "last_updated",
      -  "source",
      -  "pit_safe"
      -]New value: +[
      +  "source",
      +  "pit_safe"
      +]
  6. Changed1 schema field changed
    • changedOutput schema / properties / _meta / properties / fundamentals_as_of / description
      Previous value: -"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to."New value: +"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."
  7. Changed2 schema fields changed
    • addedOutput schema / properties / _meta / properties / fundamentals_as_of
      Added value: +{
      +  "description": "ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / _meta / properties / price_as_of
      Added value: +{
      +  "description": "ISO timestamp when the price surfaces were last refreshed.",
      +  "type": "string"
      +}
  8. Changed2 schema fields changed
    • addedInput schema / properties / fcf_source
      Added value: +{
      +  "default": "trend",
      +  "description": "\"trend\" (default): compound fcf_base by stage1_growth_rate every year (unchanged original behavior). \"three_statement\": derive the FCF stream from a full linked 3-statement projection instead — see the tool description for details.",
      +  "enum": [
      +    "trend",
      +    "three_statement"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / three_statement_assumptions
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Only used when fcf_source is \"three_statement\". Overrides for the underlying projection; unset fields use project_three_statement's defaults.",
      +  "properties": {
      +    "cash_sweep_pct": {
      +      "description": "Default 0.",
      +      "maximum": 1,
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "dividend_payout_pct": {
      +      "description": "Default 0.",
      +      "maximum": 1,
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "interest_rate_on_debt": {
      +      "description": "Default 0.06.",
      +      "maximum": 0.5,
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "tax_rate": {
      +      "description": "Default 0.21.",
      +      "maximum": 1,
      +      "minimum": 0,
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
  9. Changed2 schema fields changed
    • addedOutput schema / properties / _meta / properties / cost_usd
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Per-call cost transparency. Omitted for subscription-only tools that have no PAYG-equivalent price.",
      +  "properties": {
      +    "amount_usd": {
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "basis": {
      +      "description": "payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed.",
      +      "enum": [
      +        "payg_charge",
      +        "payg_rate_card"
      +      ],
      +      "type": "string"
      +    },
      +    "billed": {
      +      "description": "true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free.",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "amount_usd",
      +    "billed",
      +    "basis"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / _meta / properties / latency_ms
      Added value: +{
      +  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
  10. Changed1 schema field changed
    • addedOutput schema / properties / _meta / properties / pit_safe / description
      Added value: +"true iff a zero-look-ahead point-in-time cut was applied to every returned figure"
  11. Changed1 schema field changed
    • addedInput schema / properties / as_of_date
      Added value: +{
      +  "description": "Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT); valuation.parquet inputs are best-effort PIT (filtered by created_at, its accepted_at proxy — no SEC acceptance timestamp exists for pipeline-computed valuations). Omit to use the latest knowable inputs.",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
  12. Changed2 schema fields changed
    • addedInput schema / properties / stage1_years / description
      Added value: +"Number of explicit high-growth projection years before the terminal stage (3–15). Defaults to 5."
    • addedInput schema / properties / ticker / description
      Added value: +"Stock ticker symbol of the company to value, e.g. AAPL, MSFT, BRK.B."
  13. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial behavior beyond them: currency is never converted (USD for US filers, filer currency otherwise), a null `value_per_share_cents` is explicitly NOT a zero valuation and signals a degenerate model (WACC ≤ terminal growth, FCF base ≤ 0), and degenerate/overridden/three_statement runs ship without a provenance id. It also discloses the data-pull lineage (R2 FCF base, net debt, shares fallback chain) and the sp500+ tier.

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?

Front-loaded correctly — what it does and returns come first, then input definitions, then provenance rules, then usage routing. Every section carries information, but the citation/derived_id paragraph is dense and partly reads as reporting instructions rather than tool semantics, and the repetition about assumptions having no filing backing could be tightened.

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?

For a 10-parameter tool with a nested object and an output schema, the description is thorough: it explains currency handling, null/degenerate semantics, provenance id availability rules, the `as_of_date` strict-PIT behavior, and the tier gate. An agent could call and correctly report results without consulting anything else.

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

Parameters5/5

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 genuine meaning the schema cannot: `fcf_source` 'trend' compounds a single base by `stage1_growth_rate` while 'three_statement' runs a linked projection and causes `stage1_growth_rate` to be ignored, and overrides (`fcf_base_override`, `shares_override`) suppress the output `derived_id`. It also defines the derived inputs (FCF base = OCF − capex, net_debt treating long-term marketable securities as not netted) that the schema never states.

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?

Opens with a specific verb + resource + method: 'Forward discounted-cash-flow valuation (two-stage Gordon-growth model)' and states exactly what it returns (per-share intrinsic value in cents plus a 5×5 sensitivity grid). It explicitly contrasts itself with `get_valuation_metrics` (pre-computed, no assumptions) and `create_report` (persistence), so an agent can distinguish it from siblings 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.

Usage Guidelines5/5

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

Gives an explicit when-to-use rule ('when you want to drive the assumptions yourself') and names the alternative with the condition that selects it (`get_valuation_metrics` for the pipeline's pre-computed DCF/DDM). It also states what the tool does NOT do ('Does NOT persist a report — use `create_report`') and discloses the sp500+ tier prerequisite, leaving little to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.