secedgar-mcp-server

Find Holders

secedgar_find_holders

Read-onlyIdempotent

Find which institutional managers reported holding an issuer, by searching 13F-HR information tables for one reporting quarter. This is the reverse direction of secedgar_get_institutional_holdings: that tool takes a manager and returns its portfolio, this one takes an issuer and returns its managers — pass a returned filer_cik plus the same quarter to read the actual position. Searching by cusip is the precise path, matching the identifier the information table itself carries; without it the issuer name is matched as a phrase against the filing text, which both over-matches (unrelated issuers sharing a word) and under-matches (managers writing the name differently), so prefer cusip whenever one is known. A CUSIP cannot be derived from a ticker here — read one off any 13F information table returned by secedgar_get_institutional_holdings. The returned list is unranked: the search index scores by text relevance, which carries no signal about position size, and no ordering by shares or market value is available without opening each filing. Managers holding under $100M in 13(f) securities are exempt from filing at all. When more managers match than fit inline, the full fetched set is staged as df_ — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Input Schema

TableJSON Schema

Name	Required	Description
`cusip`	No	The issuer's 9-character CUSIP (e.g. "037833100" for Apple common stock; foreign issuers use a CINS starting with a letter, e.g. "H1467J104"). The precise match key — information tables identify every position by CUSIP, so this avoids the name-phrase misses. Each share class has its own CUSIP, so a multi-class issuer needs one call per class. Read a CUSIP off the holdings returned by secedgar_get_institutional_holdings.
`limit`	No	Filer rows returned inline. The full fetched set (up to 500 rows) is materialized as a dataframe when a canvas is available. Default 20.
`issuer`	Yes	The portfolio company whose holders you want — a ticker ("AAPL"), a 10-digit CIK ("0000320193"), or a company name. Without cusip, this resolves to the company's EDGAR-conformed name and that name is phrase-matched against 13F information tables, so it must identify one company. With cusip supplied, it is used only to label the result.
`quarter`	No	Reporting quarter to search, "YYYY-QN" (e.g. "2026-Q1"). Omit for the newest quarter whose 45-day filing deadline has passed — the applied quarter and its filing window are echoed in the response. A quarter still inside its deadline returns nothing, because the filings do not exist yet.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The limit cap applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of filers shown inline.
`issuer`	No	The issuer input, echoed.
`notice`	No	Guidance when the search returned no filers — names the likely cause.
`dataset`	No	Dataframe of every fetched filer row, keyed by issuer and quarter for cross-issuer joins. Absent when the result fits inline, canvas is unavailable, or staging failed.
`fetched`	No	Filings retrieved, at most 500; equals total_filings when the window fit.
`holders`	No	One page of filers, capped at limit; order says nothing about position size.
`quarter`	No	Reporting quarter searched, "YYYY-QN": the requested one or the default.
`filed_to`	No	End of the filing window searched (YYYY-MM-DD).
`ordering`	No	How the holder list is ordered, and what that ordering does not mean.
`truncated`	No	True when the inline holders list was capped.
`filed_from`	No	Start of the filing window searched (YYYY-MM-DD).
`search_key`	No	The exact term searched — the CUSIP, or the quoted phrase.
`search_mode`	No	"cusip" matches the information table's identifier; "name" phrase-matches filing text, looser both ways.
`total_filings`	No	13F-HR filings matching the search key in the window, per the index; slightly over-counts holders (amendments of older quarters, managers amending this one), which holders_in_quarter corrects.
`total_is_exact`	No	False when total_filings is a lower bound (the index capped the count).
`holders_in_quarter`	No	Distinct managers reporting this quarter among fetched filings: the set limit pages and the dataframe holds. Other-quarter amendments drop; a manager that amended counts once, at its latest filing.
`resolved_issuer_cik`	No	CIK of the resolved issuer, zero-padded to 10 digits. Absent when cusip was supplied.
`resolved_issuer_name`	No	EDGAR-conformed name the issuer resolved to, also the phrase searched. Absent when cusip was supplied.

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedOct 4, 2026

changedOutput schema / properties / dataset / description

Previous value: -"Canvas dataframe holding every fetched filer row, each carrying the issuer key and quarter so it joins across issuers and quarters. Absent when the result fits inline, canvas is unavailable, or materialization failed. Query with secedgar_dataframe_query."New value: +"Dataframe of every fetched filer row, keyed by issuer and quarter for cross-issuer joins. Absent when the result fits inline, canvas is unavailable, or staging failed."

changedOutput schema / properties / dataset / properties / name / description

Previous value: -"Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query."New value: +"Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."

changedOutput schema / properties / dataset / properties / truncated / description

Previous value: -"True when more filers exist beyond the fetch budget — total_filings exceeds fetched."New value: +"True when total_filings exceeds fetched, so more filers exist."

changedOutput schema / properties / fetched / description

Previous value: -"Filings retrieved from the index, capped by the fetch budget of 500. Equals total_filings when the whole window fit inside the budget."New value: +"Filings retrieved, at most 500; equals total_filings when the window fit."

changedOutput schema / properties / holders / description

Previous value: -"One page of filers, capped at limit. Order carries no position-size meaning — see the ordering note."New value: +"One page of filers, capped at limit; order says nothing about position size."

changedOutput schema / properties / holders / items / properties / filer_cik / description

Previous value: -"Filer CIK, zero-padded to 10 digits. Pass as company to secedgar_get_institutional_holdings for this manager's positions."New value: +"Filer CIK, zero-padded to 10 digits; pass as company to secedgar_get_institutional_holdings."

changedOutput schema / properties / holders / items / properties / filer_name / description

