Skip to main content
Glama
Sign In

KeyVex

by com.keyvex
OverviewDiscussionsAdmin

get_insider_holdings

Read-only

A ticker search also returns rows this issuer FILED UNDER SYMBOLS IT NO LONGER LISTS (renames, filer typos, ADR spellings). Each row keeps ticker as SEC received it and gains current_ticker when the issuer trades under a different symbol today. Separately-listed share classes are NOT merged, and asking for a RETIRED symbol returns only rows filed under it — retired symbols get reissued to other companies. When more than one issuer has filed under a ticker (a reused symbol, a holding-company reorganization), every row stays in the answer and carries issuer_relation: the row's own issuer and its relation to the ticker's issuer (same_issuer; predecessor or successor, on SEC evidence; related_by_name; affiliate; or different_issuer), with the evidence, such as the SEC succession form and its date. A ticker search also finds this issuer's rows filed under ANOTHER issuer's symbol, matched only on its CIK. Returns per-security INSIDER POSITIONS from SEC Form 3/4/5 filings — one row per holding line reported by a corporate insider (director, officer, or 10%+ beneficial owner). Use this when the user asks: what a specific insider currently HOLDS, who the largest insider holders of a stock are, an insider's position across companies, or direct-vs-indirect ownership structure. This is the position (stock) companion to get_insider_transactions (the buys/sells flow). Source: SEC bulk Form 3/4/5 dataset (insider_holdings_v2), 2006→present, refreshed quarterly. Each row carries the filing envelope (company_cik, company_name, ticker, reporting_owner_cik/name, role flags, filing_date, period_of_report), the position (holding_type nonderiv|deriv, security_title, shrs_owned_following_trans, valu_owned_following_trans, direct_indirect_ownership D|I), and — for derivative holdings — conv_exercise_price, exercise_date, expiration_date, and underlying-security detail. Useful filter combos: ticker='NVDA', sort_order='desc' most-recent NVDA insider holdings reporting_owner_cik='0001214128' one insider's positions everywhere ticker='AAPL', holding_type='deriv' AAPL insiders' option/RSU positions ticker='TSLA', is_ten_percent_owner=true 10%+ owners of TSLA company_cik='0000320193', min_value=1000000 Apple insiders holding >$1M reporting_owner_name='Musk' name substring (case-insensitive) shares/value are 'following the reported transaction' — the position as of that filing, not a live real-time holding. For the trades themselves use get_insider_transactions; ownership ties together via reporting_owner_cik.

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": "get_insider_holdings"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum records to return. Default 50, max 500.
sinceNoISO date (YYYY-MM-DD). Only holdings whose period_of_report >= this date.
untilNoISO date (YYYY-MM-DD). Only holdings whose period_of_report <= this date.
tickerNoExact issuer ticker (e.g., 'AAPL', 'BRK.B').
sort_byNoSort field. Only period_of_report is supported. Default: period_of_report.
min_valueNoMinimum USD value owned following the reported transaction. Use to focus on large positions.
is_officerNoTrue returns only holdings reported by officers.
min_sharesNoMinimum shares owned following the reported transaction. Use to focus on large positions.
sort_orderNoDefault: desc (most recent reporting period first).
company_cikNoIssuer CIK (10-digit, leading-zero padded). Returns insider holdings across all reporting periods for that company.
is_directorNoTrue returns only holdings reported by directors.
company_nameNoCase-insensitive substring against issuer company name (e.g., 'Apple', 'Tesla').
holding_typeNo'nonderiv' = direct securities (common stock); 'deriv' = derivative holdings (options, RSUs, warrants, convertibles). Omit for both.
merge_co_reportsNoDEFAULT TRUE — leave it alone unless you specifically want raw filings. When shares are held through a fund, trust or family holding company, every person deemed a beneficial owner files their own Form 3/4/5 reporting the SAME position, so one block appears once per filer. By default those lines are merged into one row per position, so share counts are the shares actually held; reporting_owner_name names every filer and co_reported_accessions lists every accession. Set false for one row per filing — totals then count the same shares once per reporting person.
reporting_owner_cikNoInsider CIK (10-digit, leading-zero padded). Returns one insider's positions across every company they report on.
is_ten_percent_ownerNoTrue returns only holdings reported by 10%+ beneficial owners.
reporting_owner_nameNoCase-insensitive substring against the insider's name (e.g., 'Musk', 'Cook').
direct_indirect_ownershipNo'D' direct ownership, 'I' indirect (held via trust, LLC, family member, etc.).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnly/openWorld; the description goes well beyond, disclosing that ticker searches include rows filed under retired/reused symbols, that retired-symbol queries return only rows filed under that symbol, that share classes are not merged, that co-filed duplicate positions are merged by default, and that values are 'following the reported transaction,' not live holdings. It also names the source dataset and refresh cadence (quarterly, 2006→present).

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?

Content is largely substantive, but the front half is dominated by ticker-alias and issuer_relation edge cases before the tool's core function is stated, delaying the reader's payoff. The essential one-liner, the 'use this when' triggers, and the sibling routing all appear mid-paragraph rather than up front.

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?

With 18 optional parameters and no output schema, the description does the heavy lifting by enumerating the returned row fields (company_cik, reporting_owner_cik/name, role flags, holding_type, shrs/valu_owned_following_trans, direct_indirect_ownership, and derivative-specific fields). Minor gaps remain: no explicit note on result volume/pagination behavior beyond the limit parameter and no output shape for merged co-report rows.

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% and already documents most parameters, so the schema carries the baseline. The description still adds value by pairing parameters into realistic query combos (ticker+sort_order, reporting_owner_cik, holding_type='deriv', is_ten_percent_owner, company_cik+min_value, reporting_owner_name) and by explaining the ticker/CIK matching asymmetry, which the schema does not.

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: 'Returns per-security INSIDER POSITIONS from SEC Form 3/4/5 filings — one row per holding line reported by a corporate insider (director, officer, or 10%+ beneficial owner).' It explicitly differentiates itself from the sibling get_insider_transactions ('position (stock) companion' vs. 'the buys/sells flow'), so an agent can route 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?

Gives explicit triggers ('Use this when the user asks: what a specific insider currently HOLDS, who the largest insider holders of a stock are, an insider's position across companies, or direct-vs-indirect ownership structure') plus the exclusion ('For the trades themselves use get_insider_transactions'). Concrete filter combos then map those questions onto parameter values.

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