edgar-search-mcp

Overview Schema Source Related Servers Discussions Admin

list_filings

Read-only

Fetch a company's SEC EDGAR submission filing rows in SEC order, with filters for form type, as-of date, amendments, and result limit.

Instructions

Rows of a company's submissions filing tables, in the SEC's order.

The order is the SEC's: the recent table, then each older file in the order filings.files lists them. Nothing is re-sorted or merged. form is compared literally ("10-K" is not "10-k"); None (the default) keeps every form; include_amendments also keeps "/A". as_of (YYYY-MM-DD) keeps rows whose filingDate is on or before it; a row with no such date is left out and named in warnings. Up to limit rows are returned.

Each filing has record, every column under the SEC's own key (accessionNumber, filingDate, reportDate, acceptanceDateTime, form, primaryDocument, items, ...); url, the primary document's address built from the CIK, accession number and primaryDocument; source, the file and row index the record came from; and numbers_as_text, where in record a number is kept as its text. An older file that cannot be read is an error, never a shorter list. complete is false when a warning says a row was left out or cut short.

Input Schema

Name	Required	Description	Default
`form`	No
`as_of`	No
`limit`	No
`cik_or_ticker`	Yes
`include_amendments`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.0.0Oct 29, 2026

addedInput schema / properties / form / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / form / default
```
Previous value: -"10-K"New value: +null
```
removedInput schema / properties / form / type
```
Removed value: -"string"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "envelope": {
+      "properties": {
+        "contract_version": {
+          "const": "1.0"
+        },
+        "representation": {
+          "enum": [
+            "source",
+            "source_records",
+            "parsed_source",
+            "transformed"
+          ]
+        },
+        "returned_at": {
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+          "type": "string"
+        },
+        "sources": {
+          "items": {
+            "$ref": "#/$defs/source"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "unresolved": {
+          "items": {
+            "$ref": "#/$defs/unresolved"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "contract_version",
+        "representation",
+        "sources",
+        "returned_at"
+      ],
+      "type": "object"
+    },
+    "paths": {
+      "items": {
+        "items": {
+          "type": [
+            "string",
+            "integer"
+          ]
+        },
+        "type": "array"
+      },
+      "type": "array"
+    },
+    "source": {
+      "properties": {
+        "cache_hit": {
+          "type": "boolean"
+        },
+        "frozen": {
+          "type": "boolean"
+        },
+        "retrieved_at": {
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+          "type": "string"
+        },
+        "sha256": {
+          "pattern": "^[0-9a-f]{64}$",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "url": {
+          "pattern": "^https://(www|data|efts)\\.sec\\.gov/",
+          "type": "string"
+        }
+      },
+      "required": [
+        "url",
+        "retrieved_at",
+        "frozen",
+        "cache_hit"
+      ],
+      "type": "object"
+    },
+    "unresolved": {
+      "properties": {
+        "reason": {
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "reason"
+      ],
+      "type": "object"
+    }
+  },
+  "$id": "edgar://contract/1.0/list_filings",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    {
+      "$ref": "#/$defs/envelope"
+    },
+    {
+      "properties": {
+        "filings": {
+          "items": {
+            "properties": {
+              "numbers_as_text": {
+                "$ref": "#/$defs/paths"
+              },
+              "record": {
+                "required": [
+                  "accessionNumber",
+                  "form",
+                  "filingDate"
+                ],
+                "type": "object"
+              },
+              "source": {
+                "required": [
+                  "file",
+                  "index"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "record",
+              "url",
+              "source",
+              "numbers_as_text"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "filters": {
+          "type": "object"
+        },
+        "representation": {
+          "const": "source_records"
+        }
+      },
+      "required": [
+        "cik",
+        "filters",
+        "count",
+        "limit_reached",
+        "filings",
+        "complete",
+        "warnings"
+      ]
+    }
+  ],
+  "type": "object"
+}

First observedv0.1.0Oct 29, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations only cover readOnlyHint and openWorldHint, and the description adds real behavioral context on top: ordering is never re-sorted or merged, an unreadable older file is an error rather than a short list, `warnings` names dropped rows, and `complete` reflects truncation or omissions. It stops short of permission, rate-limit, or pagination-cost detail, but the failure and truncation semantics are unusually well disclosed.

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 ordering constraint is front-loaded before filtering detail, and backticked identifiers make it scannable despite the dense run-on punctuation. Some sentences (the back-to-back semicolon clauses around `form`/`as_of`) could be split for readability, but no sentence is filler.

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?

For a five-parameter tool with warnings, a `complete` flag, and dynamic SEC column keys, the description covers ordering, filtering, error behavior, and truncation well. The `record`/`url`/`source` expansion is partly redundant given an output schema exists, while the unexplained required `cik_or_ticker` is the remaining real gap.

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 0%, so the description carries the full load and does most of it: `form` is a literal comparison with None keeping everything, `include_amendments` also admits "<form>/A", `as_of` is YYYY-MM-DD with an on-or-before rule plus exclusion-to-warnings, and `limit` caps rows. The required `cik_or_ticker` parameter is never described at all, leaving the one mandatory input unstated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete statement of what is returned: rows of a company's submissions filing tables, in the SEC's order. The resource and scope are unmistakable, but the definition never names or distinguishes itself from siblings such as search_filings or list_filing_documents, so an agent has no in-description routing signal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the filter semantics (form literal matching, include_amendments, as_of cutoff) rather than stated as when-to-use guidance, and no alternative tool is ever named. Absent any exclusions or comparison to search_filings, the agent must infer the choice from sibling names alone.

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

Deploy Server