Skip to main content
Glama

List SEC filings for a company

edgar_list_filings
Read-onlyIdempotent

List a company's SEC EDGAR filings newest first, filtered by form type and date range, returning accession numbers and document URLs for retrieving filing documents.

Instructions

List a single company's SEC EDGAR filings (newest first) with form type, filing/report dates, accession number and direct document URLs, filtered by form type and date range, with limit/offset paging. Use to find which filings exist (e.g. "Apple's 10-Ks since 2020", "Tesla 8-Ks this year") and to get an accession_number / document_url for edgar_get_filing_document (or index_url for edgar_get_filing_index to see its exhibits). Not for financial values (use edgar_get_company_facts). Behavior: GET to the data.sec.gov submissions API (throttled to <=5 requests/s). RETURNS: one row per filing; accession_number and document_url feed edgar_get_filing_document (document_url is null when SEC lists no primary document; index_url lists every file). Errors: COMPANY_NOT_FOUND, NOT_FOUND, SEC_FETCH_FAILED (retryable). WHEN NOT TO USE: for document text use edgar_get_filing_document; for XBRL numbers use edgar_get_company_facts; many companies at once -> edgar_get_concept_across_companies (free, one concept) or edgar_batch_export (paid). COST: free - direct sec.gov requests from this MCP server, no APIFY_TOKEN, no Apify billing. PARAMETERS: company: a numeric value is always used as a CIK; text is matched as ticker, then name fragment (first match). formTypes: exact, case-insensitive equality on the form field, so "10-K" does not include amendments - add "10-K/A" explicitly; insider filings are "4", proxies "DEF 14A". since/until: both inclusive and compared with filing_date (not report_date); combine them for a window, e.g. since "2024-01-01" + until "2024-12-31". includeOlder: the default searches only the ~1000 newest filings, so for date windows older than a few years (or for very active filers) set it to true, which adds one SEC request per archive file. Filters are applied before paging: total counts matching filings, rows are newest first, and you continue with offset = nextOffset. EXAMPLE: {"company":"AAPL","formTypes":["10-K"],"since":"2020-01-01","limit":5} -> 5 newest Apple 10-K rows with accession_number and document_url.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company": "<company>"
    },
    "name": "edgar_list_filings"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoOptional page size: items to return, integer 1-200 (default 20). Example: 10
sinceNoOptional inclusive lower bound on filing_date, format YYYY-MM-DD (pattern ^\d{4}-\d{2}-\d{2}$), e.g. "2020-01-01". Default: no lower bound.
untilNoOptional inclusive upper bound on filing_date, format YYYY-MM-DD (pattern ^\d{4}-\d{2}-\d{2}$), e.g. "2024-12-31". Default: no upper bound.
offsetNoOptional zero-based number of items to skip, integer >= 0 (default 0); pass nextOffset from the previous response, e.g. 20
companyYesRequired, 1-200 chars. Ticker ("AAPL", case-insensitive), CIK of 1-10 digits ("320193" or "0000320193"; any SEC filer, even without a ticker) or registrant-name fragment ("Apple"; the first SEC ticker-map match is used). Call edgar_resolve_company first if a name is ambiguous.
formTypesNoOptional, default omitted = all forms. 1-20 exact SEC form types (case-insensitive equality; amendments like "10-K/A" must be listed separately). Example: ["10-K","10-Q"], ["8-K"], ["4"], ["DEF 14A"]
includeOlderNoOptional boolean, default false. true also loads the archived filings older than the ~1000 most recent (one extra SEC request per archive file). Example: true

Output Schema

