Skip to main content
Glama

Get Beneficial Owners

secedgar_get_beneficial_owners
Read-onlyIdempotent

List the 5%-and-over beneficial owners of a public company, parsed from the structured SCHEDULE 13D and SCHEDULE 13G filings made about it. The input is the ISSUER — the company being held — which is the opposite direction from secedgar_get_institutional_holdings, where the input is the manager. 13D is the activist form and carries the filer's stated purpose of the transaction; 13G is the passive form and has no purpose field at all, which is the substantive difference between a stake that intends to influence control and one that does not. Every filing is returned with each reporting person listed separately, because voting power, dispositive power, and percent of class are reported per person even on a joint filing where several funds and their controlling principal report overlapping shares — summing those percentages double-counts the same position. Coverage starts at 2024-12-18, when SEC replaced the legacy SC 13D / SC 13G text filings with this XML format; earlier stakes are readable but not parseable, and the response reports how many of them the issuer has. The full parsed set is materialized as df_ when a canvas is available, one row per reporting person, so it joins against the insider dataframes on issuer CIK and the 13F and NPORT-P dataframes on CUSIP — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

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": {
      "issuer": "<issuer>"
    },
    "name": "secedgar_get_beneficial_owners"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of successfully parsed filings naming the requested issuer to return, newest first. Other-issuer schedules and failed documents do not consume this limit; at most 50 documents are examined. Default 10. Capped at 20: a larger value, up to 1000, returns what 20 returns.
issuerYesThe company whose blockholders you want — a ticker ("AAPL"), a 10-digit CIK ("0000320193"), or a company name. This is the subject company of the schedule, not the investor filing it; passing an investment manager here returns the schedules filed about that manager, which is almost always empty.
form_kindNoWhich schedule to return. "13D" is the activist form, filed by a holder that may seek to influence control and carrying a stated purpose of transaction. "13G" is the passive form, available to institutions and holders under 20% that certify no control intent. "all" (default) returns both, newest first.all
include_amendmentsNoWhether to include amendments (SCHEDULE 13D/A, SCHEDULE 13G/A). Amendments carry the current position and are how an ongoing stake is tracked, so they are included by default. Set false to see only filings that opened a new position.

Output Schema

