edgar-mcp

Overview Schema Source Related Servers Discussions Admin

get_financial_concept

Retrieve a company's reported financial figure as a time series from SEC filings, including XBRL tag, units, restatements, and fiscal years. Resolves aliases like 'sales' for revenue.

Instructions

Get one reported financial figure as a time series, with its XBRL tag.

This is the tool that answers "what was revenue". Supported concepts:

revenue, net_income, total_assets, total_liabilities, cash, operating_income, rnd_expense, shares_outstanding, gross_profit, cost_of_revenue

Plain-English aliases work too: "sales", "net sales", "profit", "R&D", "COGS", "cash and equivalents", "share count".

There is no XBRL tag called "revenue". Companies tag the same economic figure differently depending on the year and their accounting policy, so this tool walks an ordered fallback chain and tells you which tag actually matched. Always read matched_tag and quote it if it is not the first entry in fallback_chain. A revenue figure that came from SalesRevenueGoodsNet covers goods only, and an answer that does not say so is misleading. tags_tried shows every tag attempted and why each one was skipped.

Restatements are surfaced, not hidden. When a period was reported with a different value in an earlier filing, that period carries restated: true plus prior_value and prior_filed. The current value is the most recently filed one. When you see restated: true, say so in your answer and give both figures. An analyst who quotes a restated number without knowing it was restated will be wrong in a meeting.

Fiscal years are the company's, not the calendar's. NVIDIA's fiscal 2024 ended 28 January 2024. Apple's fiscal 2024 ended 28 September 2024. The fy field is the fiscal year the period belongs to; start and end are the actual dates. Always state the period end date alongside a fiscal-year figure.

Units are never mixed. The response names the single unit used and lists units_available. If the unit is not USD, the company reports in a foreign currency and the figure must not be compared with a dollar figure.

This tool does not compute ratios, margins, growth rates or per-share figures. To answer a margin question, fetch the two underlying concepts for the same period and divide, and say in your answer that you calculated it.

Args: cik: The company's CIK, from resolve_company. concept: A concept name or alias, e.g. "revenue" or "R&D". period: "annual" for fiscal-year figures, "quarterly" for quarters, or "all". Default "annual". fiscal_year: Return only this fiscal year, e.g. 2024. Omit to get a series of recent years. limit: Maximum periods to return, newest first. Default 8.

Returns: matched_tag, tags_tried, fallback_chain, unit, units_available, notes, and a values list. Each value carries value, fy, fp, start, end, filed, form, accession_number, restated, and prior_value/prior_filed when the figure changed between filings.

Input Schema

TableJSON Schema

Name	Required	Default
`cik`	Yes
`limit`	No
`period`	No	annual
`concept`	Yes
`fiscal_year`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 9, 2026

TDQS

A5/5.0

Behavior5/5

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

With no annotations provided, the description carries the full responsibility for behavioral disclosure, and it delivers exceptionally. It explains the fallback chain, the meaning of matched_tag and tags_tried, how restatements are surfaced, fiscal-year conventions, unit handling, and the need to caveat non-first fallback matches.

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?

Although long, the description is tightly organized with clear sections: supported concepts, behavioral caveats, fiscal-year context, unit rules, limitations, and parameters. It is front-loaded with the core purpose and every major paragraph covers a distinct behavioral trap, so the length is justified.

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 complete for a complex financial-data tool: it covers parameter semantics, output semantics, fallback behavior, restatements, fiscal years, units, and limitations. The output schema already describes the return shape, and the description adds the interpretive context an agent needs.

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?

The input schema has 0% description coverage, but the description's 'Args' section documents all five parameters with examples, defaults, and meaning. For example, it explains that concept can be an alias like 'R&D' and that fiscal_year returns only that year, adding substantial value beyond the bare 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?

The description opens with a specific verb and resource: 'Get one reported financial figure as a time series, with its XBRL tag.' It also explicitly says 'This is the tool that answers "what was revenue"' and lists the supported concepts, making its scope unmistakable and distinct from the sibling tools.

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?

The description gives clear when-to-use guidance, including supported concepts and aliases, and explicitly states what the tool does NOT do: it does not compute ratios, margins, or growth rates. It also offers the alternative approach of fetching two underlying concepts and dividing for margin questions, so an agent knows how to handle those requests.

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

Deploy Server