Skip to main content
Glama

secedgar-mcp-server

by io.github.cyanheads

Secedgar Fetch Frames

secedgar_fetch_frames
Read-onlyIdempotent

Fetch SEC XBRL frames for one concept × one period across all reporting companies. Inline response returns a page of the ranked companies — start at the top or pass offset/next_offset to walk further down the ranking; the full frames response (all reporters) is materialized as df_ when a canvas is available, queryable via secedgar_dataframe_query. Accepts friendly names like "revenue" or "assets" (discover via secedgar_search_concepts) or raw XBRL tags. One call hits one XBRL tag — when a friendly name maps to multiple same-meaning tags, the response's unqueried_tags lists the others; call again per tag and UNION/COALESCE in SQL with an analysis-specific priority (e.g. SalesRevenueGoodsNet is goods-only). The response's related_tags separately flags alternate-DEFINITION tags a meaningful share of filers use as their primary line (e.g. cash incl. restricted cash, equity incl. noncontrolling interest) — a whole-universe screen on the base tag silently omits those filers; query them separately, but do not blindly union (the semantics differ). Response includes value_distribution and period_end_range to flag XBRL scale-factor anomalies and fiscal-year mixing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNoSort direction. "desc" for highest values first (typical for revenue, assets). "asc" for lowest values.desc
unitNoUnit of measure. Use "USD-per-shares" (or equivalently "USD/shares") for EPS, "shares" for share counts, "pure" for ratios. Ignored when concept resolves to a friendly name with a known unit.USD
limitNoNumber of companies to return.
offsetNoRank to start the page at, 0-based, over the sorted frame. Pass the next_offset from the previous response to read the next page — the ranked list is fetched whole and sliced, so paging is stable and gap-free. An offset at or past total_companies returns an empty page.
periodYesCalendar period. Use duration periods (no I suffix) for income/cash-flow items: "CY2023" (full year), "CY2024Q2" (single quarter). Use instant periods (I suffix) for balance-sheet items: "CY2023Q4I" (snapshot at Q4 close).
conceptYesFinancial concept — same friendly names as secedgar_get_financials (e.g., "revenue", "assets", "eps_basic") or raw XBRL tag.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit cap applied.
dataNoRanked companies for this metric.
unitNoUnit of measure used for the lookup (always normalized to dashed form, e.g. "USD-per-shares").
errorNoPresent when the call failed. Absent on success.
labelNoHuman-readable concept label.
shownNoNumber of companies shown inline.
noticeNoGuidance when the requested offset lands past the end of the ranked list.
offsetNoRank the returned page starts at, 0-based — the effective offset applied.
periodNoCalendar period the data was fetched for, echoed from input.
caveatsNoData-completeness warnings specific to this query. Currently populated for duration periods 'CY####Q[1-4]', where SEC XBRL omits filers' fiscal Q4 (reported only as the 10-K residual) — affected filers are silently absent from the frame. Empty for annual ('CY####') and instant ('CY####Q#I') periods, where the underlying facts exist and the frame is complete.
conceptNoXBRL tag the data was actually fetched against (after resolving any friendly name).
datasetNoCanvas dataframe handle holding the full frames response. Absent when canvas is unavailable or materialization failed.
truncatedNoTrue when the inline data[] was capped by limit.
next_offsetNoOffset to pass on the next call to continue down the ranking. Absent on the last page (no companies remain past this one).
related_tagsNoAlternate-DEFINITION XBRL tags (distinct from same-meaning `unqueried_tags`) that a meaningful share of filers use as their primary line for this metric — e.g. `cash` filers reporting `CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents` (incl. restricted cash), `equity` filers reporting `StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest` (incl. noncontrolling interest). These filers are NOT in `data` or the dataframe, so a whole-universe screen on the base tag silently under-counts. To recover them, run a separate fetch_frames against the alternate tag — do NOT blindly UNION (definitions differ; you would mix or double-count). Empty when the concept has no known high-coverage alternate.
unqueried_tagsNoOther same-meaning XBRL tags in the friendly-name mapping that this call did NOT query (historical/variant spellings of the same metric). Empty for raw tags or single-tag concepts — for alternate-DEFINITION tags some filers use instead, see `related_tags`. For "revenue" this typically lists `Revenues`, `SalesRevenueNet`, `SalesRevenueGoodsNet` — filers reporting under legacy variants are absent from `data`; call again per tag and UNION/COALESCE in SQL to recover them.
total_companiesNoTotal companies reporting this metric for this period.
period_end_rangeNoRange of period_end dates across the frame. SEC normalizes to calendar periods but filers report against their own fiscal year-ends, so a "CY2023" duration frame can contain period_ends from 2023-01-31 (January-FY filers like Walmart) to 2024-12-31 (calendar-FY filers reported late). Wide ranges mean cross-comparison mixes fiscal periods.
value_distributionNoDistribution stats across the full frame, computed during materialization. Use `max_to_p95_ratio` as the primary outlier signal — it catches scale-factor anomalies even when median is 0 or negative.

TDQS

A4.6/5.0
Behavior5/5

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

The description discloses critical behaviors beyond annotations: paging is stable and gap-free due to whole-list slicing, friendly names may map to multiple tags via related_tags, and value_distribution/period_end_range flag anomalies. This transparency helps agents understand edge cases without needing to probe the tool.

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?

The description is front-loaded with the primary purpose, but it runs as a single long sentence with many embedded clauses. While it contains valuable detail, the structure could be broken into bullet points for easier scanning, yet it remains efficient given the complexity.

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 the tool's complexity, the description covers paging, concept resolution, unit behavior, and post-processing signals, making it self-sufficient. The output schema is present, so not explaining return values is acceptable, and the description sufficiently orients the agent.

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?

The schema already provides thorough parameter descriptions, but the tool description adds extra meaning such as duration vs. instant period usage, unit handling with friendly concepts, and the offset paging semantics. These additions go beyond the schema coverage and clarify subtle aspects.

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 clearly states the tool fetches SEC XBRL frames for one concept and one period across companies, with a specific verb and target. It distinguishes itself by emphasizing the ranked, cross-company nature and paging mechanism, which separates it from other financial data tools.

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?

The description provides clear context for when to use this tool, such as when needing a ranked list of companies for a given concept and period, and mentions friendly names and raw tags. It also hints at alternatives like using secedgar_dataframe_query for full responses, but does not explicitly state exclusions versus all sibling tools.

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