Skip to main content
Glama

secedgar-mcp-server

by io.github.cyanheads

Secedgar Compare Companies

secedgar_compare_companies
Read-onlyIdempotent

Compare 2-10 named companies across 1-8 XBRL concepts, aligned on calendar periods. This is the middle shape between secedgar_get_financials (one company, one concept, full history) and secedgar_fetch_frames (one concept, one period, every reporting company) — reach for it when the question names the companies. One companyfacts read per company, resolved through the same frame dedup and tag priority as secedgar_get_financials so the numbers agree. Balance-sheet and entity-info concepts are filed as point-in-time values and align on the calendar year (annual) or quarter (quarterly) their snapshot falls in, so they sit in the same matrix as income-statement lines. The inline matrix covers the most recent periods up to periods, trimmed further when companies x concepts x periods is too large to return in one response; the full aligned series is materialized as df_ for growth rates and spreads via secedgar_dataframe_query. A company that fails to resolve is reported in failed_companies and the comparison proceeds with the rest, and a company that does not report a concept is reported in gaps with the tags that were tried — never interpolated or zero-filled. Off-calendar filers and unit mismatches are surfaced in caveats rather than silently mixed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
periodsNoUpper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query.
conceptsYesConcepts to compare — friendly names like "revenue" or "net_income" (discover them with secedgar_search_concepts) or raw XBRL tags.
taxonomyNoXBRL taxonomy to resolve concepts under. Use ifrs-full only when every company in the list reports under IFRS; mixing IFRS and US GAAP filers in one call resolves them all under the same taxonomy.us-gaap
companiesYesCompanies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs.
period_typeNoAlign on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats.annual

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe periods cap applied.
gapsNoCompany-concept pairs with no data. Deliberately explicit — a missing value is never interpolated or zero-filled.
cellsNoInline matrix values, covering the periods listed in periods[].
errorNoPresent when the call failed. Absent on success.
shownNoNumber of periods shown inline.
caveatsNoComparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept whose values stop at least two full years behind the rest of that company's reporting (either an XBRL tag SEC has retired, or a current tag the filer stopped using), period ends that differ inside one aligned period, and concepts whose unit differs across companies. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging.
datasetNoCanvas dataframe holding the full aligned series across every period, not just the inline window. Columns match cells[]. Absent when canvas is unavailable.
periodsNoCalendar period keys covered by the inline matrix, newest first. Shorter than the requested periods when the cell count forced the window to shrink — the enrichment trailer reports the drop.
conceptsNoConcepts covered, in the order supplied.
taxonomyNoTaxonomy the concepts were resolved under, echoed from input.
companiesNoCompanies included in the comparison.
truncatedNoTrue when the aligned series has more periods than the inline matrix shows.
period_typeNoPeriod alignment used, echoed from input.
failed_companiesNoCompanies excluded from the matrix. The comparison proceeds with the rest rather than failing the whole call.

TDQS

A4.6/5.0
Behavior4/5

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

Annotations provide readOnlyHint=true, openWorldHint=true, and idempotentHint=true, which already establish the safety profile. The description adds substantial behavioral context beyond these: it discloses that balance-sheet concepts align on point-in-time snapshot periods, that companies failing to resolve are excluded from results without halting, that gaps are never interpolated or zero-filled, and that off-calendar filers and unit mismatches are surfaced in caveats. This is rich behavioral disclosure. It falls just short of 5 because it doesn't explicitly state that it performs read-only operations or describe the return structure (though the output schema covers that).

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, but it is front-loaded with the core purpose and positioning, then flows into behavioral nuances. Every sentence carries meaningful information: scope, placement among siblings, read semantics, period alignment, matrix behavior, failure handling, gap handling, and caveats. It is not overly verbose for its content density, though it could hypothetically be split into two paragraphs for readability. The front-loading of the purpose and sibling distinction is exemplary.

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?

For a multi-company, multi-concept comparison tool with 5 parameters, an output schema, and detailed annotations, the description covers all necessary operational aspects: scope limits, alignment behavior, failure handling, gap reporting, interpolation policy, period trimming, and the dataframe mechanism for further analysis. The only potentially missing element is an explicit statement of what the return payload looks like, but the output schema exists to convey that. Given the complexity and the richness of the surrounding structured metadata, the description is complete.

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 description coverage is 100%, so the schema already documents all five parameters thoroughly. The description adds extra value beyond the schema by explaining the semantics of periods — that it is 'not a guarantee' and that the inline window drops older periods when the product is too large — and by stating that all parameters map to the matrix dimensions. The description also clarifies that a failed company is reported in failed_companies rather than aborting. Since the schema is comprehensive and the description enriches meaning, a 4 is appropriate.

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 precise verb-resource statement: 'Compare 2-10 named companies across 1-8 XBRL concepts, aligned on calendar periods.' It then explicitly positions itself as the middle shape between secedgar_get_financials and secedgar_fetch_frames, making the distinction from siblings unmistakable. This is a clear, specific purpose with no ambiguity.

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 explicitly names the sibling tools it sits between and states 'reach for it when the question names the companies.' It also instructs to use ifrs-full 'only when every company in the list reports under IFRS' and warns against mixing IFRS and US GAAP filers. The periods parameter description adds further guidance on when dropped periods stay queryable via secedgar_dataframe_query. This is thorough when-to-use and when-not-to-use guidance.

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