Skip to main content
Glama

Kaleidoscope MCP (SEC & financial data)

Fund Equity Book (an ETF or fund equity positions, N-PORT)

fund_equity_book
Read-onlyIdempotent

A fund's / ETF's equity holdings — given a fund SERIES id (S000…), return its equity positions (ticker, issuer, shares, value_usd), ranked by position size, amendment-resolved to the fund's latest N-PORT report. The mirror of fund_equity_holders ('who holds X' ↔ 'what does fund Y hold').

Source: SEC N-PORT-P fund-holdings panel (equity slice), fund-series grain. series_id is the FUND, not the fund family — one registrant (e.g. iShares Trust) files a separate N-PORT per series (iShares Core S&P 500 ETF = one series_id). Find a series_id from fund_equity_holders (each holder row carries it) or a fund's N-PORT.

Caveats: equity slice only (this is the fund's EQUITY book — its bond holdings are in the tranche corp-debt panel, its full book incl. derivatives/other isn't here); as_of is the fund's latest report_date; value_usd is the marked position. Coverage: latest-quarter + ~3.5y history (2022-11 → current); full 6.5y backfill in progress.

The header carries accession + filing_url (the N-PORT for as_of; open with get_filing) and each position its own accession + filing_url (the N-PORT it was read from).

Each fund row carries fund_type from the fund's latest SEC N-CEN: etf, mutual_fund, closed_end, money_market, interval, both (one series with ETF and mutual-fund share classes, e.g. Vanguard Total Stock Market = VTI + VTSAX; share_classes then lists each class with ticker and is_etf_class), other (separate account, UIT), or null when N-CEN doesn't cover the series (e.g. liquidated before filing one).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "series_id": "<series_id>"
    },
    "name": "fund_equity_book"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax positions (default 100, max 1000), ranked by value_usd desc.
series_idYesFund series id (S000… — the fund, not the family). Required.
include_preferredNoInclude preferred-stock positions (asset_cat 'EP'). Default true (a fund's full equity book).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds real behavior: results are amendment-resolved to the latest N-PORT report_date, as_of reflects that report, value_usd is the marked position, and coverage is latest-quarter plus ~3.5y with a backfill in progress. It also discloses the response envelope (header accession + filing_url, per-position accession + filing_url) and the fund_type derivation from N-CEN including the null case. Only pagination/truncation behavior for large books is left implicit.

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 the core purpose and routing sentence before caveats and source notes, and every block (mirror, series-grain warning, caveats, coverage) carries distinct information. Some density and mild repetition between the caveat paragraph and the return-envelope paragraph keep it from being maximally tight.

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 no output schema, the description still describes the return shape, the fund_type/share_classes vocabulary, and the coverage window, which is more than most definitions at this complexity. Minor gaps remain around response size, truncation, and what happens for funds with no equity positions, but nothing essential to correct invocation 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 meaning the schema lacks: why series_id is series-grain (one N-PORT per series, not per registrant) and concrete sources for obtaining one. It does not expand on `include_preferred` or `limit` beyond what the schema already states, so it earns an increment rather than a top score.

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 (return a fund's equity positions given a series id) plus the payload fields (ticker, issuer, shares, value_usd) and ranking. It explicitly names the sibling it mirrors, `fund_equity_holders`, with the 'who holds X' ↔ 'what does fund Y hold' framing, so an agent can pick between 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?

Gives explicit when-to-use (equity book of a fund series), when-not (bond holdings live in the corp-debt tranche panel, derivatives/other absent), and how to obtain the required series_id (from a `fund_equity_holders` row or the fund's N-PORT). It also warns series_id is the fund, not the family, with a concrete iShares example.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources