Skip to main content
Glama

secedgar-mcp-server

by io.github.cyanheads

Get Material Events

secedgar_get_material_events
Read-onlyIdempotent

Retrieve a company's 8-K filings with their item codes decoded, optionally filtered to specific items. 8-K item codes are how material events are actually scoped — 1.01 material agreements, 2.02 results of operations, 4.02 non-reliance on previously issued financials, 5.02 officer and director departures — and filtering by them is narrower than any form-level filter in secedgar_search_filings or secedgar_company_search, neither of which can see items. Each row carries the accession number and primary document for secedgar_get_filing; press releases usually ride as EX-99 exhibits rather than in the primary document. Two numbering regimes exist: filings from 2004-08-23 onward use the x.xx codes, earlier ones use single integers (12 was the old results-of-operations item, 9 the old Regulation FD item), and both are accepted as filters and decoded in the response. A date window reaches filings older than the recent submissions window by paging into the archive. The full filtered set is materialized as a dataframe for item-distribution analysis over time.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
itemsNoItem codes to filter to; a filing matches when it reports any of them. Omit to return every 8-K. Current-regime codes are dotted ("2.02"), pre-2004-08-23 codes are bare integers ("12"), and the two vocabularies do not overlap — filtering on "2.02" alone returns nothing from a pre-2004 window, so pair them ("2.02", "12") when the window spans the changeover. Full decode table: the secedgar://filing-types resource.
limitNoFilings returned inline, newest first. The full filtered set is materialized as a dataframe when it exceeds this and a canvas is available. Default 20.
companyYesCompany ticker symbol (e.g. "AAPL"), name (e.g. "Apple"), or CIK number (e.g. "320193"). Ticker is the exact lookup; name search matches current and former names.
filed_afterNoOnly include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches 8-K filings that predate the ~1000-filing recent window.
filed_beforeNoOnly include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit cap applied.
cikNoCentral Index Key of the resolved company, zero-padded to 10 digits.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of filings shown inline.
noticeNoGuidance when nothing matched — distinguishes an empty date window from an items filter that excluded everything.
datasetNoCanvas dataframe holding the full filtered 8-K set. Item codes ride as a comma-separated `item_codes` column, so item-frequency-over-time queries split it (`unnest(string_split(item_codes, ','))`). Absent when the result fits inline, canvas is unavailable, or materialization failed.
filingsNoMatching filings, newest first, capped at limit.
truncatedNoTrue when the inline filings list was capped.
company_nameNoSEC-conformed company name.
items_filterNoThe item codes filtered on, echoed. Absent when no filter was applied.
total_matchedNoFilings matching every applied filter across the whole scan, which may exceed limit and the inline list.
total_8k_scannedNo8-K filings inside the date window before the items filter — compare against total_matched to see how much the items filter removed.
item_distributionNoCount of the 8-K filings scanned in the date window carrying each item code, before the items filter. Empty when no 8-K filings were scanned.
history_scanned_throughNoOldest filing date reached by the scan (YYYY-MM-DD). Older filings were not examined: the recent window caps at ~1000 filings, and archive pages are fetched only when a date filter or an under-filled result requires them. Absent when no filings were scanned.

TDQS

A4.7/5.0
Behavior4/5

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

Annotations cover readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is already known. The description adds valuable behavioral context: that the full filtered set is materialized as a dataframe when it exceeds the inline limit, that date windows page into the older archive, and that press releases ride as EX-99 exhibits rather than the primary document. These details go beyond what annotations provide. It lacks exhaustive disclosure (e.g., what the output schema looks like), but given the presence of an output schema and annotations, a 4 is warranted for the meaningful additions without contradiction.

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 a single dense paragraph and is front-loaded with the purpose, with the most meaningful scoping detail (item codes) stated early. It uses concrete examples efficiently. It is longer than a minimal description, but every sentence adds new information (e.g., date-regime changeover, dataframe materialization, EX-99 note). Slight clutter in the first sentence's long list of examples, but it earns a 4 for force and efficiency without being bloated.

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 tool is moderately complex: it has 5 parameters, a nested items enum, and an output schema. The description closes the gaps that the schema alone leaves open—how item codes relate to 8-K scoping, the changeover date, paging behavior for old filings, and the return context (dataframe for analysis). Given the output schema exists and the description covers the behavioral edge cases, nothing an agent needs to call this correctly is missing. It is complete for its complexity.

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?

Schema description coverage is 100%, so the schema already documents each parameter. But the tool description and param descriptions add significant value: they explain the pragmatic meaning of 'items' (decoding example codes and overlap between regimes), clarify the comparative semantics ('Ticker is the exact lookup; name search matches current and former names'), and detail the archive-paging behavior of date filters. This is not repetition—it extends the schema with real-world usage notes, so it earns a 5 despite the high schema coverage baseline of 3.

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 uses a specific verb ('Retrieve'), a clear resource ('a company's 8-K filings'), and a differentiator ('with their item codes decoded'). It explicitly distinguishes this tool from siblings like secedgar_search_filings and secedgar_company_search by noting they cannot see item-level scoping. The first paragraph crisply states the tool's purpose and names the exact functionality, making the boundary unambiguous.

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 excellent usage guidance: it says 8-K item codes are how material events are scoped, it excludes alternatives ('filtering by them is narrower than any form-level filter in secedgar_search_filings or secedgar_company_search'), it names the sibling for fetching documents (secedgar_get_filing), and it explains the dual numbering regimes, including when to pair codes across the 2004-08-23 changeover. This is explicit when/when-not guidance with named alternatives.

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