Skip to main content
Glama

Get Institutional Holdings

secedgar_get_institutional_holdings
Read-onlyIdempotent

Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML. company is the institutional filer — its 10-digit CIK (e.g. 0000102909), a ticker, or an entity name (names outside EDGAR's ticker file resolve through EDGAR entity search) — and the tool returns what that institution holds. A name that matches several EDGAR filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK, rather than guessing. For the reverse direction — which institutions hold a given portfolio company — use secedgar_find_holders, whose filer_cik results feed straight back into this tool. The 13F information table lists each position: issuer name, CUSIP, shares held, market value (in whole USD), and put/call designation for options. Sub-lines for the same security are consolidated into distinct positions sorted by value by default (set consolidate=false for raw filing rows). The inline holdings list is one page of limit rows starting at offset — pass the returned next_offset to walk further down a large information table. The full parsed holdings set is also materialized as df_ when a canvas is available — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate the whole filing or self-join across quarters on cusip + reporting_period. Institutions with less than $100M in 13(f) securities are exempt and may not file. Use secedgar_search_filings with forms=["13F-HR"] for broader search.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20.
offsetNoRow to start the page at, 0-based, over the ordered position list. Pass the next_offset from the previous response to read the next page — the filing is parsed whole and sliced, so paging is stable and gap-free. An offset at or past the position count returns an empty page.
companyYesThe institutional filer whose 13F to fetch — a 10-digit CIK (e.g. "0000102909" for VANGUARD GROUP INC, the most reliable form), a ticker, or an entity name. A name is matched against the registrants in EDGAR's ticker file first (current and former names) and, when none match, resolved through EDGAR entity search, which covers institutional managers absent from that file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like "AAPL" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction.
quarterNoReporting quarter to target, in "YYYY-QN" format (e.g., "2025-Q4"), matched exactly against each 13F-HR's period of report. When omitted, returns the most recent 13F-HR in the submissions feed's recent window (the last year or 1,000 filings, whichever holds more). Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026. A quarter older than the recent window is looked up in the archive, reading forward from the quarter end up to 10 archive pages. A quarter the manager covered with a 13F-NT notice (holdings reported by other managers) fails naming that notice.
consolidateNoWhen true (default), info-table sub-lines for the same security (CUSIP + class + put/call) are summed into one position and results are sorted by market value descending, so `limit` returns the largest distinct holdings. Set false to return raw information-table rows in filing order (one per investment-discretion/manager sub-line), preserving investment_discretion.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit cap applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of holdings shown inline.
noticeNoGuidance when no filing was found or the result is empty, with alternatives.
offsetNoRow the returned page starts at, 0-based.
datasetNoDataframe of every position, shaped by consolidate; rows carry the filer keys and join across quarters on cusip + reporting_period. Absent when canvas is unavailable or there are no holdings.
holdingsNo`limit` rows from `offset`: positions by market value when consolidate=true, else raw rows in filing order.
filer_cikNoCIK of the 13F filer, zero-padded to 10 digits.
truncatedNoTrue when the inline holdings[] was capped by limit.
filer_nameNoName of the institutional filer (the 13F submitter).
filing_dateNoDate the 13F was submitted (YYYY-MM-DD).
next_offsetNoOffset for the next page. Absent on the last page.
total_positionsNoDistinct positions after consolidating sub-lines, before limit. Present only when consolidate=true.
accession_numberNoAccession number of this 13F-HR — pass to secedgar_get_filing.
reporting_periodNoCalendar-quarter end this 13F covers (YYYY-MM-DD), from the cover page. Absent when the filing omits it.
total_holdings_in_filingNoRaw information-table rows in this filing, before consolidation and limit.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changed
    • changedOutput schema / properties / accession_number / description
      Previous value: -"Accession number for this 13F-HR filing — pass to secedgar_get_filing for the full document."New value: +"Accession number of this 13F-HR — pass to secedgar_get_filing."
    • changedOutput schema / properties / dataset / description
      Previous value: -"Canvas dataframe holding every parsed position from this 13F filing (the inline holdings[] is a preview capped at limit). Each row carries the filer metadata (filer_cik, filer_name, reporting_period, filing_date, accession_number) plus the position fields, so it self-joins across quarters/filers on cusip + reporting_period. Reflects the consolidate setting (consolidated positions when true, raw info-table sub-lines with investment_discretion when false). Query with secedgar_dataframe_query. Absent when canvas is unavailable or the filing had no holdings."New value: +"Dataframe of every position, shaped by consolidate; rows carry the filer keys and join across quarters on cusip + reporting_period. Absent when canvas is unavailable or there are no holdings."
    • 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 / holdings / description
      Previous value: -"One page of holdings, `limit` rows starting at `offset` — consolidated positions sorted by market value when consolidate=true, else raw information-table rows in filing order."New value: +"`limit` rows from `offset`: positions by market value when consolidate=true, else raw rows in filing order."
    • changedOutput schema / properties / holdings / items / properties / investment_discretion / description
      Previous value: -"SOLE = sole investment discretion, DFND = defined (shared/advised), OTR = other. Absent when not reported."New value: +"SOLE sole discretion, DFND defined (shared or advised), OTR other. Absent when not reported, and on consolidated positions."
    • changedOutput schema / properties / holdings / items / properties / market_value_usd / description
      Previous value: -"Market value of the position in whole USD at the reporting date. SEC Form 13F has reported whole dollars since the 2023 amendments; values from filings before 2023-01-03 (originally thousands) are normalized to whole USD. Absent when not reported."New value: +"Market value in whole USD at the reporting date; values from filings before 2023-01-03, reported in thousands, are scaled to whole USD. Absent when not reported."
    • changedOutput schema / properties / holdings / items / properties / put_call / description
      Previous value: -"Options designation. Present only when the row represents a put or call option position."New value: +"Present only on a put or call option position."
    • changedOutput schema / properties / holdings / items / properties / shares_or_principal_amount / description
      Previous value: -"Number of shares (for equities) or principal amount (for debt securities). Absent when not reported."New value: +"Shares (equities) or principal amount (debt). Absent when not reported."
    • changedOutput schema / properties / holdings / items / properties / shares_or_principal_type / description
      Previous value: -"SH = share position, PRN = principal amount (bonds, notes). Absent when not reported."New value: +"SH shares, PRN principal amount (bonds, notes). Absent when not reported."
    • changedOutput schema / properties / next_offset / description
      Previous value: -"Offset to pass on the next call to continue through the positions. Absent on the last page (no rows remain past this one)."New value: +"Offset for the next page. Absent on the last page."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no filings were found or the result set is empty — suggests alternatives."New value: +"Guidance when no filing was found or the result is empty, with alternatives."
    • changedOutput schema / properties / offset / description
      Previous value: -"Row the returned page starts at, 0-based — the effective offset applied."New value: +"Row the returned page starts at, 0-based."
    • changedOutput schema / properties / reporting_period / description
      Previous value: -"The calendar-quarter end date this 13F covers (YYYY-MM-DD), from the filing cover page. Absent if not surfaced in the filing."New value: +"Calendar-quarter end this 13F covers (YYYY-MM-DD), from the cover page. Absent when the filing omits it."
    • changedOutput schema / properties / total_holdings_in_filing / description
      Previous value: -"Total number of raw information-table rows in this filing, before consolidation and the limit."New value: +"Raw information-table rows in this filing, before consolidation and limit."
    • changedOutput schema / properties / total_positions / description
      Previous value: -"Number of distinct positions after consolidating info-table sub-lines, before the limit. Present only when consolidate=true."New value: +"Distinct positions after consolidating sub-lines, before limit. Present only when consolidate=true."
  2. Changed2 schema fields changed
    • changedInput schema / properties / quarter / description
      Previous value: -"Reporting quarter to target, in \"YYYY-QN\" format (e.g., \"2025-Q4\"). When omitted, returns the most recent 13F-HR available. Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026."New value: +"Reporting quarter to target, in \"YYYY-QN\" format (e.g., \"2025-Q4\"), matched exactly against each 13F-HR's period of report. When omitted, returns the most recent 13F-HR in the submissions feed's recent window (the last year or 1,000 filings, whichever holds more). Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026. A quarter older than the recent window is looked up in the archive, reading forward from the quarter end up to 10 archive pages. A quarter the manager covered with a 13F-NT notice (holdings reported by other managers) fails naming that notice."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a known company or institution. `ambiguous_entity`: The name resolves to multiple EDGAR entities (e.g. several filers sharing a legal name). `no_filings_found`: No 13F-HR filings found for this entity in the recent submissions window. `no_info_table`: The 13F-HR filing was found but the information table XML document could not be located. `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."New value: +"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a known company or institution. `ambiguous_entity`: The name resolves to multiple EDGAR entities (e.g. several filers sharing a legal name). `no_filings_found`: No 13F-HR matches — the entity files none, none exists for the requested quarter in the recent submissions window or the archive pages searched, or the manager filed a 13F-NT notice instead (for the requested quarter, or as its only recent 13F filing when no quarter is given). `no_info_table`: The 13F-HR filing was found but the information table XML document could not be located. `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."
  3. Changed5 schema fields changed
    • addedInput schema / properties / company
      Added value: +{
      +  "description": "The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form), a ticker, or an entity name. A name is matched against the registrants in EDGAR's ticker file first (current and former names) and, when none match, resolved through EDGAR entity search, which covers institutional managers absent from that file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / properties / ticker_or_cik
      Removed value: -{
      -  "description": "The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction.",
      -  "minLength": 1,
      -  "type": "string"
      -}
    • changedInput schema / required
      Previous value: -[
      -  "ticker_or_cik"
      -]New value: +[
      +  "company"
      +]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `company_not_found`: The ticker or CIK does not resolve to a known company or institution `ambiguous_entity`: The name resolves to multiple EDGAR entities (e.g. several filers sharing a legal name) `no_filings_found`: No 13F-HR filings found for this entity in the recent submissions window `no_info_table`: The 13F-HR filing was found but the information table XML document could not be located Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a known company or institution. `ambiguous_entity`: The name resolves to multiple EDGAR entities (e.g. several filers sharing a legal name). `no_filings_found`: No 13F-HR filings found for this entity in the recent submissions window. `no_info_table`: The 13F-HR filing was found but the information table XML document could not be located. `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: -[
      -  "company_not_found",
      -  "ambiguous_entity",
      -  "no_filings_found",
      -  "no_info_table"
      -]New value: +[
      +  "company_not_found",
      +  "ambiguous_entity",
      +  "no_filings_found",
      +  "no_info_table",
      +  "rate_limited"
      +]
  4. Changed1 schema field changed
    • 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."
  5. Changed6 schema fields changed
    • 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": [
      +      "filer_name",
      +      "filer_cik",
      +      "filing_date",
      +      "accession_number",
      +      "total_holdings_in_filing",
      +      "offset",
      +      "holdings"
      +    ]
      +  },
      +  {
      +    "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: `company_not_found`: The ticker or CIK does not resolve to a known company or institution `ambiguous_entity`: The name resolves to multiple EDGAR entities (e.g. several filers sharing a legal name) `no_filings_found`: No 13F-HR filings found for this entity in the recent submissions window `no_info_table`: The 13F-HR filing was found but the information table XML document could not be located Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "company_not_found",
      +            "ambiguous_entity",
      +            "no_filings_found",
      +            "no_info_table"
      +          ],
      +          "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: -[
      -  "filer_name",
      -  "filer_cik",
      -  "filing_date",
      -  "accession_number",
      -  "total_holdings_in_filing",
      -  "offset",
      -  "holdings"
      -]
  6. Changed1 schema field changed
    • changedInput schema / properties / ticker_or_cik / description
      Previous value: -"The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it."New value: +"The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction."
  7. Changed5 schema fields changed
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Row to start the page at, 0-based, over the ordered position list. Pass the next_offset from the previous response to read the next page — the filing is parsed whole and sliced, so paging is stable and gap-free. An offset at or past the position count returns an empty page.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / holdings / description
      Previous value: -"Holdings truncated to limit — consolidated positions sorted by market value when consolidate=true, else raw information-table rows in filing order."New value: +"One page of holdings, `limit` rows starting at `offset` — consolidated positions sorted by market value when consolidate=true, else raw information-table rows in filing order."
    • addedOutput schema / properties / next_offset
      Added value: +{
      +  "description": "Offset to pass on the next call to continue through the positions. Absent on the last page (no rows remain past this one).",
      +  "type": "number"
      +}
    • addedOutput schema / properties / offset
      Added value: +{
      +  "description": "Row the returned page starts at, 0-based — the effective offset applied.",
      +  "type": "number"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "filer_name",
      -  "filer_cik",
      -  "filing_date",
      -  "accession_number",
      -  "total_holdings_in_filing",
      -  "holdings"
      -]New value: +[
      +  "filer_name",
      +  "filer_cik",
      +  "filing_date",
      +  "accession_number",
      +  "total_holdings_in_filing",
      +  "offset",
      +  "holdings"
      +]
  8. Changed1 schema field changed
    • changedInput schema / properties / ticker_or_cik / description
      Previous value: -"The institutional filer whose 13F to fetch — its CIK (e.g., \"0000102909\" for Vanguard) or full legal name (e.g., \"Vanguard Group\"). CIK or the full legal name resolves most reliably; tickers usually belong to operating companies, which do not file 13Fs. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that entity's own filings, not who holds it."New value: +"The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it."
  9. Changed1 schema field changed
    • changedInput schema / properties / ticker_or_cik / description
      Previous value: -"Ticker symbol or CIK of the institutional filer (e.g., \"0000102909\" for Vanguard) or a company name. For institution lookups, CIK or the full legal name resolves most reliably — tickers are typically for operating companies, not fund managers."New value: +"The institutional filer whose 13F to fetch — its CIK (e.g., \"0000102909\" for Vanguard) or full legal name (e.g., \"Vanguard Group\"). CIK or the full legal name resolves most reliably; tickers usually belong to operating companies, which do not file 13Fs. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that entity's own filings, not who holds it."
  10. Changed3 schema fields changed
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The limit cap applied.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of holdings shown inline.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the inline holdings[] was capped by limit.",
      +  "type": "boolean"
      +}
  11. Changed1 schema field changed
    • addedOutput schema / properties / dataset
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Canvas dataframe holding every parsed position from this 13F filing (the inline holdings[] is a preview capped at limit). Each row carries the filer metadata (filer_cik, filer_name, reporting_period, filing_date, accession_number) plus the position fields, so it self-joins across quarters/filers on cusip + reporting_period. Reflects the consolidate setting (consolidated positions when true, raw info-table sub-lines with investment_discretion when false). Query with secedgar_dataframe_query. Absent when canvas is unavailable or the filing had no holdings.",
      +  "properties": {
      +    "expires_at": {
      +      "description": "ISO 8601 expiry timestamp.",
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "Dataframe handle (df_XXXXX_XXXXX) — pass to secedgar_dataframe_query.",
      +      "type": "string"
      +    },
      +    "row_count": {
      +      "description": "Rows materialized in the dataframe.",
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "row_count",
      +    "expires_at"
      +  ],
      +  "type": "object"
      +}
  12. Changed6 schema fields changed
    • addedInput schema / properties / consolidate
      Added value: +{
      +  "default": true,
      +  "description": "When true (default), info-table sub-lines for the same security (CUSIP + class + put/call) are summed into one position and results are sorted by market value descending, so `limit` returns the largest distinct holdings. Set false to return raw information-table rows in filing order (one per investment-discretion/manager sub-line), preserving investment_discretion.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / holdings / description
      Previous value: -"Holdings rows from the information table, truncated to limit."New value: +"Holdings truncated to limit — consolidated positions sorted by market value when consolidate=true, else raw information-table rows in filing order."
    • addedOutput schema / properties / holdings / items / properties / market_value_usd
      Added value: +{
      +  "description": "Market value of the position in whole USD at the reporting date. SEC Form 13F has reported whole dollars since the 2023 amendments; values from filings before 2023-01-03 (originally thousands) are normalized to whole USD. Absent when not reported.",
      +  "type": "number"
      +}
    • removedOutput schema / properties / holdings / items / properties / value_in_thousands
      Removed value: -{
      -  "description": "Market value of the position in thousands of USD at the reporting date. Absent when not reported.",
      -  "type": "number"
      -}
    • changedOutput schema / properties / total_holdings_in_filing / description
      Previous value: -"Total number of infoTable rows in this filing before the limit was applied."New value: +"Total number of raw information-table rows in this filing, before consolidation and the limit."
    • addedOutput schema / properties / total_positions
      Added value: +{
      +  "description": "Number of distinct positions after consolidating info-table sub-lines, before the limit. Present only when consolidate=true.",
      +  "type": "number"
      +}
  13. Added

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, so the safety profile is covered. The description adds real behavioral context: consolidation default and its effect on limit, stable gap-free paging via next_offset, the materialized df_<id> dataframe, and ambiguous-name candidate returns. It does not add much beyond this (e.g., rate limits, response shape), but the extra disclosure is substantial for an annotated tool.

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?

The core purpose and key caveat (filer, not issuer) are front-loaded, and the dense sentences each carry information. It is nonetheless long and packs dataframe, pagination, AND name-resolution details into one block, slightly past the point of easy scanning.

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?

An output schema exists and annotations cover safety, so the description need not explain return values. What remains – name resolution, quarter mapping, consolidation, paging, and the sibling routing – is covered, leaving nothing an agent needs to call it correctly.

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 coverage is 100%, so the schema already documents all five parameters thoroughly, making 3 the baseline. The description reinforces semantics rather than adding format detail the schema lacks, though the 'this is NOT the portfolio company' framing for company adds genuine disambiguation value.

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?

The opening sentence gives a specific verb+resource ('Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML') and immediately distinguishes company (the filer) from the portfolio company. It explicitly names secedgar_find_holders as the reverse-direction sibling, so an agent can tell them apart 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?

Explicit routing is provided: use secedgar_find_holders for the reverse direction, secedgar_search_filings with forms=["13F-HR"] for broader search, and the $100M exemption is noted as a reason an expected filer may be absent. When/when-not conditions and alternatives are all stated.

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.