Skip to main content
Glama
brechanbech

SEC EDGAR MCP

by brechanbech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Remote

Cross-Company XBRL Frames

sec_xbrl_frames
Read-only

Compare a financial metric across all SEC filers for a given period and rank results by value, with paging and instant/duration concept handling.

Instructions

Cross-company comparison — get a specific financial metric for all companies in a given period. For example, compare revenue across all filers for 2024. Returns entries sorted by value, largest first, 20 by default; 'total' says how many filers reported, and passing 'next_offset' back as 'offset' pages down the ranking. Note: 'instant' concepts (balance-sheet items measured at a point in time, e.g. Assets, Liabilities, StockholdersEquity, CashAndCashEquivalentsAtCarryingValue, CommonStockSharesOutstanding) require instant=true with a quarterly period. 'Duration' concepts (flow items measured over a period, e.g. Revenues, NetIncomeLoss, OperatingIncomeLoss, EarningsPerShareBasic) require instant=false (the default).

Input Schema

NameRequiredDescriptionDefault
unitNoUnit: 'USD' (default), 'pure', 'shares', or a compound unit like 'USD/shares' for per-share concepts (e.g. EarningsPerShareBasic).USD
limitNoNumber of entries to return, largest value first (default 20, max 300)
offsetNoNumber of entries to skip, for paging down the ranking (default 0). Pass the previous response's 'next_offset'.
periodYesPeriod: year like '2024' (annual, duration concepts only), or quarter like '2024Q1'
conceptYesXBRL concept name, e.g. 'Revenues', 'NetIncomeLoss', 'Assets'
instantNoSet true for instant/balance-sheet concepts measured at a point in time (must be combined with a quarterly period). Default false.
taxonomyNoTaxonomy: 'us-gaap' (default) or 'ifrs-full'us-gaap

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.7.0
    • changedInput schema / properties / limit / description
      Previous value: -"Number of top entries to return (default 20)"New value: +"Number of entries to return, largest value first (default 20, max 300)"
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "description": "Number of entries to skip, for paging down the ranking (default 0). Pass\nthe previous response's 'next_offset'.",
+  "format": "uint64",
+  "minimum": 0,
+  "type": "integer"
+}
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly and openWorld, so the bar is lower, but the description adds genuinely non-obvious behavior: results are ranked by value descending, default 20, a 'total' count of reporting filers, and that next_offset must be passed back as offset to page. The instant/duration taxonomy rule is domain knowledge an agent could not infer. Minor gap: only the 'total' field of the response shape is described.

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?

Purpose and example are front-loaded, then return behavior, then the paging mechanics, then the instant caveat — a sensible order. A few clauses repeat schema facts (default 20, offset semantics), which is mild waste in an otherwise dense, low-fluff paragraph.

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 no output schema, the description correctly takes on the responsibility of explaining 'total' and 'next_offset', and it pre-empts the most likely failure mode (using a balance-sheet concept with instant=false). It stops short of describing the remaining per-entry fields (entity identity, value, unit), leaving a small hole for a 7-parameter ranking tool.

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 a 3 is the baseline, but the description earns above that by explaining the semantic coupling between concept type and the instant parameter, with named examples (Assets, Liabilities vs Revenues, NetIncomeLoss), and by noting that annual periods only apply to duration concepts — meaning not stated in the schema's period field.

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?

Opens with a specific verb and scope: 'get a specific financial metric for all companies in a given period', and the 'cross-company' framing cleanly separates it from single-entity siblings like sec_financial_concept and sec_company_facts. The concrete example ('compare revenue across all filers for 2024') removes any ambiguity about what a call produces.

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?

Gives an explicit use case and, more usefully, states the selection rule for the instant flag: instant concepts require instant=true plus a quarterly period, duration concepts use the default. It does not name a sibling tool for single-company lookups, so the routing guidance is contextual rather than exhaustive.

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