StockLens

Overview Schema Source Related Servers Discussions Admin

get_us_filings

Read-onlyIdempotent

Retrieve US SEC filings for a ticker, filter by form type, and paginate through EDGAR coverage to get accession numbers and direct URLs to original documents.

Instructions

US SEC filings — SEC EDGAR 공시 목록 (accession number·원문 URL 포함).

"AAPL 10-K", "RIVN latest filings", "8-K", "SEC filing" 같은 질문에 사용합니다. 본문·exhibit 를 읽으려면 결과의 accession number 로 get_us_filing_detail 을 부르세요.

기본 조회는 SEC 의 최근 구간(최대 1000건)입니다. 그보다 오래된 공시는 구간 파일로 나뉘어 있고, 결과 메타의 coverage.older_pages 에 구간 목록 (이름·기간·건수)이 옵니다. page= 에 그 이름을 넣어 구간을 옮기고, 한 구간이 limit 보다 크면 coverage.next_offset 을 offset= 에 넣어 이어서 조회하세요. 완전한 검색의 종료 조건은 coverage_complete=true (현재 구간을 끝까지 봤고 older_pages 도 없음)이지, older_pages 가 비었다는 것만이 아닙니다.

SEC 는 발행사를 티커가 아니라 CIK 로 식별합니다. GOOGL/GOOG 같은 클래스주는 같은 발행사로 정규화되어 같은 공시 집합이 나오고, 요청 티커는 메타에 보존됩니다.

Args: ticker: US 티커 limit: 표시할 공시 건수 (기본 15, 최대 100) forms: 공시 유형 필터 (예: ["10-Q", "8-K"]). 비우면 전체. page: 구간 파일 이름 (coverage.older_pages[].name). 비우면 최근 구간. offset: 현재 구간 안에서 건너뛸 건수 (coverage.next_offset 값). 기본 0.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No
`forms`	No
`limit`	No
`offset`	No
`ticker`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv1.1.3Sep 17, 2026
- removedInput schema / properties / forms / anyOf
```
Removed value: -[
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / forms / default
```
Removed value: -null
```
- addedInput schema / properties / forms / items
```
Added value: +{
+  "type": "string"
+}
```
- addedInput schema / properties / forms / type
```
Added value: +"array"
```
- removedInput schema / properties / limit / default
```
Removed value: -15
```
- removedInput schema / properties / offset / default
```
Removed value: -0
```
- removedInput schema / properties / page / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / page / default
```
Removed value: -null
```
- addedInput schema / properties / page / type
```
Added value: +"string"
```

Changed3 schema fields changedv1.0.1Sep 13, 2026

addedInput schema / properties / forms

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Forms"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "title": "Offset",
+  "type": "integer"
+}

addedInput schema / properties / page

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Page"
+}

First observedv0.4.0May 29, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already convey read-only/idempotent behavior, and the description adds substantial operational context beyond them: SEC identifies issuers by CIK, share classes like GOOGL/GOOG normalize to the same issuer set, the requested ticker is preserved in metadata, and full search completion requires coverage_complete=true. It also discloses the segmented older-page mechanism.

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

Conciseness5/5

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

The description is information-dense but well structured, front-loading purpose and example queries before explaining pagination and parameters. Every sentence earns its place, and there is no redundant repetition of annotations or schema.

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 tool with pagination, CIK normalization, form filtering, and a companion detail tool, the description covers all invocation-relevant behavior. It provides the termination condition, segment navigation, parameter defaults, and routing to get_us_filing_detail, so an agent can call it correctly without additional context.

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 description coverage is 0%, but the Args section documents every parameter in detail: ticker, limit with default and max, forms with examples, page as a segment file name, and offset with its default. This fully compensates for the schema's lack of parameter descriptions.

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 clearly states that the tool returns the US SEC EDGAR filing list, including accession numbers and original URLs, and gives concrete example queries. It also distinguishes itself from the sibling get_us_filing_detail by explicitly directing body/exhibit reading to that tool.

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?

Usage guidance is explicit: use for queries like 'AAPL 10-K', 'RIVN latest filings', '8-K', and 'SEC filing'. It tells the agent to call get_us_filing_detail with the accession number when body/exhibits are needed, and it fully explains pagination via page/offset and the completion condition.

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

Deploy Server