FinancialMD

First-reported versus current values

compare_versions

Read-onlyIdempotent

For one fiscal period of a company, compare every line item as first reported (the original filing) with its current value (after any restatement, reclassification or correction in later filings), with the proofs of both versions so each can be traced to its filing. The result lists each concept with first_reported, current, changed, delta and delta_percent, and counts how many items changed. Use it for restatement reviews, earnings-quality work and to explain why a number in an old report differs from today's database. Optionally restrict to one concept. Costs two standardized reads. If a dataset, field, company or analysis you need is missing, call request_data.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company": "ticker:AAPL",
      "statement": "income_statement",
      "fiscal_year": 2023,
      "fiscal_period": "FY"
    },
    "name": "compare_versions"
  }
}

Input Schema

Name	Required	Description
`company`	Yes	Company identifier: a FinancialMD id ("fmd_01H..."), an SEC CIK ("cik:320193"), or a ticker ("ticker:AAPL", optionally with the MIC "ticker:AAPL.XNAS"). A bare ticker like "AAPL" is accepted and sent as ticker:AAPL. An issuer on an EU or UK regulated market that does not file with the SEC has no CIK: pass its LEI ("lei:IOG4E947OATN0KJYSD45") or its fmd_ id.
`concept`	No	Optional: compare only this standardized concept id.
`statement`	Yes	Which financial statement.
`fiscal_year`	Yes	Fiscal year as the filer labels it (for example 2024 for Apple's year ending 2024-09-28).
`period_type`	No	Period basis to search; defaults to annual for FY and quarterly for Q1 to Q4.
`fiscal_period`	Yes	Fiscal period label: FY for the full year, or Q1, Q2, Q3, Q4.

Output Schema

Name	Required	Description
`data`	No	statement, the matched period, rows with first_reported and current value objects (each with proof), changed_count and row_count.
`meta`	No	Request metadata: request_id, as_of, company resolution, coverage, pipeline_version, licence, terms, proof_base.
`error`	No	Present only on isError results: the API error code and message plus remedy hints.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 13, 2026

changedInput schema / properties / company / description

Previous value: -"Company identifier: a FinancialMD id (\"fmd_01H...\"), an SEC CIK (\"cik:320193\"), or a ticker (\"ticker:AAPL\", optionally with the MIC \"ticker:AAPL.XNAS\"). A bare ticker like \"AAPL\" is accepted and sent as ticker:AAPL."New value: +"Company identifier: a FinancialMD id (\"fmd_01H...\"), an SEC CIK (\"cik:320193\"), or a ticker (\"ticker:AAPL\", optionally with the MIC \"ticker:AAPL.XNAS\"). A bare ticker like \"AAPL\" is accepted and sent as ticker:AAPL. An issuer on an EU or UK regulated market that does not file with the SEC has no CIK: pass its LEI (\"lei:IOG4E947OATN0KJYSD45\") or its fmd_ id."

First observedNov 13, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: a cost disclosure of two standardized reads and provenance guarantees that both versions carry proofs traceable to their filings. It does not discuss failure modes or limits on result size, so it stops short of the richest disclosure.

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 with the core comparison and scope, then usage, then cost and fallback routing, so an agent can stop reading early. The sentence enumerating first_reported, current, changed, delta and delta_percent largely restates the output schema and is the one place wording does not fully earn 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?

Given an output schema and full annotation coverage, the description supplies the remaining decision-critical facts: scope, optional narrowing, cost, traceability, and a fallback tool. Nothing an agent needs in order to call this correctly appears to be missing.

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

Parameters4/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 real meaning: the scope is exactly one fiscal period of one company and one statement, and it clarifies that comparison is all-line-items by default with an optional single-concept restriction. That default-versus-narrowing behavior is not stated 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?

Uses a specific verb (compare) against two clearly named resources: the original filing value versus the current post-restatement value, for one fiscal period. It is readily distinguishable from siblings such as changes_since or financials_as_reported because it explicitly frames the comparison as first-reported vs current with both proofs.

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

Usage Guidelines4/5

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

Gives concrete when-to-use contexts (restatement reviews, earnings-quality work, explaining discrepancies between an old report and today's database) and names the fallback (request_data) when something is missing. It does not explicitly contrast with sibling tools like changes_since or financials_as_reported, so the routing guidance is clear but not exhaustive.

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

All FinancialMD tools Inspect

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

Need Help?