Previous value: -"Institutional manager that filed, with ticker/CIK parentheticals stripped."New value: +"Institutional manager that filed, ticker/CIK parentheticals stripped."

changedOutput schema / properties / holders / items / properties / form / description

Previous value: -"Form type, \"13F-HR\" or \"13F-HR/A\" for an amendment. Absent when the index carries no form tag."New value: +"\"13F-HR\", or \"13F-HR/A\" for an amendment. Absent when the index carries no form tag."

changedOutput schema / properties / holders_in_quarter / description

Previous value: -"Distinct managers among the fetched filings reporting this quarter as their period — the set paged by limit and materialized on the dataframe. Lower than fetched by the filings dropped as amendments restating other quarters, and by managers that amended this quarter (kept once, at their latest filing)."New value: +"Distinct managers reporting this quarter among fetched filings: the set limit pages and the dataframe holds. Other-quarter amendments drop; a manager that amended counts once, at its latest filing."

changedOutput schema / properties / quarter / description

Previous value: -"Reporting quarter searched, \"YYYY-QN\" — the requested one, or the applied default."New value: +"Reporting quarter searched, \"YYYY-QN\": the requested one or the default."

changedOutput schema / properties / resolved_issuer_name / description

Previous value: -"EDGAR-conformed company name the issuer resolved to, and the phrase that was searched. Absent when cusip was supplied (no company lookup runs)."New value: +"EDGAR-conformed name the issuer resolved to, also the phrase searched. Absent when cusip was supplied."

changedOutput schema / properties / search_mode / description

Previous value: -"Which key matched the information tables. \"cusip\" matches the identifier the table itself carries; \"name\" phrase-matches the filing text and is looser in both directions."New value: +"\"cusip\" matches the information table's identifier; \"name\" phrase-matches filing text, looser both ways."

changedOutput schema / properties / total_filings / description

Previous value: -"Total 13F-HR filings matching the search key inside the filing window, as reported by the index. A slight over-count of this quarter's holders on two counts, both of which the returned rows correct for: a few percent are amendments restating an older quarter, and a few more are managers amending their own report for this quarter, which puts them in the window twice."New value: +"13F-HR filings matching the search key in the window, per the index; slightly over-counts holders (amendments of older quarters, managers amending this one), which holders_in_quarter corrects."

Changed3 schema fields changedSep 22, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: No cusip was given and the issuer does not resolve to a known EDGAR company `ambiguous_issuer`: The issuer name matches several EDGAR companies and no cusip was given Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: No cusip was given and the issuer does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies and no cusip was given. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "issuer_not_found",
-  "ambiguous_issuer"
-]New value: +[
+  "issuer_not_found",
+  "ambiguous_issuer",
+  "rate_limited"
+]

changedOutput schema / properties / holders / items / properties / filer_cik / description

Previous value: -"Filer CIK, zero-padded to 10 digits. Pass as ticker_or_cik to secedgar_get_institutional_holdings for this manager's positions."New value: +"Filer CIK, zero-padded to 10 digits. Pass as company to secedgar_get_institutional_holdings for this manager's positions."

Changed1 schema field changedSep 10, 2026

changedOutput schema / properties / dataset / properties / name / description

Previous value: -"Dataframe handle (df_XXXXX_XXXXX) — pass to secedgar_dataframe_query."New value: +"Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query."

Changed6 schema fields changedAug 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "issuer",
+      "search_mode",
+      "search_key",
+      "quarter",
+      "filed_from",
+      "filed_to",
+      "total_filings",
+      "total_is_exact",
+      "fetched",
+      "holders_in_quarter",
+      "holders",
+      "ordering"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `issuer_not_found`: No cusip was given and the issuer does not resolve to a known EDGAR company `ambiguous_issuer`: The issuer name matches several EDGAR companies and no cusip was given Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "issuer_not_found",
+            "ambiguous_issuer"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "issuer",
-  "search_mode",
-  "search_key",
-  "quarter",
-  "filed_from",
-  "filed_to",
-  "total_filings",
-  "total_is_exact",
-  "fetched",
-  "holders_in_quarter",
-  "holders",
-  "ordering"
-]

AddedJul 27, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare only readOnly/openWorld/idempotent; the description adds substantial non-obvious behavior — results are unranked because the index scores text relevance, positions under $100M in 13(f) securities are exempt from filing, and a quarter still inside its 45-day deadline returns nothing. These are the exact caveats an agent would otherwise misread.

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?

Long, but front-loaded with the core purpose and each sentence carries operational value (routing, cusip caveat, unranked warning, exemption, dataframe handoff). It is dense rather than padded; only slight redundancy in restating the secedgar_get_institutional_holdings relationship twice.

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?

With an output schema present, return values need no explanation, and the description still covers the behavioral envelope: match key choice, coverage of a quarter, result ordering, filing exemptions, and the staged-dataframe follow-up. Nothing an agent needs to call this 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 coverage is 100% so the baseline is 3, but the description adds real value beyond it: it states a CUSIP cannot be derived from a ticker here and must be read off a holdings result, and that issuer is used only to label the result when cusip is supplied. Minor remaining gap is that it doesn't restate limit/quarter formatting, which the schema already covers.

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?

States a specific verb and resource — finding institutional managers that reported holding an issuer via 13F-HR information tables — and explicitly contrasts it with the sibling secedgar_get_institutional_holdings ('reverse direction of...'). An agent can distinguish the two without opening either schema.

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?

Names the alternative (secedgar_get_institutional_holdings) and the conditions that select it, prescribes cusip as the preferred match path when known, and explains the failure modes of name matching (over- and under-matching). It also spells out the follow-up workflow: pass filer_cik + same quarter to read the position, and stage overflow into a df_<id> dataframe.

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

All secedgar-mcp-server 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.