Skip to main content
Glama

Get Insider Transactions

secedgar_get_insider_transactions
Read-onlyIdempotent

Fetch Form 4 insider transactions (purchases, sales, grants, exercises) for a company by parsing SEC EDGAR ownership XML. Returns the reporting person, their relationship to the issuer, transaction date, type, shares traded (absolute magnitude), direction (acquire/dispose), price per share, and shares owned after the transaction. Covers nonDerivative transactions (open-market buys/sells, gifts) and derivative transactions (option exercises, RSU vests). Without a date window it reads the newest Form 4 filings; filed_after / filed_before read any period since mid-2003, reaching past the recent submissions window into the archive (e.g. insider trades in the quarter before an earnings miss). When a canvas is available, the full set of transactions parsed from the scanned filings is materialized as df_ (the inline list is a preview capped at limit) — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate net buy/sell by insider: SUM(CASE WHEN direction='dispose' THEN -shares_traded ELSE shares_traded END). Use secedgar_search_filings with forms=["4"] to search Form 4 filings across all companies.

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": {
      "company": "<company>"
    },
    "name": "secedgar_get_insider_transactions"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20. Capped at 100: a larger value, up to 1000, returns what 100 returns.
companyYesThe issuer whose Form 4 filings to read — the company, not the reporting person. A ticker symbol (e.g., "AAPL"), a CIK with or without zero-padding (e.g., "320193" or "0000320193"), or a company name (current or former). A name matching several companies fails and lists them, so retry with one's ticker or CIK.
filed_afterNoOnly read Form 4 filings filed on or after this date (YYYY-MM-DD). A date window reaches filings older than the recent submissions window by paging into the archive, and with a canvas every Form 4 filed inside it is parsed, up to 100. Structured Form 4 XML begins in mid-2003, so an earlier window finds nothing.
filed_beforeNoOnly read Form 4 filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after. Without either bound the tool reads the newest Form 4 filings.
transaction_typeNoFilter by direction. "purchase" = open-market buys (code P). "sale" = open-market sells (code S). "all" includes grants, awards, exercises, gifts, and other coded transaction types as well.all

Output Schema

