Stockfacts

Company filings (10-K, 10-Q, 8-K)

list_filings

Read-onlyIdempotent

A company's SEC filings, or the whole market's: 10-K (annual report, including 10-KT), 10-Q (quarterly report), 8-K (current report), 20-F and 40-F (foreign companies' annual reports), each with its amendments (/A), newest first, since 2009. Each row: accession, form, the 8-K item codes with their descriptions (for example 2.02 Results of operations, 4.02 Non-reliance on previously issued financial statements, 5.02 Departure or appointment of directors or officers), filed_date, accepted_at (ISO 8601 UTC), period_of_report (the period end for 10-K and 10-Q, the event date for 8-K), the company with its ticker, url (the company's filings page on livermore.club), sec_url (the main document on SEC.gov) and index_url (the SEC filing index with all exhibits). Livermore does not store the text of filings. To learn what an 8-K reports, or a 10-K or 10-Q's business description, risk factors or management's discussion, fetch sec_url; the press release of an 8-K with Item 2.02 is usually exhibit EX-99.1, listed on index_url. With ticker or cik the company's whole history is searchable (filings under a former CIK included). Without either, the query covers the whole market (companies with a ticker) and at most 30 days of filing dates (default: the last 7 days); note says when the range was narrowed. items keeps 8-K filings with any of the given item codes. At most 200 rows per call; use page.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_filings"
  }
}

Input Schema

Name	Required	Description
`to`	No	Latest filing date, YYYY-MM-DD, inclusive.
`cik`	No	The company's SEC CIK instead of a ticker, e.g. 0000320193. Give ticker or cik, not both.
`from`	No	Earliest filing date, YYYY-MM-DD (US Eastern).
`page`	No	Page number starting at 1; each page has `limit` rows. Check has_more.
`forms`	No	Form types, each including its amendments (/A); 10-K also includes 10-KT. Default all, e.g. ["10-K","10-Q"].
`items`	No	8-K item codes; a filing matches when it has any of them, e.g. ["4.01","4.02","5.02"]. Only 8-K and 8-K/A filings have items.
`limit`	No	Maximum rows to return (1-200, default 25).
`ticker`	No	Only this company's filings, whole history (including filings under a former CIK).

Output Schema

Name	Required	Description	Default
`url`	Yes
`note`	Yes
`page`	Yes
`rows`	Yes
`limit`	Yes
`scope`	Yes
`company`	Yes
`filters`	Yes
`has_more`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 8, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the bar is met; the description still adds substantial behavior: newest-first ordering, data since 2009, the 30-day market cap with a note when the range is narrowed, a 200-row-per-call limit with pagination, and that filing text is not stored. These are operational constraints an agent needs and none duplicate the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The material is front-loaded with the resource, but it is delivered as one dense run-on paragraph mixing scope, form taxonomy, output fields, retrieval guidance, and pagination. The mid-sentence catalog of 8-K item codes with descriptions is heavy for a description, and a few structural breaks would make it far easier to parse.

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?

Despite an output schema existing, the description explains the row shape (accession, form, item codes, filed_date, accepted_at, period_of_report, ticker, url/sec_url/index_url) and how to retrieve underlying text, leaving no ambiguity for an 8-parameter, zero-required tool. Combined with the annotations, nothing needed 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.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so 3 is the baseline; the description goes further by explaining that items matches 8-K filings containing any of the given codes (and only 8-K/8-K-A have items), that forms includes amendments, and that ticker/cik should not both be given. It adds meaningful semantics over the schema, though much of the row-field detail belongs to the output shape rather than inputs.

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 names a specific resource (SEC filings: 10-K, 10-Q, 8-K, 20-F, 40-F with amendments) and both scopes (a single company or the whole market). It is immediately distinguishable from siblings like get_ownership_filings, get_financials, or get_major_holders, which cover different datasets. An agent does not need to open the schema to know what this returns.

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?

It gives clear conditional guidance: with ticker/cik the full company history is searchable (including former CIKs), without either the query covers the market but is capped at 30 days (default 7). It also directs the agent to sec_url / index_url for the actual filing text since Livermore stores none. It does not, however, name any sibling tool as an alternative when the agent wants ownership or financials instead, so routing between siblings is left implicit.

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

All Stockfacts tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?