Skip to main content
Glama

AlphaAI

by io.github.makeev

Insider & ownership news

alphai_insider_news
Read-onlyIdempotent

Insider-transaction news: SEC Form 4 insider trades (company officers, directors and 10% owners buying or selling their own stock). Optionally filter by ticker, date range, and whether the trade ran under a pre-scheduled Rule 10b5-1 plan (is_10b5_1=false hides planned sales, leaving discretionary trades). Cursor-paginated; same shape (incl. the full inline AI analysis) as alphai_news_search, and the same sort='ingested' delta polling for watching new filings arrive. Roughly equivalent to alphai_news_search(category='insider'), exposed as a dedicated tool. Sets unknown_ticker=true only for an unrecognized ticker filter; a delisted symbol serves its history with delisted=true and renamed_to set when the company continues under a new ticker. When the ticker is a crypto collider (BTC = the Grayscale ETF, not the coin), ticker_note names the -USD coin ticker.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNopublished (default): newest first. ingested: delta polling — only Form 4 events added since your cursor, ascending; next_cursor is always returned (empty items = caught up, keep the cursor and poll later). Prefer this for watching insider activity: a filing arrives days after its transaction date, so it can land below the newest page of a publish-ordered feed. A cursor only works with the sort mode that issued it.
limitNoAlias for page_size.
cursorNoOpaque cursor from a prior next_cursor.
tickerNoRestrict to one ticker, e.g. 'AAPL'.
to_dateNoOn/before this ISO time (UTC if naive); a bare date covers that whole day. Bounds when the filing reached the feed, not the insider's transaction_date.
from_dateNoOn/after this ISO time (UTC if naive); a bare date means that day's midnight.
is_10b5_1NoRule 10b5-1 filter, on the same field each item's insider block reports. Omit for every event; false = discretionary trades only (a 10b5-1 ladder was scheduled months earlier, so it carries no timing decision); true = plan events only. Event-level: a filing mixing plan and discretionary tranches counts as a plan event.
page_sizeNoItems/page; capped at 20 Free/Basic, 50 Pro.
min_relevanceNoMinimum AI relevance score, 1-10.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNo
itemsNo
delistedNo
renamed_toNo
next_cursorNo
ticker_noteNo
unknown_tickerNo

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed13 schema fields changed
    • changedInput schema / properties / from_date / description
      Previous value: -"On/after this ISO time (UTC if naive)."New value: +"On/after this ISO time (UTC if naive); a bare date means that day's midnight."
    • addedInput schema / properties / is_10b5_1
      Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Rule 10b5-1 filter, on the same field each item's insider block reports. Omit for every event; false = discretionary trades only (a 10b5-1 ladder was scheduled months earlier, so it carries no timing decision); true = plan events only. Event-level: a filing mixing plan and discretionary tranches counts as a plan event."
