Skip to main content
Glama

KeyVex

by com.keyvex
OverviewDiscussionsAdmin

get_institutional_holdings

Read-only

Returns 13F holdings — quarterly snapshots of equity positions held by institutional investment managers with $100M+ AUM, filed with the SEC. Each record is one (fund, security, quarter) tuple. Use this when the user asks about: which institutions hold a stock, a fund's portfolio, position changes quarter-over-quarter, or 'whale' activity in a specific name. Reporting lag: up to 45 days after quarter end. A 2026-Q1 filing typically appears in mid-May 2026. The most recent quarter visible always lags real time. Important: 13F covers institutional managers ≥ $100M AUM but does NOT include short positions, cash, options (with rare exceptions), or non-US-listed equities. It's a snapshot of long equity positions only. For 'did the fund increase its AAPL stake?' questions, check the position_change field — values are 'new', 'increased', 'decreased', 'closed', or 'unchanged' relative to the same fund's prior quarter. form: the filing a row comes from, '13F-HR' (the quarter's report) or '13F-HR/A' (an amendment). amendment_type: on an amendment, 'RESTATEMENT' (it replaces the report) or 'NEW HOLDINGS' (it adds positions); null on a 13F-HR. Both are absent on rows stored before they were recorded. Values are US dollars. 13F filings before 2023 report thousands and are multiplied by 1000; a filing that used the other unit is corrected once market prices confirm it: a 2023+ filing in thousands ×1000, a pre-2023 filing already in dollars ÷1000 (units_corrected true; value_as_filed holds the filed number, summed across a security's lines). A few filings whose units could not be confirmed are left as stored: a 2023+ one may read 1000x too low, a pre-2023 one 1000x too high. verification_status: VERIFIED means the filing matches its own totals (its rows add up to the row count and total value it declares). It is not a check against market prices: a filer's own consistent but wrong numbers still read VERIFIED, and so do a few filings stored before the thousands check began. INSUFFICIENT_DATA means that check failed or could not run, or the values look filed in the wrong unit (a 2023+ filing in thousands, or a pre-2023 filing in dollars) but could not be confirmed.

Input Schema

NameRequiredDescriptionDefault
cusipNoAlternative to ticker — 9-character SEC CUSIP identifier. Useful when a security has multiple share classes with different tickers.
limitNoMaximum records to return. Default 50, max 500.
cursorNoPass the `next_cursor` from the previous response VERBATIM to fetch the next page. Keep every other filter and the sort identical while paging. Omit to start from the top. A quarter of 13F filings runs to far more than 500 rows, so a complete picture requires paging.
tickerNoFilter to holdings of one stock by US ticker, e.g. 'AAPL'. Case-insensitive.
quarterNoPeriod ending date in YYYY-MM-DD form (e.g. '2026-03-31'). Defaults to all quarters available in the database.
sort_byNoField used for ordering. Default: market_value (largest positions first).
fund_cikNoSEC CIK of the fund (10-digit, padded). Preferred over fund_name when known. Berkshire Hathaway = '0001067983'.
fund_nameNoFull or partial fund name; case-insensitive substring match. Examples: 'Berkshire', 'Bridgewater', 'Citadel'. A name of 1-2 characters matches as a whole word within the newest 20,000 holdings by filing date only, and the answer says so; fund_cik searches the full history.
min_valueNoFilter to positions with market_value >= this amount (USD). Use to focus on large positions.
sort_orderNoDefault: desc (largest first).
position_changeNoFilter to position-change type. Common queries: 'increased' for funds adding to a position, 'closed' for funds that exited.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / fund_name / description
      Previous value: -"Full or partial fund name; case-insensitive substring match. Examples: 'Berkshire', 'Bridgewater', 'Citadel'."New value: +"Full or partial fund name; case-insensitive substring match. Examples: 'Berkshire', 'Bridgewater', 'Citadel'. A name of 1-2 characters matches as a whole word within the newest 20,000 holdings by filing date only, and the answer says so; fund_cik searches the full history."
  2. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already establish read-only, open-world, non-destructive, but the description adds far more: a 45-day reporting lag with a concrete example, coverage exclusions (no shorts/cash/options/non-US equities), amendment semantics, unit-correction rules and their failure modes, and the exact meaning of verification_status including that it does not validate against market prices.

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 purpose and usage before the data caveats, and nearly every sentence carries operational weight (lag, units, verification). The unit-correction paragraph is dense and slightly over-elaborated, costing a point.

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 no output schema, the description must document return-field semantics, and it does: form, amendment_type, units/units_corrected, value_as_filed, and verification_status are all explained, alongside coverage limits and paging expectations. An agent has everything needed to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 11 parameters including the position_change enum values and the fund_name 1-2 character caveat. The description does not extend parameter meaning beyond that, so the baseline of 3 applies.

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 precise verb+resource+scope: 13F quarterly snapshots of equity positions by institutional managers with $100M+ AUM, one (fund, security, quarter) row per record. The 13F framing and AUM threshold clearly separate it from siblings like get_activist_stakes, get_fund_holdings, and get_insider_holdings even without naming them.

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 explicit user-question triggers ('which institutions hold a stock', 'a fund's portfolio', 'position changes QoQ', 'whale activity'). It stops short of naming alternative tools or stating when NOT to use it (e.g. for short positions or options, which it notes are excluded but doesn't route elsewhere).

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

All KeyVex toolsInspect
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