NameRequiredDescriptionDefault
capNoThe limit cap applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of transactions shown inline.
noticeNoWhy the result is empty (the filter, or every scanned filing naming another issuer), and the dataframe pointer when staged.
datasetNoDataframe of every parsed transaction, issuer keys on each row, for net buy/sell by insider and cross-issuer joins. Absent when canvas is unavailable or nothing parsed.
truncatedNoTrue when the inline transactions[] was capped by limit.
issuer_cikNoIssuer CIK, zero-padded to 10 digits.
resolvedAsNoHow the input was read: a ticker spelling, former ticker, earlier holder, or entity-index match.
issuer_nameNoIssuer entity name (SEC-conformed).
transactionsNoInsider transactions, newest filing first, capped at limit; the dataframe holds the full parsed set.
issuer_tickerNoIssuer ticker symbol when available.
filings_scannedNoForm 4 filings scanned, including those in filings_other_issuer.
filings_other_issuerNoScanned Form 4 filings naming a different issuer, filed by this company as that issuer's reporting owner (e.g., a 10% holder of a fund); they add no transactions here or to the dataframe.
history_scanned_throughNoFiling date of the oldest Form 4 parsed (YYYY-MM-DD). Present only with a date window that held a Form 4.

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. Changed5 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: `company_not_found`: The company input does not resolve to a known company. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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: `company_not_found`: The company input does not resolve to a known company. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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: -[
      -  "company_not_found",
      -  "ambiguous_company",
      -  "no_filings_found",
      -  "rate_limited",
      -  "sec_unreachable"
      -]New value: +[
      +  "company_not_found",
      +  "ambiguous_company",
      +  "no_filings_found",
      +  "rate_limited",
      +  "sec_unreachable",
      +  "sec_unavailable"
      +]
    • changedOutput schema / properties / filings_other_issuer / description
      Previous value: -"Scanned Form 4 filings naming a different issuer, filed by this company as a reporting owner of another (e.g., a 10% holder of a fund). They are that issuer's activity, so they add no transactions here or in the dataframe."New value: +"Scanned Form 4 filings naming a different issuer, filed by this company as that issuer's reporting owner (e.g., a 10% holder of a fund); they add no transactions here or to the dataframe."
    • addedOutput schema / properties / resolvedAs
      Added value: +{
      +  "description": "How an unlisted ticker spelling was read, e.g. \"UEC.N read as UEC\".",
      +  "type": "string"
      +}
  3. Changed3 schema fields changed
    • changedInput schema / properties / company / description
      Previous value: -"The issuer whose Form 4 filings to read — the company, not the reporting person. A ticker symbol (e.g., \"AAPL\"), a CIK with or without zero-padding (e.g., \"320193\" or \"0000320193\"), or a company name (current or former). A name matching several companies resolves to the top-ranked one — exact name first, then prefix, then substring — so pass a ticker or CIK when the issuer must be exact."New value: +"The issuer whose Form 4 filings to read — the company, not the reporting person. A ticker symbol (e.g., \"AAPL\"), a CIK with or without zero-padding (e.g., \"320193\" or \"0000320193\"), or a company name (current or former). A name matching several companies fails and lists them, so retry with one's ticker or CIK."
    • 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. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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: `company_not_found`: The company input does not resolve to a known company. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "company_not_found",
      -  "no_filings_found",
      -  "rate_limited",
      -  "sec_unreachable"
      -]New value: +[
      +  "company_not_found",
      +  "ambiguous_company",
      +  "no_filings_found",
      +  "rate_limited",
      +  "sec_unreachable"
      +]
  4. Changed2 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20."New value: +"Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20. Capped at 100: a larger value, up to 1000, returns what 100 returns."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +1000
  5. Changed1 schema field changed
    • 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. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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: `company_not_found`: The company input does not resolve to a known company. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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."
  6. Changed2 schema fields changed
    • 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. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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: -[
      -  "company_not_found",
      -  "no_filings_found",
      -  "rate_limited"
      -]New value: +[
      +  "company_not_found",
      +  "no_filings_found",
      +  "rate_limited",
      +  "sec_unreachable"
      +]
  7. Changed18 schema fields changed
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "issuer_name",
      -      "issuer_cik",
      -      "transactions",
      -      "filings_scanned"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "issuer_name",
      +      "issuer_cik",
      +      "transactions",
      +      "filings_scanned",
      +      "filings_other_issuer"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / dataset / description
      Previous value: -"Canvas dataframe holding the full parsed transaction set from the scanned filings (the inline transactions[] is a preview capped at limit). Each row carries the issuer (issuer_cik, issuer_ticker) plus the transaction fields, so it aggregates net buy/sell by insider and joins across issuers. Query with secedgar_dataframe_query. Absent when canvas is unavailable or no transactions were parsed."New value: +"Dataframe of every parsed transaction, issuer keys on each row, for net buy/sell by insider and cross-issuer joins. 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 Form 4 filings exist beyond those parsed — past the newest-filings sample, or, with a date window, inside the window beyond the 100-filing cap or past the 10 archive pages read. Narrow the window to reach the rest."New value: +"True when Form 4 filings exist past those parsed (the newest-filings sample, or a window's 100-filing or 10-page cap); narrow the window to reach them."
    • addedOutput schema / properties / filings_other_issuer
      Added value: +{
      +  "description": "Scanned Form 4 filings naming a different issuer, filed by this company as a reporting owner of another (e.g., a 10% holder of a fund). They are that issuer's activity, so they add no transactions here or in the dataframe.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / filings_scanned / description
      Previous value: -"Number of Form 4 filings scanned to produce the result."New value: +"Form 4 filings scanned, including those in filings_other_issuer."
    • changedOutput schema / properties / history_scanned_through / description
      Previous value: -"Filing date of the oldest Form 4 parsed (YYYY-MM-DD). Present only when a date window was given; absent when the window held no Form 4 filing."New value: +"Filing date of the oldest Form 4 parsed (YYYY-MM-DD). Present only with a date window that held a Form 4."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when results are empty after filtering — explains the filter applied and suggests alternatives."New value: +"Why the result is empty (the filter, or every scanned filing naming another issuer), and the dataframe pointer when staged."
    • changedOutput schema / properties / transactions / description
      Previous value: -"Insider transactions, newest filing first. Preview capped at `limit` — the full scanned set lives on the canvas dataframe (see `dataset`)."New value: +"Insider transactions, newest filing first, capped at limit; the dataframe holds the full parsed set."
    • changedOutput schema / properties / transactions / items / properties / direction / description
      Previous value: -"Whether shares were acquired or disposed. \"acquire\" = buy, award, exercise; \"dispose\" = sale, gift, return. Absent when shares_traded is absent."New value: +"\"acquire\" (buy, award, exercise) or \"dispose\" (sale, gift, return). Absent when shares_traded is."
    • changedOutput schema / properties / transactions / items / properties / is_derivative / description
      Previous value: -"True for derivative security transactions (options, RSUs, convertible notes). False for direct equity transactions."New value: +"True for derivative securities (options, RSUs, convertible notes); false for direct equity."
    • changedOutput schema / properties / transactions / items / properties / ownership_nature / description
      Previous value: -"Nature of indirect ownership (e.g., \"By Trust\", \"By Spouse\"). Only present when ownership_type is indirect."New value: +"Nature of indirect ownership (e.g., \"By Trust\"). Present only when ownership_type is indirect."
    • changedOutput schema / properties / transactions / items / properties / ownership_type / description
      Previous value: -"D = direct ownership, I = indirect (through a trust, family member, etc.). Absent when not reported."New value: +"Direct, or indirect (through a trust, family member, etc.). Absent when not reported."
    • changedOutput schema / properties / transactions / items / properties / price_per_share / description
      Previous value: -"Price per share in USD. 0 for gifts and RSU awards (no cash consideration). Absent when not reported."New value: +"Price per share in USD; 0 for gifts and RSU awards. Absent when not reported."
    • changedOutput schema / properties / transactions / items / properties / shares_owned_after / description
      Previous value: -"Total shares owned after this transaction, as reported. Absent when omitted by the filer."New value: +"Shares owned after this transaction, as reported. Absent when omitted."
    • changedOutput schema / properties / transactions / items / properties / shares_traded / description
      Previous value: -"Absolute number of shares involved (always positive). Absent when the filing omits this field. Use `direction` to distinguish acquisitions from disposals."New value: +"Shares involved, always positive; direction gives the sign. Absent when the filing omits it."
    • changedOutput schema / properties / transactions / items / properties / transaction_code / description
      Previous value: -"Single-letter SEC transaction code: P = purchase, S = sale, M = exercise, A = award, G = gift, F = tax withholding, C = conversion, others exist."New value: +"SEC transaction code: P purchase, S sale, M exercise, A award, G gift, F tax withholding, C conversion, among others."
    • changedOutput schema / properties / transactions / items / properties / transaction_type / description
      Previous value: -"Human-readable description of the transaction code (e.g., \"purchase\", \"sale\", \"conversion_of_derivative\")."New value: +"Plain-language name of the code (e.g., \"purchase\", \"conversion_of_derivative\")."
  8. Changed5 schema fields changed
    • addedInput schema / properties / filed_after
      Added value: +{
      +  "anyOf": [
      +    {
      +      "const": "",
      +      "type": "string"
      +    },
      +    {
      +      "description": "YYYY-MM-DD",
      +      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +      "type": "string"
      +    }
      +  ],
      +  "description": "Only read Form 4 filings filed on or after this date (YYYY-MM-DD). A date window reaches filings older than the recent submissions window by paging into the archive, and with a canvas every Form 4 filed inside it is parsed, up to 100. Structured Form 4 XML begins in mid-2003, so an earlier window finds nothing."
      +}
    • addedInput schema / properties / filed_before
      Added value: +{
      +  "anyOf": [
      +    {
      +      "const": "",
      +      "type": "string"
      +    },
      +    {
      +      "description": "YYYY-MM-DD",
      +      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +      "type": "string"
      +    }
      +  ],
      +  "description": "Only read Form 4 filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after. Without either bound the tool reads the newest Form 4 filings."
      +}
    • changedOutput schema / properties / dataset / properties / truncated / description
      Previous value: -"True when more recent Form 4 filings exist beyond the scanned window — the dataframe is a recent sample, not the issuer's full Form 4 history. Use secedgar_search_filings with forms=[\"4\"] for exhaustive coverage."New value: +"True when Form 4 filings exist beyond those parsed — past the newest-filings sample, or, with a date window, inside the window beyond the 100-filing cap or past the 10 archive pages read. Narrow the window to reach the rest."
    • 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. `no_filings_found`: No Form 4 filings exist for this company in the recent submissions window. `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. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `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."
    • addedOutput schema / properties / history_scanned_through
      Added value: +{
      +  "description": "Filing date of the oldest Form 4 parsed (YYYY-MM-DD). Present only when a date window was given; absent when the window held no Form 4 filing.",
      +  "type": "string"
      +}
  9. Changed5 schema fields changed
    • addedInput schema / properties / company
      Added value: +{
      +  "description": "The issuer whose Form 4 filings to read — the company, not the reporting person. A ticker symbol (e.g., \"AAPL\"), a CIK with or without zero-padding (e.g., \"320193\" or \"0000320193\"), or a company name (current or former). A name matching several companies resolves to the top-ranked one — exact name first, then prefix, then substring — so pass a ticker or CIK when the issuer must be exact.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / properties / ticker_or_cik
      Removed value: -{
      -  "description": "Company ticker symbol (e.g., \"AAPL\") or 10-digit CIK number (e.g., \"0000320193\"). The issuer, not the reporting person.",
      -  "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 `no_filings_found`: No Form 4 filings exist for this company in the recent submissions window 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. `no_filings_found`: No Form 4 filings exist for this company in the recent submissions window. `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",
      -  "no_filings_found"
      -]New value: +[
      +  "company_not_found",
      +  "no_filings_found",
      +  "rate_limited"
      +]
  10. 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."
  11. 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_name",
      +      "issuer_cik",
      +      "transactions",
      +      "filings_scanned"
      +    ]
      +  },
      +  {
      +    "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 `no_filings_found`: No Form 4 filings exist for this company in the recent submissions window Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "company_not_found",
      +            "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_name",
      -  "issuer_cik",
      -  "transactions",
      -  "filings_scanned"
      -]
  12. 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 transactions shown inline.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the inline transactions[] was capped by limit.",
      +  "type": "boolean"
      +}
  13. Changed4 schema fields changed
    • addedOutput schema / properties / dataset
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Canvas dataframe holding the full parsed transaction set from the scanned filings (the inline transactions[] is a preview capped at limit). Each row carries the issuer (issuer_cik, issuer_ticker) plus the transaction fields, so it aggregates net buy/sell by insider and joins across issuers. Query with secedgar_dataframe_query. Absent when canvas is unavailable or no transactions were parsed.",
      +  "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"
      +    },
      +    "truncated": {
      +      "description": "True when more recent Form 4 filings exist beyond the scanned window — the dataframe is a recent sample, not the issuer's full Form 4 history. Use secedgar_search_filings with forms=[\"4\"] for exhaustive coverage.",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "name",
      +    "row_count",
      +    "expires_at",
      +    "truncated"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / transactions / description
      Previous value: -"Insider transactions, newest filing first."New value: +"Insider transactions, newest filing first. Preview capped at `limit` — the full scanned set lives on the canvas dataframe (see `dataset`)."
    • addedOutput schema / properties / transactions / items / properties / direction
      Added value: +{
      +  "description": "Whether shares were acquired or disposed. \"acquire\" = buy, award, exercise; \"dispose\" = sale, gift, return. Absent when shares_traded is absent.",
      +  "enum": [
      +    "acquire",
      +    "dispose"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / transactions / items / properties / shares_traded / description
      Previous value: -"Shares involved. Negative = disposal (sale, return, gift), positive = acquisition. Absent when the filing omits this field."New value: +"Absolute number of shares involved (always positive). Absent when the filing omits this field. Use `direction` to distinguish acquisitions from disposals."
  14. Added

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/idempotent, so the description carries real weight and adds source-level detail: it parses SEC EDGAR ownership XML, spans nonDerivative and derivative sections, and reports shares as absolute magnitude plus a separate acquire/dispose direction. It also discloses the canvas behavior (df_<id> materialization with limit-capped inline preview) that annotations cannot express, and the mid-2003 XML horizon that bounds results.

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?

It is front-loaded with the return-value contract and usage rules, and each sentence carries information. There is minor redundancy in enumerating transaction kinds twice (purchases/sales/grants/exercises and again open-market buys/sells, gifts, option exercises, RSU vests), and the inline SQL snippet is arguably beyond a tool description, but overall it is efficient.

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 an output schema present the description needn't explain return values, yet it still sketches them, and it covers the safety profile via annotations plus the canvas/preview mechanics. For a five-parameter read tool with a table output, an agent has everything needed to call it and follow up 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% and the schema already documents the limit cap, the issuer-not-reporting-person distinction, name ambiguity retries, and date formats. The description restates the date-window semantics but adds little parameter syntax beyond what the schema provides, so the 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?

The description leads with a specific verb and resource ("Fetch Form 4 insider transactions") and enumerates the transaction kinds covered (purchases, sales, grants, exercises), listing the exact return fields. It clearly separates this tool from secedgar_search_filings and secedgar_get_beneficial_owners, so an agent can identify it without opening the 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?

It states explicitly when no date window applies ("reads the newest Form 4 filings"), what a filed_after/filed_before window buys you (archive access back to mid-2003, e.g. trades before an earnings miss), and names alternatives with the condition that selects them: secedgar_search_filings with forms=["4"] for cross-company search, and dataframe_describe/query for aggregation. Nothing is left to inference.

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.