NameRequiredDescriptionDefault
metaNoTool-specific context (company, source_url, ...)
countYesNumber of items in this page
itemsYesResult rows for this page
totalYesTotal items matching the filters (before paging)
offsetYesOffset of the first item in this page
hasMoreYesTrue if more items exist after this page
nextOffsetYesOffset to pass for the next page, or null

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv1.2.2
    • changedInput schema / properties / company / description
      Previous value: -"Ticker (\"AAPL\"), CIK (\"320193\", zero-padding optional) or company name fragment (\"Apple\"); best match is used. Call edgar_resolve_company first if the name is ambiguous."New value: +"Required, 1-200 chars. Ticker (\"AAPL\", case-insensitive), CIK of 1-10 digits (\"320193\" or \"0000320193\"; any SEC filer, even without a ticker) or registrant-name fragment (\"Apple\"; the first SEC ticker-map match is used). Call edgar_resolve_company first if a name is ambiguous."
    • changedInput schema / properties / formTypes / description
      Previous value: -"Exact form types to keep, e.g. [\"10-K\",\"10-Q\"], [\"8-K\"], [\"4\"]. Case-insensitive. Omit for all forms."New value: +"Optional, default omitted = all forms. 1-20 exact SEC form types (case-insensitive equality; amendments like \"10-K/A\" must be listed separately). Example: [\"10-K\",\"10-Q\"], [\"8-K\"], [\"4\"], [\"DEF 14A\"]"
    • changedInput schema / properties / includeOlder / description
      Previous value: -"Also search filings older than the ~1000 most recent (default false)"New value: +"Optional boolean, default false. true also loads the archived filings older than the ~1000 most recent (one extra SEC request per archive file). Example: true"
    • changedInput schema / properties / limit / description
      Previous value: -"Optional page size: items to return, integer 1-200 (default 20)"New value: +"Optional page size: items to return, integer 1-200 (default 20). Example: 10"
    • changedInput schema / properties / offset / description
      Previous value: -"Number of items to skip for paging (default 0); use nextOffset from the previous response"New value: +"Optional zero-based number of items to skip, integer >= 0 (default 0); pass nextOffset from the previous response, e.g. 20"
    • changedInput schema / properties / since / description
      Previous value: -"Optional inclusive lower bound on filing_date, format YYYY-MM-DD, e.g. \"2020-01-01\". Default: no lower bound."New value: +"Optional inclusive lower bound on filing_date, format YYYY-MM-DD (pattern ^\\d{4}-\\d{2}-\\d{2}$), e.g. \"2020-01-01\". Default: no lower bound."
    • changedInput schema / properties / until / description
      Previous value: -"Optional inclusive upper bound on filing_date, format YYYY-MM-DD, e.g. \"2024-12-31\". Default: no upper bound."New value: +"Optional inclusive upper bound on filing_date, format YYYY-MM-DD (pattern ^\\d{4}-\\d{2}-\\d{2}$), e.g. \"2024-12-31\". Default: no upper bound."
  2. Addedv1.2.1

TDQS

A4.9/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description goes well beyond: it discloses the upstream endpoint, a <=5 req/s throttle, the extra SEC request cost of includeOlder, filter-before-paging semantics, and named error codes with a retryable flag. This is exactly the behavioral context annotations cannot carry.

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?

Front-loaded and organized into labeled sections (Behavior, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE) with the example last. It is on the long side and the sibling alternatives are effectively repeated (edgar_get_company_facts appears in both the purpose line and WHEN NOT TO USE), which is minor redundancy but not waste.

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 7-parameter, paginated, free-of-charge list tool with an output schema, every gap is closed: resolution rules, filter semantics, paging continuation (offset = nextOffset), return shape, error handling, and cost/token requirements. Nothing an agent needs to invoke it correctly is missing.

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 coverage is already 100% (baseline 3), but the description adds real meaning: the company disambiguation rule (numeric = CIK, text = ticker then name fragment), the fact that formTypes is exact case-insensitive equality so 10-K excludes 10-K/A, that since/until bind filing_date not report_date, and how includeOlder changes cost. This clearly exceeds the schema.

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?

Specific verb (List) plus resource (SEC EDGAR filings for a single company), with scope details (newest first, what fields come back) and explicit negative framing that names the sibling tools it is not (edgar_get_company_facts, edgar_get_filing_document). An agent can distinguish it from every sibling on name alone.

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?

Provides an explicit 'Use to find which filings exist' section, a dedicated 'WHEN NOT TO USE' block that routes document text to edgar_get_filing_document, XBRL numbers to edgar_get_company_facts, and multi-company queries to edgar_get_concept_across_companies / edgar_batch_export. Both the when and the when-not with named alternatives are present.

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