NameRequiredDescriptionDefault
capNoResult limit or document ceiling that stopped scanning.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of filings returned.
issuerNoThe issuer input, echoed.
noticeNoExclusions, document recovery, scan bounds, cut text, and dataframe guidance.
datasetNoDataframe with one row per reporting person across parsed filings; joins insider dataframes on issuer_cik, and 13F and NPORT-P dataframes on cusip. Absent when canvas is unavailable or nothing parsed.
filingsNoBlockholder filings, newest first, capped at limit.
partialNoTrue when filings_failed is nonempty, independently of truncation.
form_kindNoThe schedule filter applied (default "all").
truncatedNoTrue when filings_not_examined > 0.
issuer_cikNoCIK of the resolved issuer, zero-padded to 10 digits.
resolvedAsNoHow the input was read: a ticker spelling, former ticker, earlier holder, or entity-index match.
issuer_nameNoEDGAR-conformed name of the resolved issuer.
filings_failedNoFailures in scan order; successes retained.
filings_parsedNoMatching parsed filings, capped by limit.
filings_examinedNoMatches + exclusions + failures; at most 50 documents.
filings_not_examinedNoIndexed schedules beyond the result limit or 50-document ceiling.
structured_coverage_fromNoFirst date SEC required this XML format (YYYY-MM-DD); earlier filings cannot be parsed here.
total_structured_filingsNoIndexed 13D/13G schedules matching form/amendment filters in the recent submissions window.
filings_excluded_other_issuerNoSchedules naming another issuer; no rows returned.
legacy_filings_before_coverageNoLegacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window (last year or 1,000 filings), so a floor; find them with secedgar_search_filings.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / resolvedAs / description
      Previous value: -"How an unlisted ticker spelling was read, e.g. \"UEC.N read as UEC\"."New value: +"How the input was read: a ticker spelling, former ticker, earlier holder, or entity-index match."
  2. Changed8 schema fields changed
    • changedOutput schema / properties / dataset / properties / name / description
      Previous value: -"Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."New value: +"Dataframe handle for secedgar_dataframe_describe, then secedgar_dataframe_query."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. `sec_unavailable`: SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out). Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "issuer_not_found",
      -  "ambiguous_issuer",
      -  "no_filings_found",
      -  "rate_limited",
      -  "sec_unreachable"
      -]New value: +[
      +  "issuer_not_found",
      +  "ambiguous_issuer",
      +  "no_filings_found",
      +  "rate_limited",
      +  "sec_unreachable",
      +  "sec_unavailable"
      +]
    • changedOutput schema / properties / filings / items / properties / accession_number / description
      Previous value: -"Accession number — pass to secedgar_get_filing for the full document."New value: +"Accession number for secedgar_get_filing."
    • changedOutput schema / properties / form_kind / description
      Previous value: -"The schedule filter applied — the requested value, or the default \"all\"."New value: +"The schedule filter applied (default \"all\")."
    • changedOutput schema / properties / legacy_filings_before_coverage / description
      Previous value: -"Legacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window; find them with secedgar_search_filings. A floor: the window holds the last year or 1,000 filings."New value: +"Legacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window (last year or 1,000 filings), so a floor; find them with secedgar_search_filings."
    • addedOutput schema / properties / resolvedAs
      Added value: +{
      +  "description": "How an unlisted ticker spelling was read, e.g. \"UEC.N read as UEC\".",
      +  "type": "string"
      +}
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when schedules remain unexamined after the result limit or 50-document ceiling."New value: +"True when filings_not_examined > 0."
  3. Changed10 schema fields changed
    • changedOutput schema / properties / dataset / properties / truncated / description
      Previous value: -"True when indexed schedules remain unexamined after the result limit or scan ceiling."New value: +"True when indexed schedules remain unexamined."
    • changedOutput schema / properties / filings / items / properties / purpose_of_transaction / description
      Previous value: -"Item 4 purpose of transaction, 13D only. Absent on 13G and on an amendment that restates none."New value: +"Item 4 purpose of transaction as filed; 13D only. Absent on 13G and on an amendment that restates none."
    • changedOutput schema / properties / filings / items / properties / purpose_truncated / description
      Previous value: -"True when purpose_of_transaction was clipped; read the full item with secedgar_get_filing."New value: +"True when purpose_of_transaction holds only its first 5,000 characters; secedgar_get_filing has it whole."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / description
      Previous value: -"Every reporting person; a joint filing lists a fund, its adviser, and its principal separately, each reporting the same shares."New value: +"Every reporting person; a joint filing lists each fund, adviser, and principal separately."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / notes / description
      Previous value: -"The filer's cover-page footnote, often the share count behind the percentage. Clipped when long."New value: +"The filer's cover-page footnote as filed, often the share count behind the percentage."
    • addedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / notes_truncated
      Added value: +{
      +  "description": "True when notes holds only its first 2,000 characters; secedgar_get_filing has it whole.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / required
      Previous value: -[
      -  "name",
      -  "person_types"
      -]New value: +[
      +  "name",
      +  "person_types",
      +  "notes_truncated"
      +]
    • changedOutput schema / properties / legacy_filings_before_coverage / description
      Previous value: -"Legacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window, which this tool cannot parse; find them with secedgar_search_filings. A floor: the window holds the last year or 1,000 filings."New value: +"Legacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window; find them with secedgar_search_filings. A floor: the window holds the last year or 1,000 filings."
    • changedOutput schema / properties / notice / description
      Previous value: -"Exclusions, document recovery, scan bounds, and dataframe guidance."New value: +"Exclusions, document recovery, scan bounds, cut text, and dataframe guidance."
    • changedOutput schema / properties / structured_coverage_from / description
      Previous value: -"First date SEC required this XML format (YYYY-MM-DD); earlier blockholder filings cannot be parsed here."New value: +"First date SEC required this XML format (YYYY-MM-DD); earlier filings cannot be parsed here."
  4. Changed1 schema field changed
    • changedOutput schema / properties / dataset / description
      Previous value: -"Dataframe with one row per reporting person across parsed filings; joins insider and 13F dataframes on issuer_cik. Absent when canvas is unavailable or nothing parsed."New value: +"Dataframe with one row per reporting person across parsed filings; joins insider dataframes on issuer_cik, and 13F and NPORT-P dataframes on cusip. Absent when canvas is unavailable or nothing parsed."
  5. Changed2 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Number of successfully parsed filings naming the requested issuer to return, newest first. Other-issuer schedules and failed documents do not consume this limit; at most 50 documents are examined. Default 10."New value: +"Number of successfully parsed filings naming the requested issuer to return, newest first. Other-issuer schedules and failed documents do not consume this limit; at most 50 documents are examined. Default 10. Capped at 20: a larger value, up to 1000, returns what 20 returns."
    • changedInput schema / properties / limit / maximum
      Previous value: -20New value: +1000
  6. Changed13 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Number of filings to fetch and parse, newest first. Each filing is a separate document fetch, so this is the cost of the call as well as its depth. Default 10; a widely-held company can have dozens of blockholder filings a year."New value: +"Number of successfully parsed filings naming the requested issuer to return, newest first. Other-issuer schedules and failed documents do not consume this limit; at most 50 documents are examined. Default 10."
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "issuer",
      -      "issuer_cik",
      -      "issuer_name",
      -      "form_kind",
      -      "total_structured_filings",
      -      "filings_parsed",
      -      "structured_coverage_from",
      -      "legacy_filings_before_coverage",
      -      "filings"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "issuer",
      +      "issuer_cik",
      +      "issuer_name",
      +      "form_kind",
      +      "total_structured_filings",
      +      "filings_parsed",
      +      "filings_examined",
      +      "filings_excluded_other_issuer",
      +      "filings_not_examined",
      +      "filings_failed",
      +      "partial",
      +      "structured_coverage_from",
      +      "legacy_filings_before_coverage",
      +      "filings"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / cap / description
      Previous value: -"The limit cap applied."New value: +"Result limit or document ceiling that stopped scanning."
    • changedOutput schema / properties / dataset / properties / truncated / description
      Previous value: -"True when more structured filings exist than limit fetched."New value: +"True when indexed schedules remain unexamined after the result limit or scan ceiling."
    • addedOutput schema / properties / filings_examined
      Added value: +{
      +  "description": "Matches + exclusions + failures; at most 50 documents.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / filings_excluded_other_issuer
      Added value: +{
      +  "description": "Schedules naming another issuer; no rows returned.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / filings_failed
      Added value: +{
      +  "description": "Failures in scan order; successes retained.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One failed document.",
      +    "properties": {
      +      "accession_number": {
      +        "description": "Accession to inspect with secedgar_get_filing.",
      +        "type": "string"
      +      },
      +      "reason": {
      +        "description": "Document returned 404, or could not be parsed with a usable issuer CIK.",
      +        "enum": [
      +          "document_not_found",
      +          "unparseable"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "accession_number",
      +      "reason"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / filings_not_examined
      Added value: +{
      +  "description": "Indexed schedules beyond the result limit or 50-document ceiling.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / filings_parsed / description
      Previous value: -"Filings fetched and parsed: total_structured_filings capped by limit."New value: +"Matching parsed filings, capped by limit."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no filings matched, naming the coverage boundary and the fallback."New value: +"Exclusions, document recovery, scan bounds, and dataframe guidance."
    • addedOutput schema / properties / partial
      Added value: +{
      +  "description": "True when filings_failed is nonempty, independently of truncation.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / total_structured_filings / description
      Previous value: -"Structured 13D/13G filings matching form_kind in the recent submissions window, before limit."New value: +"Indexed 13D/13G schedules matching form/amendment filters in the recent submissions window."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when filings were capped by limit."New value: +"True when schedules remain unexamined after the result limit or 50-document ceiling."
  7. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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. `sec_unreachable`: The last of three attempts to reach SEC EDGAR got no HTTP response — the connection failed, or no response headers arrived within 15 seconds. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
  8. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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. `sec_unreachable`: The last of three attempts to reach SEC EDGAR got no HTTP response — the connection failed, or no response headers arrived within 15 seconds. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "issuer_not_found",
      -  "ambiguous_issuer",
      -  "no_filings_found",
      -  "rate_limited"
      -]New value: +[
      +  "issuer_not_found",
      +  "ambiguous_issuer",
      +  "no_filings_found",
      +  "rate_limited",
      +  "sec_unreachable"
      +]
  9. Changed20 schema fields changed
    • changedOutput schema / properties / dataset / description
      Previous value: -"Canvas dataframe holding one row per reporting person across every parsed filing, each row carrying the issuer, form, accession, and dates alongside the person's powers. Joins against the insider and 13F dataframes on issuer_cik. Absent when canvas is unavailable or nothing parsed."New value: +"Dataframe with one row per reporting person across parsed filings; joins insider and 13F dataframes on issuer_cik. Absent when canvas is unavailable or nothing parsed."
    • 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 / dataset / properties / truncated / description
      Previous value: -"True when the issuer has more structured filings than limit fetched — the dataframe holds the parsed filings only, not the whole history."New value: +"True when more structured filings exist than limit fetched."
    • changedOutput schema / properties / filings / items / properties / event_date / description
      Previous value: -"Date of the event that required the filing (YYYY-MM-DD) — when the position actually crossed or changed, which precedes filing_date. Absent when the cover page omits it."New value: +"Date of the event that required the filing (YYYY-MM-DD). Absent when the cover page omits it."
    • changedOutput schema / properties / filings / items / properties / purpose_of_transaction / description
      Previous value: -"Item 4 purpose-of-transaction prose — what the holder says it intends. Present on 13D filings only; 13G has no such field, which is what makes it the passive form. Absent on an amendment that restates no purpose."New value: +"Item 4 purpose of transaction, 13D only. Absent on 13G and on an amendment that restates none."
    • changedOutput schema / properties / filings / items / properties / purpose_truncated / description
      Previous value: -"True when purpose_of_transaction was clipped to fit — read the full item with secedgar_get_filing on this accession number."New value: +"True when purpose_of_transaction was clipped; read the full item with secedgar_get_filing."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / description
      Previous value: -"Every reporting person on this filing. A joint filing lists a fund, its adviser, and its controlling principal separately, each reporting the same underlying shares."New value: +"Every reporting person; a joint filing lists a fund, its adviser, and its principal separately, each reporting the same shares."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / aggregate_amount_owned / description
      Previous value: -"Shares beneficially owned by this person. Absent when the person reports no amount, which happens on an exit amendment reporting a zero position."New value: +"Shares beneficially owned by this person. Absent when none is reported, as on an exit amendment."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / cik / description
      Previous value: -"Reporting person CIK, when the schedule carries one. SCHEDULE 13G never does — its cover page has no CIK field — so this is populated on 13D filings only."New value: +"Reporting person CIK. 13D only; the 13G cover page has no CIK field."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / citizenship / description
      Previous value: -"SEC citizenship or place-of-organization code — a US state (\"DE\"), or an SEC country code (\"X1\" United States, \"E9\" Cayman Islands)."New value: +"SEC citizenship or place-of-organization code: a US state (\"DE\") or SEC country code (\"E9\" Cayman Islands)."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / excludes_certain_shares / description
      Previous value: -"True when the reported aggregate deliberately excludes shares this person disclaims beneficial ownership of. Absent when the filing does not answer."New value: +"True when the aggregate excludes shares this person disclaims. Absent when the filing does not say."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / notes / description
      Previous value: -"The filer's own cover-page footnote, usually the share count the percentage was computed against. Clipped when long — the full text is in the filing."New value: +"The filer's cover-page footnote, often the share count behind the percentage. Clipped when long."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / percent_of_class / description
      Previous value: -"Percent of the class this person beneficially owns (0-100), as this person reports it. Per person, not per filing: joint filers report overlapping shares, so these do not sum to a group total."New value: +"Percent of the class this person beneficially owns (0-100). Joint filers report overlapping shares, so these do not sum."
    • changedOutput schema / properties / filings / items / properties / reporting_persons / items / properties / person_types / description
      Previous value: -"SEC type-of-reporting-person codes — IN individual, CO corporation, PN partnership, IA investment adviser, HC holding company, OO other. One person can carry several."New value: +"SEC reporting-person codes: IN individual, CO corporation, PN partnership, IA investment adviser, HC holding company, OO other."
    • changedOutput schema / properties / filings / items / properties / security_class / description
      Previous value: -"Title of the class of securities the schedule covers. A multi-class issuer has a separate schedule per class, so percentages are of this class only."New value: +"Class of securities the schedule covers; percentages are of this class only."
    • changedOutput schema / properties / filings_parsed / description
      Previous value: -"Filings actually fetched and parsed — total_structured_filings capped by limit."New value: +"Filings fetched and parsed: total_structured_filings capped by limit."
    • changedOutput schema / properties / legacy_filings_before_coverage / description
      Previous value: -"Legacy SC 13D / SC 13G filings in the issuer's recent submissions window — pre-2024-12-18 stakes this tool cannot parse. Reach them with secedgar_search_filings and read them with secedgar_get_filing. A floor, not a lifetime count: the submissions window holds the last year or 1,000 filings of every type, whichever is more."New value: +"Legacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window, which this tool cannot parse; find them with secedgar_search_filings. A floor: the window holds the last year or 1,000 filings."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no filings matched — names the coverage boundary and the fallback."New value: +"Guidance when no filings matched, naming the coverage boundary and the fallback."
    • changedOutput schema / properties / structured_coverage_from / description
      Previous value: -"First filing date on which SEC required this XML format (YYYY-MM-DD). Blockholder filings before it exist but are not parseable into this schema."New value: +"First date SEC required this XML format (YYYY-MM-DD); earlier blockholder filings cannot be parsed here."
    • changedOutput schema / properties / total_structured_filings / description
      Previous value: -"Structured SCHEDULE 13D/13G filings matching the form filter in the issuer's recent submissions window, before the limit. The population the returned filings are the newest slice of."New value: +"Structured 13D/13G filings matching form_kind in the recent submissions window, before limit."
  10. Changed1 schema field changed
    • changedOutput schema / properties / legacy_filings_before_coverage / description
      Previous value: -"Legacy SC 13D / SC 13G filings in the issuer's recent submissions window — pre-2024-12-18 stakes this tool cannot parse. Reach them with secedgar_search_filings and read them with secedgar_get_filing. A floor, not a lifetime count: the submissions window holds roughly the last thousand filings of every type."New value: +"Legacy SC 13D / SC 13G filings in the issuer's recent submissions window — pre-2024-12-18 stakes this tool cannot parse. Reach them with secedgar_search_filings and read them with secedgar_get_filing. A floor, not a lifetime count: the submissions window holds the last year or 1,000 filings of every type, whichever is more."
  11. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company `ambiguous_issuer`: The issuer name matches several EDGAR companies `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `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: -[
      -  "issuer_not_found",
      -  "ambiguous_issuer",
      -  "no_filings_found"
      -]New value: +[
      +  "issuer_not_found",
      +  "ambiguous_issuer",
      +  "no_filings_found",
      +  "rate_limited"
      +]
  12. 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."
  13. 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": [
      +      "issuer",
      +      "issuer_cik",
      +      "issuer_name",
      +      "form_kind",
      +      "total_structured_filings",
      +      "filings_parsed",
      +      "structured_coverage_from",
      +      "legacy_filings_before_coverage",
      +      "filings"
      +    ]
      +  },
      +  {
      +    "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: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company `ambiguous_issuer`: The issuer name matches several EDGAR companies `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "issuer_not_found",
      +            "ambiguous_issuer",
      +            "no_filings_found"
      +          ],
      +          "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: -[
      -  "issuer",
      -  "issuer_cik",
      -  "issuer_name",
      -  "form_kind",
      -  "total_structured_filings",
      -  "filings_parsed",
      -  "structured_coverage_from",
      -  "legacy_filings_before_coverage",
      -  "filings"
      -]
  14. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover only the safe-read profile (readOnly/openWorld/idempotent), and the description adds materially more: coverage begins 2024-12-18 because legacy SC 13D/13G text filings are readable but not parseable, the response reports how many legacy filings exist, results are one row per reporting person to avoid double-counting joint filings, and the parsed set is materialized as df_<id>. These are non-obvious behaviors an agent cannot get from the annotations.

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 the key sibling distinction, and most sentences carry real information (double-counting hazard, coverage cutoff, join keys). It is dense but long; the filer-purpose aside about activism vs. passivity is somewhat expansive, though it does justify the form_kind semantics.

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?

For a 4-parameter tool with rich schema and an output schema, the description still covers what matters: the direction of the lookup, per-reporting-person row granularity, the historical coverage boundary, dataframe materialization, and join keys (CIK to insider data, CUSIP to 13F/NPORT-P). Nothing needed to call or interpret it correctly is missing.

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 carries issuer, form_kind, limit, and include_amendments semantics in detail. The description reinforces the issuer direction and the 13D-vs-13G conceptual distinction, but adds little parameter-level meaning the schema does not already state. Baseline 3 is appropriate.

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?

Opens with a specific verb and resource: 'List the 5%-and-over beneficial owners of a public company, parsed from the structured SCHEDULE 13D and SCHEDULE 13G filings.' It immediately differentiates itself from secedgar_get_institutional_holdings by naming the input inversion (issuer vs. manager), so an agent can route correctly 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?

Explicitly states when to use this versus the sibling ('the input is the ISSUER... the opposite direction from secedgar_get_institutional_holdings, where the input is the manager'), warns against the common misuse ('passing an investment manager here returns... almost always empty' in the schema, echoed in the description's framing), and explains the 13D/13G selection criterion substantively. It also hands off the downstream workflow (describe then query the dataframe).

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.