+}
    • changedInput schema / properties / page_size / description
      Previous value: -"Items/page; capped at 10 Basic / 50 Pro."New value: +"Items/page; capped at 20 Free/Basic, 50 Pro."
    • addedInput schema / properties / sort
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "published",
+        "ingested"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "published (default): newest first. ingested: delta polling — only Form 4 events added since your cursor, ascending; next_cursor is always returned (empty items = caught up, keep the cursor and poll later). Prefer this for watching insider activity: a filing arrives days after its transaction date, so it can land below the newest page of a publish-ordered feed. A cursor only works with the sort mode that issued it."
+}
    • changedInput schema / properties / to_date / description
      Previous value: -"On/before this ISO time (UTC if naive)."New value: +"On/before this ISO time (UTC if naive); a bare date covers that whole day. Bounds when the filing reached the feed, not the insider's transaction_date."
    • addedOutput schema / properties / delisted
      Added value: +{
+  "default": false,
+  "type": "boolean"
+}
    • addedOutput schema / properties / items / items / properties / created_at
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / items / items / properties / earnings
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
    • addedOutput schema / properties / items / items / properties / insider
      Added value: +{
+  "anyOf": [
+    {
+      "description": "Structured SEC Form 4 event block (``alphai_insider_news`` items only).\n\nAggregate of the news row's whole transaction group — same semantics as the\nREST ``/api/news/insider/`` block (openapi.yaml: ``InsiderEvent``): shares and\nvalue are GROUP sums (a 10b5-1 ladder is one event), ``avg_price_usd`` is\nvalue-weighted over priced tranches, ``is_10b5_1`` is the group OR, the\nlast fill dates the event. ``side`` is the signal label: buy (P) / sell (S)\n/ other (everything else, incl. D — sale to issuer, a buyback/redemption,\nnot an open-market disposition); the raw ``transaction_code`` rides along.\nMoney/share fields are decimal STRINGS (\"25000\", \"187.32\") — flat, precise,\nschema-simple; null when the filing prices no tranche.\n\n``filed_at`` is when EDGAR accepted the filing and ``late_filing`` marks the\nones that missed the SEC's two-business-day deadline; the rule lives in\n``_is_late_filing`` in ``repository.py`` (ported from the backend's\n``apps.insider.services.filing_lateness``). Field reference for both\nsurfaces: ``backend/openapi.yaml`` (``InsiderEvent``).",
+      "properties": {
+        "avg_price_usd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "filed_at": {
+          "type": "string"
+        },
+        "insider_name": {
+          "type": "string"
+        },
+        "insider_title": {
+          "type": "string"
+        },
+        "is_10b5_1": {
+          "type": "boolean"
+        },
+        "is_director": {
+          "type": "boolean"
+        },
+        "is_officer": {
+          "type": "boolean"
+        },
+        "is_ten_percent_owner": {
+          "type": "boolean"
+        },
+        "late_filing": {
+          "type": "boolean"
+        },
+        "shares": {
+          "type": "string"
+        },
+        "side": {
+          "type": "string"
+        },
+        "total_value_usd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "transaction_code": {
+          "type": "string"
+        },
+        "transaction_date": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "side",
+        "transaction_code",
+        "shares",
+        "is_10b5_1",
+        "insider_name",
+        "insider_title",
+        "is_officer",
+        "is_director",
+        "is_ten_percent_owner",
+        "transaction_date",
+        "filed_at",
+        "late_filing"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
    • addedOutput schema / properties / items / items / properties / source_type
      Added value: +{
+  "default": "",
+  "type": "string"
+}
    • changedOutput schema / properties / items / items / required
      Previous value: -[
-  "uid",
-  "title",
-  "url",
-  "source",
-  "source_domain",
-  "summary",
-  "category",
-  "relevance_score",
-  "time_published"
-]New value: +[
+  "uid",
+  "title",
+  "url",
+  "source",
+  "source_domain",
+  "summary",
+  "category",
+  "relevance_score",
+  "time_published",
+  "created_at"
+]
    • addedOutput schema / properties / renamed_to
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
    • addedOutput schema / properties / ticker_note
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
  2. Changed2 schema fields changed
    • addedInput schema / properties / limit
      Added value: +{
+  "anyOf": [
+    {
+      "maximum": 50,
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alias for page_size."
+}
    • changedInput schema / properties / page_size / description
      Previous value: -"Items/page. 10 Basic / 50 Pro (tools.bulk)."New value: +"Items/page; capped at 10 Basic / 50 Pro."
  3. First observed

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the read-only safety profile is covered. The description goes well beyond that: unknown_ticker behavior, delisted-symbol handling with renamed_to, crypto-collider disambiguation with ticker_note, the cursor-sort coupling rule, event-level 10b5-1 classification, and the caveat that to_date/from_date bound feed-ingest time rather than transaction date. Nothing contradicts 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence carries distinct value: the subject, the filters, the pagination contract, the sibling equivalence, ticker edge cases, and the crypto-collider note. It front-loads the core Form 4 purpose and only then adds edge-case behavior. Given the number of non-obvious behaviors it must convey, the length is justified and well organized.

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?

The tool has 9 parameters and an output schema, yet the description covers all behavior areas an agent needs to invoke it correctly: selection context, filtering semantics, pagination and cursor rules, sort-mode differences, ticker edge cases, and unknown-input signaling. The output schema handles return-shape details, so the description's job was to explain the non-obvious behavioral semantics, which it does completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description does far more than echo it. It explains the insider field, the event-level aggregation quirk for mixed plan/discretionary filings, what a cursor can and cannot do across sort modes, the delta-polling contract (empty items = caught up, keep polling), and the date-filter semantic difference between feed time and transaction date. This is substantial added meaning beyond the schema's property descriptions.

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 opens with a specific verb and resource: 'Insider-transaction news: SEC Form 4 insider trades...' It names the actors (officers, directors, 10% owners), the form type, and the optional filtering dimensions. It explicitly positions the tool against its sibling, 'Roughly equivalent to alphai_news_search(category='insider'), exposed as a dedicated tool,' which lets an agent distinguish it from alphai_news_search without opening schemas.

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?

The description gives concrete when-to-use guidance: use this when you need Form 4 insider filings; use the ingested sort for delta polling to watch new filings arrive; use is_10b5_1=false to isolate discretionary trades for timing analysis. It also explains the relationship to alphai_news_search(category='insider') rather than other siblings and flags the preference for ingested sorting when watching insider activity because filings arrive days after the transaction date.

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

All AlphaAI toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0
Disambiguation3/5

Multiple news feed tools (alphai_actionable_now, alphai_trending, alphai_macro, alphai_ticker_news, alphai_news_search, alphai_insider_news, and search) overlap in purpose, so an agent could pick the wrong one by name alone. The detailed descriptions clarify each tool's window, scope, and filtering, but the set still relies heavily on reading those descriptions to avoid misselection.

Naming Consistency3/5

Most tools share the alphai_ prefix and snake_case, but there is no consistent verb_noun pattern: alphai_alerts_subscribe and alphai_news_search are verb phrases while alphai_ticker_news, alphai_macro, and alphai_calendar are noun phrases. The un-prefixed connector tools search and fetch add a further deviation, making the naming readable but mixed.

Tool Count3/5

At 16 tools, the set is at the heavy end and includes several near-duplicates: alphai_news_search vs search, alphai_article vs fetch, and alphai_insider_news vs alphai_news_search(category='insider'). The domain is broad enough to justify many specialized feeds, but the redundancies make it feel padded.

Completeness4/5

The toolset covers news discovery, search, article retrieval, alerts lifecycle, macro calendar, earnings reads, ticker metadata, and pair comparisons, so agents can complete most workflows. Minor gaps remain, such as no story-level detail endpoint and no broader user-account or watchlist management beyond alerts.

Resources