Skip to main content
Glama

Sec Insider

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Insider Top Buyers

insider_top_buyers
Read-onlyIdempotent

Stock purchases by a company's insiders and major holders, from SEC Form 4 — one buyer at one company, every buyer at one company, or the biggest buyers market-wide: "how much Occidental stock did Berkshire Hathaway buy in March", "insider buying at Pfizer this quarter", "which insiders bought the most stock recently", "largest insider purchase last month". Pass issuer (ticker or company name) and owner (a person or a firm, e.g. "Berkshire") to narrow it, since/until for the period, and group_by "owner" for one buyer's total across several filings. Officers, directors and 10% owners — including large investors and funds holding over 10% of a company — file a Form 4 within two business days of every trade, so this gives the exact trade dates, shares, price per share and dollar value inside any month or week. Returns the insider name and role, the issuer and ticker, shares, price and value. Counts only transaction code P, a purchase at market; option exercises, grants and tax withholding are excluded because none of them is a decision to buy. Ranks over every row in the window — never a capped slice — and reports rows_considered so a cut is never silent. A price the filer states in another currency (e.g. Brazilian reais, in a footnote) is left out and counted in non_usd_rows_excluded, never ranked as dollars. A price that looks like a filer data-entry error is left out unless include_suspect is set, and a report filed as several parts counts as one filing. Sourced from SEC Forms 3/4/5.

Input Schema

NameRequiredDescriptionDefault
limitNoHow many to return (default 20, max 100).
ownerNoLimit to one insider — name substring (e.g. "Berkshire") or SEC CIK.
sinceNoEarliest transaction date, ISO (YYYY-MM-DD). Defaults to the last 90 days of the loaded window.
untilNoLatest transaction date, ISO (YYYY-MM-DD).
issuerNoLimit to one issuer — ticker (e.g. "LEN") or SEC CIK. Substring match on issuer name also works.
group_byNoHow to roll transactions up before ranking. "filing" (default): sum every row on the same Form 4 into one total — a filing often reports one decision as several price-band lines, and a price-band row has no economic meaning on its own. A report filed as several documents for the same issuer, the same reporting owners and the same period of report, whose parts start on the same trade date (a long transaction table split across accessions), counts as one filing; accession_numbers lists every part. "row": rank individual transaction lines. "owner": sum every filing by the same insider against the same issuer across the whole window (e.g. several purchases over several days).
exclude_fundsNoDrop issuers that are funds reporting unitholders, not operating companies with real insiders (e.g. a BDC or interval fund). Best-effort name/security-type heuristic. Default false.
min_value_usdNoIgnore transactions below this dollar value.
include_suspectNoInclude transactions whose price looks like a filer data-entry error (see the caveat). Default false — suspect rows are excluded from rankings.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / exclude_funds
      Added value: +{
+  "description": "Drop issuers that are funds reporting unitholders, not operating companies with real insiders (e.g. a BDC or interval fund). Best-effort name/security-type heuristic. Default false.",
+  "type": "boolean"
+}
    • addedInput schema / properties / group_by
      Added value: +{
+  "description": "How to roll transactions up before ranking. \"filing\" (default): sum every row on the same Form 4 into one total — a filing often reports one decision as several price-band lines, and a price-band row has no economic meaning on its own. A report filed as several documents for the same issuer, the same reporting owners and the same period of report, whose parts start on the same trade date (a long transaction table split across accessions), counts as one filing; accession_numbers lists every part. \"row\": rank individual transaction lines. \"owner\": sum every filing by the same insider against the same issuer across the whole window (e.g. several purchases over several days).",
+  "enum": [
+    "row",
+    "filing",
+    "owner"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / include_suspect
      Added value: +{
+  "description": "Include transactions whose price looks like a filer data-entry error (see the caveat). Default false — suspect rows are excluded from rankings.",
+  "type": "boolean"
+}
    • addedInput schema / properties / issuer
      Added value: +{
+  "description": "Limit to one issuer — ticker (e.g. \"LEN\") or SEC CIK. Substring match on issuer name also works.",
+  "type": "string"
+}
    • changedInput schema / properties / min_value_usd / description
      Previous value: -"Ignore purchases below this dollar value."New value: +"Ignore transactions below this dollar value."
    • addedInput schema / properties / owner
      Added value: +{
+  "description": "Limit to one insider — name substring (e.g. \"Berkshire\") or SEC CIK.",
+  "type": "string"
+}
  2. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the read-only annotations, the description discloses critical behavior: only transaction code P is counted, option exercises and grants are excluded, rankings cover every row in the window (never a capped slice), rows_considered is reported, non-USD prices are excluded and counted, suspect prices are omitted unless include_suspect is set, and multi-part filings are merged. This is exactly the kind of context an agent needs to trust and interpret the output.

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 description is long but dense and front-loads the core purpose and examples. Every sentence contributes either scope clarification, query examples, or critical behavioral caveats, though the single-paragraph format could be slightly more scannable.

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 no output schema, the description still describes return fields (insider name and role, issuer/ticker, shares, price, value), ranking behavior, exclusion counts, and edge cases. Together with the detailed input schema and safety annotations, an agent has everything needed to call and interpret the tool 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 description coverage is 100%, so the schema already documents all nine parameters in detail. The description adds only high-level usage guidance (issuer/owner to narrow, since/until for period, group_by 'owner' for one buyer's total) that is largely redundant with the schema, though it does reinforce the intent of grouping and suspect handling.

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 states a specific verb and resource (stock purchases by insiders from SEC Form 4) and immediately distinguishes three scopes: one buyer, one company, and market-wide. The example queries make it unmistakable how this tool differs from a generic search or from its sibling insider_top_sellers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete example questions and explains how to narrow results with issuer, owner, since/until, and group_by. However, it does not explicitly name the alternative tool (insider_top_sellers) or state when not to use this one, leaving that inference to the agent.

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

All Sec Insider toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources