Skip to main content
Glama

secedgar-mcp-server

by io.github.cyanheads

Secedgar Get Financials

secedgar_get_financials
Read-onlyIdempotent

Get historical XBRL financial data for a company. Accepts friendly concept names (e.g., "revenue", "net_income", "assets") or raw XBRL tags. Discover available friendly names with secedgar_search_concepts. Handles historical tag changes and deduplicates data automatically.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoCap the inline data[] to the most-recent N periods (the series is newest-first). The full series is always registered to the dataframe, so older periods stay queryable via secedgar_dataframe_query. Omit to return every period inline.
companyYesTicker symbol (e.g., "AAPL") or CIK number. Ticker is preferred.
conceptYesFinancial concept — friendly name (e.g., "revenue", "net_income", "assets", "eps_diluted") or raw XBRL tag (e.g., "AccountsPayableCurrent"). Friendly names auto-resolve to the correct XBRL tags and handle historical tag changes.
taxonomyNoXBRL taxonomy. us-gaap for US companies, ifrs-full for foreign filers, dei for entity info (shares outstanding).us-gaap
period_typeNoFilter to annual (FY) or quarterly (Q1-Q4) data. "all" returns both. When omitted, defaults to "annual"; instant (balance-sheet) concepts automatically fall back to returning the full series on the first call when the annual filter yields nothing (#48).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit cap applied.
cikNoResolved CIK, zero-padded to 10 digits.
dataNoDeduplicated time series, newest first.
unitNoUnit of measure (e.g., "USD", "shares", "USD/shares").
errorNoPresent when the call failed. Absent on success.
labelNoHuman-readable label for the concept.
shownNoNumber of periods shown inline.
caveatsNoData-completeness warnings about the returned series. Two kinds. On quarterly results, one entry when one or two calendar quarters are absent from every recent qualifying year — SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact, so the calendar quarter fiscal Q4 spans has no frame-tagged value, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. Applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones. On any result, one entry when the series stops well short of today — either because the concept resolved to an XBRL tag SEC has retired from the taxonomy (the current tags reported nothing), or because a current tag's series ends more than two years plus a filing window back, which is what a filer migrating to a different element or dropping the disclosure looks like. Absent when the series has nothing to flag.
companyNoResolved entity name (SEC-conformed).
conceptNoXBRL tag name used.
datasetNoCanvas dataframe handle holding the same time series. Use for cross-company JOINs via secedgar_dataframe_query. The source-filing fiscal keys are materialized as source_filing_fy/source_filing_fp — order, group, and window by period_end, not by those columns. Absent when canvas is unavailable.
truncatedNoTrue when the inline data[] was capped by limit.
tags_triedNoXBRL tags that were attempted (shown when using friendly names that map to multiple tags).
descriptionNoXBRL taxonomy description for this concept. Often absent for company-extension tags or older concepts.

TDQS

A3.5/5.0
Behavior4/5

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

Annotations declare read-only, open-world, idempotent. Description adds 'Handles historical tag changes and deduplicates data automatically' and 'Accepts friendly concept names or raw XBRL tags' — behavioral details that go beyond annotations. No contradictions.

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?

Three sentences, front-loaded with core purpose. Each sentence adds information: functionality, input flexibility, and automatic processing. No fluff.

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?

With output schema present and rich parameter descriptions, the description covers the essentials: what it returns (historical data), how to specify inputs (friendly/raw), and dependency on search_concepts for discovery. Missing explicit mention of response structure but output schema covers that.

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 descriptions cover all 5 parameters (100% coverage). The description adds context about friendly-name resolution and historical tag changes that relates to the 'concept' parameter, but doesn't meaningfully enrich parameter meaning beyond schema. Baseline 3 is appropriate.

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 'Get historical XBRL financial data for a company' — a specific verb and resource. Mentions it accepts friendly names or raw tags, which clarifies scope. However, it doesn't explicitly contrast with sibling tools like secedgar_get_snapshot, so it's clear but not fully differentiated.

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?

Only hints at discovery via secedgar_search_concepts for friendly names. No explicit when-to-use vs alternatives (e.g., when to choose this over secedgar_get_snapshot). Lacks guidance on when not to use this tool.

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

All secedgar-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0
Disambiguation4/5

Most tools have clearly distinct purposes, with detailed descriptions that explicitly separate similar-sounding ones (e.g., secedgar_get_institutional_holdings vs secedgar_find_holders vs secedgar_get_beneficial_owners). The four ownership/holdings tools share a domain but are each tied to a different filing type and direction, so an agent reading carefully should not misselect.

Naming Consistency4/5

All tools share the secedgar_ prefix and mostly follow a get_/search_/dataframe_ convention. Minor deviations like fetch_frames, compare_companies, and find_holders break the otherwise consistent verb pattern, but the naming remains predictable and readable.

Tool Count4/5

16 tools is slightly above the typical well-scoped range, but the SEC EDGAR domain is broad enough that the count is defensible. Each tool covers a distinct data source or workflow, and the dataframe management pair adds necessary infrastructure rather than bloat.

Completeness4/5

The tool set covers company lookup, full-text filing search, XBRL concepts and frames, financial histories, comparisons, insider trades, institutional holdings, beneficial owners, fund holdings, and material events. Minor gaps exist — e.g., no explicit exhibit-content retrieval and no direct way to list all filings for a company beyond recent submissions — but core workflows are well covered.

Resources