Skip to main content
Glama
brechanbech

SEC EDGAR MCP

by brechanbech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Remote

Financial Concept History

sec_financial_concept
Read-only

Retrieve historical SEC XBRL values for a financial concept by ticker or CIK; filter annual or quarterly periods, page older facts, and optionally include amendments.

Instructions

Get historical values for a financial concept from SEC XBRL data. Returns the most recent 20 facts by default (in chronological order); 'total_facts' says how many exist, and passing 'next_offset' back as 'offset' pages further into the past. The 'annual' and 'quarterly' period filters leave out amendments (10-K/A), which restate periods the original already reported; pass include_amendments: true to admit them, and 'amended_facts' counts them. Common concepts: 'Revenues', 'NetIncomeLoss', 'EarningsPerShareBasic', 'Assets', 'StockholdersEquity', 'OperatingIncomeLoss', 'CashAndCashEquivalentsAtCarryingValue'.

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of facts to return (default 20, max 100), most recent first
offsetNoNumber of most-recent facts to skip, for paging back into older history (default 0). Pass the previous response's 'next_offset'.
periodNoFilter by period: 'annual' (10-K, or 20-F/40-F for foreign filers) or 'quarterly' (10-Q, or 6-K for foreign filers)
tickerYesStock ticker, e.g. AAPL, or the company's CIK, e.g. 1163302, for one with no current ticker (delisted, acquired or renamed)
conceptYesXBRL concept name, e.g. 'Revenues', 'NetIncomeLoss'
taxonomyNoTaxonomy: 'us-gaap' (default) or 'ifrs-full'us-gaap
include_amendmentsNoWith 'period': also match amendments (10-K/A, 10-Q/A, 20-F/A), which restate a period the original already reported, so the series then holds both (default false). Without 'period', every form is returned anyway.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • addedInput schema / properties / include_amendments
      Added value: +{
+  "default": false,
+  "description": "With 'period': also match amendments (10-K/A, 10-Q/A, 20-F/A), which\nrestate a period the original already reported, so the series then holds\nboth (default false). Without 'period', every form is returned anyway.",
+  "type": "boolean"
+}
  2. Changed1 schema field changedv0.7.0
    • changedInput schema / properties / ticker / description
      Previous value: -"Stock ticker symbol"New value: +"Stock ticker, e.g. AAPL, or the company's CIK, e.g. 1163302, for one with no\ncurrent ticker (delisted, acquired or renamed)"
  3. First observed

TDQS

A3.9/5.0
Behavior5/5

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

Beyond the read-only annotation, the description discloses default result count, chronological ordering, total_facts, next_offset paging, and amendment exclusion semantics. These are meaningful behavioral details an agent needs to invoke and interpret the tool correctly.

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?

The description is front-loaded with the core action, then efficiently covers paging, amendment behavior, and helpful concept examples. Every sentence contributes useful information without waste.

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?

The description covers paging and key return counts, which is important because there is no output schema. However, it does not describe the full shape of returned fact records, leaving some return-value structure implicit.

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 practical meaning for the concept parameter by listing common XBRL concepts and reinforces amendment-filter semantics for period/include_amendments. It does not add much beyond the schema for ticker, taxonomy, limit, or offset.

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

Purpose4/5

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

States a specific verb and resource: getting historical values for a financial concept from SEC XBRL data. The scope is clear and concept-specific, but it does not explicitly differentiate itself from siblings such as sec_company_facts or sec_xbrl_frames.

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

Usage Guidelines2/5

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

The description explains paging and amendment behavior but gives no explicit guidance on when to use this tool versus alternatives like sec_company_facts or sec_xbrl_frames. Usage is only implied by the first sentence.

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

Deploy Server

Other Tools