FinancialMD

Institutional holders of a company

institutional_holders

Read-onlyIdempotent

List the investment managers that reported a position in a company on SEC Form 13F for one quarter, largest reported value first: the manager, shares, market value as the manager reported it, the same manager's shares one quarter earlier, the change, whether the position is new, increased, decreased or unchanged, and the share of the company's reported shares outstanding. data.periods lists the quarters on file. Only positions that an SEC filing ties to the company are listed, so coverage is partial and the list is not a full register. Every number carries a proof that opens the 13F on sec.gov. Filing-layer read: served with generous limits on every tier. Use it when asked which institutions hold a company and how their positions changed. If a dataset, field, company or analysis you need is missing, call request_data.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "limit": 20,
      "company": "ticker:AAPL"
    },
    "name": "institutional_holders"
  }
}

Input Schema

Name	Required	Description
`as_of`	No	Knowledge date or timestamp (YYYY-MM-DD or RFC 3339). The answer is what FinancialMD knew at that instant: only facts whose known interval contains as_of. Omit for the current view.
`limit`	No	Maximum number of periods or items to return (default 50, at most 500).
`cursor`	No	Opaque cursor from a previous page (data.next_cursor).
`period`	No	Optional calendar quarter end (YYYY-03-31, -06-30, -09-30 or -12-31). Default: the newest quarter on file.
`company`	Yes	Company identifier: a FinancialMD id ("fmd_01H..."), an SEC CIK ("cik:320193"), or a ticker ("ticker:AAPL", optionally with the MIC "ticker:AAPL.XNAS"). A bare ticker like "AAPL" is accepted and sent as ticker:AAPL. An issuer on an EU or UK regulated market that does not file with the SEC has no CIK: pass its LEI ("lei:IOG4E947OATN0KJYSD45") or its fmd_ id.

Output Schema

Name	Required	Description
`data`	No	{ period, periods, items: [{ holder: { cik, name }, issuer_name, class_title, company, put_call, share_type, shares, value, prior_shares, shares_change, position_change, percent_of_shares_outstanding }], next_cursor }.
`meta`	No	Request metadata: request_id, as_of, company resolution, coverage, pipeline_version, licence, terms, proof_base.
`error`	No	Present only on isError results: the API error code and message plus remedy hints.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 13, 2026

changedInput schema / properties / company / description

Previous value: -"Company identifier: a FinancialMD id (\"fmd_01H...\"), an SEC CIK (\"cik:320193\"), or a ticker (\"ticker:AAPL\", optionally with the MIC \"ticker:AAPL.XNAS\"). A bare ticker like \"AAPL\" is accepted and sent as ticker:AAPL."New value: +"Company identifier: a FinancialMD id (\"fmd_01H...\"), an SEC CIK (\"cik:320193\"), or a ticker (\"ticker:AAPL\", optionally with the MIC \"ticker:AAPL.XNAS\"). A bare ticker like \"AAPL\" is accepted and sent as ticker:AAPL. An issuer on an EU or UK regulated market that does not file with the SEC has no CIK: pass its LEI (\"lei:IOG4E947OATN0KJYSD45\") or its fmd_ id."

First observedNov 13, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses the important behavioral caveats: coverage is partial and not a full register, only filing-tied positions appear, every figure carries a proof link to the 13F on sec.gov, and the endpoint is generously rate-limited. That is exactly the kind of provenance and completeness context annotations cannot express.

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 with purpose and scope, and the caveats and routing come last where they belong. The opening sentence is an over-long run-on enumerating six returned fields, some of which the output schema already documents, so a little trimming is possible.

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 read-only filing-layer tool with an output schema and fully documented params, the definition covers the gaps that matter: partial coverage, provenance links, quarter defaults, and where to go when data is missing. The field enumeration is partly wasted given the output schema, but nothing an agent needs to call it correctly is absent.

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?

With 100% schema coverage the schema already carries the semantics, but the description still adds meaning by explaining that data.periods enumerates the quarters on file and framing the period choice in terms of the reporting quarter. The one-quarter-earlier comparison column also clarifies why a single period yields change figures.

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?

Names a specific verb and resource ("List the investment managers that reported a position in a company on SEC Form 13F for one quarter") plus the ordering and breadth of returned fields, which separates it from fund_holders and insider_holders 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 Guidelines4/5

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

Gives a clear trigger ("Use it when asked which institutions hold a company and how their positions changed") and a fallback route ("If a dataset, field, company or analysis you need is missing, call request_data"). It stops short of explicitly excluding the near-neighbour institutional_holdings, so the agent must infer that boundary.

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

All FinancialMD 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?