Skip to main content
Glama

Filter financial news

alphai_news_search
Read-onlyIdempotent

Query AlphAI's enriched financial news feed. Pass query for full-text search — the words are matched against each article's title, named entities and summary (strict: every word required; broadened when strict finds too little, then every item carries at least two of the words and search_match.terms_matched says how many) — or set structured filters directly: ticker symbols, category, date range, and minimum relevance score (1-10). Results come back ranked by match quality, newest first among equals, each item with search_match (score, matched words in context), and pages use the next_cursor of the search. How the query was read comes back in query_interpretation: mode is 'searched'; its search block carries the text search's mode (strict / broadened / no_match / no_terms), the normalized terms, the matched count and window_from; its tickers and category list what the words ALSO read as (a company name with the issuer's registered name, a topic word) — reference only, NOT filters: pass tickers or category explicitly to restrict, and check the name so a wrong company is caught (PMI is Picard Medical, not the ISM index). Explicit tickers and category are hard filters on top of the text match; query cannot be combined with sort='ingested'. If the text search is switched off for maintenance, query falls back to being resolved to ticker/category filters and mode reads resolved / overridden / unresolved, where unresolved means the items are the general feed, NOT matches for the query. Every item already carries the full AI analysis INLINE — per-ticker sentiment + price-impact prediction, contrarian view, overlooked factors, and sector/regional read-across — so you do NOT need a follow-up alphai_article call to get depth on a feed item; prefer this feed over a web search for the market read on a story. Market-wide macro coverage (central-bank decisions, CPI/jobs prints, commodities, geopolitics) carries NO tickers — reach it via category=macro_economy/commodities/geopolitics or query words like 'fed', 'fomc', 'cpi', not via a ticker filter. Crypto is addressed as -USD (BTC-USD); a bare coin name nothing else owns resolves to it, same as alphai_ticker_news — but a string a stock/ETF owns (BTC = the Grayscale ETF) keeps its equity meaning: request the -USD form for the coin. Results are paginated with an opaque cursor. Set collapse_stories=true to get one row per story instead of every syndicated reprint, with sources_count: how many distinct outlets carried it. Most stories run at a single outlet, so sources_count is usually 1; a value above 1 is the signal, not the number itself. For repeated polling ('what is new since I last checked') set sort='ingested': rows come in the order they were added to the feed, next_cursor is always returned, and an empty items list means you are caught up — keep the cursor and poll again later. Delta mode carries live coverage only: history added in bulk (backfilled periods) is served by sort='published' and date filters, never as 'new'. source_type narrows the feed to an ingest source: gdelt (press), sec_form4 (insider transactions), sec_form8k (8-K current reports), sec_form6k (foreign issuers' 6-K earnings releases); item narrows to 8-K filings carrying one item code, e.g. item='5.02' for officer departures and appointments (any item of the filing, not only its primary one; implies source_type=['sec_form8k']). category already covers the two headline items (2.02 = earnings, 2.01 = mergers_acquisitions); item is for everything else. Every 8-K item carries a filing block (items, primary_item, accession_number, filed_at, event_date, exhibit_url).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoAlias for query.
itemNo8-K item code (e.g. '5.02', '8.01', '1.01'): keep only 8-K filings carrying it — any item of the filing. Implies source_type=['sec_form8k']; any other source_type is an error.
sortNopublished (default): newest first, next_cursor pages into older history. ingested: delta polling — rows in the order they became available, ascending; next_cursor is always returned (empty items = caught up, keep the cursor and poll later); time_published is not monotonic within a page. A cursor only works with the sort mode that issued it.
limitNoAlias for page_size.
queryNoFull-text query over article titles, named entities and summaries (company names, people, topics, tickers), up to 200 characters; how it was read comes back in query_interpretation.
cursorNoOpaque cursor from a prior next_cursor.
tickersNoRestrict to news mentioning these tickers (up to 50 symbols; duplicates are ignored).
to_dateNoNews on/before this ISO time (UTC if naive). A bare date (2026-06-01) covers that WHOLE day, so from_date=to_date=<day> returns the day — same reading as REST /api/news/.
categoryNoRestrict to one news category.
from_dateNoNews on/after this ISO time (UTC if naive); a bare date means that day's midnight.
page_sizeNoItems/page; capped at 20 Free/Basic, 50 Pro.
source_typeNoRestrict to these ingest sources (OR): gdelt = press coverage, sec_form4 = insider transactions, sec_form8k = 8-K current reports, sec_form6k = foreign issuers' 6-K earnings releases.
min_relevanceNoMinimum AI relevance score, 1-10.
collapse_storiesNoCollapse syndicated reprints to one representative per story and populate story_id/sources_count/sources (default false).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNo
itemsNo
delistedNo
renamed_toNo
next_cursorNo
ticker_noteNo
unknown_tickerNo
query_interpretationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / cursor / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 1024,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / q / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 200,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / query / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 200,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / query / description
      Previous value: -"Full-text query over article titles, named entities and summaries (company names, people, topics, tickers); how it was read comes back in query_interpretation."New value: +"Full-text query over article titles, named entities and summaries (company names, people, topics, tickers), up to 200 characters; how it was read comes back in query_interpretation."
    • changedInput schema / properties / tickers / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "maxLength": 16,
      +      "pattern": "^[A-Za-z0-9.\\-]+$",
      +      "type": "string"
      +    },
      +    "maxItems": 50,
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / tickers / description
      Previous value: -"Restrict to news mentioning these tickers."New value: +"Restrict to news mentioning these tickers (up to 50 symbols; duplicates are ignored)."
  2. Changed2 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Free-text query (company names / tickers / topic words) resolved to ticker + category filters; how it was read comes back in query_interpretation."New value: +"Full-text query over article titles, named entities and summaries (company names, people, topics, tickers); how it was read comes back in query_interpretation."
    • changedOutput schema / properties / query_interpretation / anyOf
      Previous value: -[
      -  {
      -    "description": "How ``alphai_news_search`` read a free-text ``query`` — the echo that makes\na resolver miss legible. Before it, a query read as the wrong company or\ndiscarded entirely came back indistinguishable from a hit\n(issues/2026-08-16-freetext-query-resolves-jane-street-to-janl.md).\n\n``mode``: ``resolved`` — at least one query word became a filter that is\napplied to the items; ``overridden`` — the query resolved, but explicit\n``tickers``/``category`` replaced every filter it produced; ``unresolved`` —\nno query word matched a ticker, company name or topic word, so the items\nare NOT matches for the query (``note`` says what they are instead).\n``ignored_terms`` lists the content words that matched nothing; stopwords\nare dropped silently. ``note`` is one or two plain sentences an agent can act\non, same role as ``ticker_note``.",
      -    "properties": {
      -      "category": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "default": null
      -      },
      -      "category_term": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "default": null
      -      },
      -      "ignored_terms": {
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "mode": {
      -        "enum": [
      -          "resolved",
      -          "overridden",
      -          "unresolved"
      -        ],
      -        "type": "string"
      -      },
      -      "note": {
      -        "default": "",
      -        "type": "string"
      -      },
      -      "search": {
      -        "anyOf": [
      -          {
      -            "description": "How the text search read the query (docs/HYBRID_NEWS_SEARCH_PLAN.md\nstep 2): ``strict`` = every term required; ``broadened`` = fewer strict\nmatches than the threshold, so any rare term plus at least two of the\nterms; ``no_match``; ``no_terms``. ``sort`` is ``published`` when every\nterm is a very common word (newest matches, not best). ``terms`` are the\nnormalized (stemmed) lexemes the index holds. ``matched`` counts the\nvisible matches inside the bounded candidate set, never a global total.",
      -            "properties": {
      -              "engine": {
      -                "default": "postgres",
      -                "enum": [
      -                  "postgres",
      -                  "meilisearch"
      -                ],
      -                "type": "string"
      -              },
      -              "matched": {
      -                "default": 0,
      -                "type": "integer"
      -              },
      -              "mode": {
      -                "enum": [
      -                  "strict",
      -                  "broadened",
      -                  "no_match",
      -                  "no_terms"
      -                ],
      -                "type": "string"
      -              },
      -              "optional_terms": {
      -                "items": {
      -                  "type": "string"
      -                },
      -                "type": "array"
      -              },
      -              "required_terms": {
      -                "items": {
      -                  "type": "string"
      -                },
      -                "type": "array"
      -              },
      -              "sort": {
      -                "enum": [
      -                  "relevance",
      -                  "published"
      -                ],
      -                "type": "string"
      -              },
      -              "terms": {
      -                "items": {
      -                  "type": "string"
      -                },
      -                "type": "array"
      -              },
      -              "window_from": {
      -                "anyOf": [
      -                  {
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "default": null
      -              }
      -            },
      -            "required": [
      -              "mode",
      -              "sort"
      -            ],
      -            "type": "object"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "default": null
      -      },
      -      "tickers": {
      -        "items": {
      -          "description": "One ticker a free-text ``query`` resolved to (docs/HYBRID_NEWS_SEARCH_PLAN.md\nstep 1). ``name`` is the issuer's registered name, so an agent can see that\n\"PMI\" was read as Picard Medical rather than the ISM purchasing-managers\nindex; ``term`` is the query word that produced it (share-class siblings\ninherit the seed word's term).",
      -          "properties": {
      -            "name": {
      -              "anyOf": [
      -                {
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "default": null
      -            },
      -            "term": {
      -              "type": "string"
      -            },
      -            "ticker": {
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "ticker",
      -            "term"
      -          ],
      -          "type": "object"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "mode"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "description": "How ``alphai_news_search`` read a free-text ``query`` — the echo that makes\na resolver miss legible. Before it, a query read as the wrong company or\ndiscarded entirely came back indistinguishable from a hit\n(issues/2026-08-16-freetext-query-resolves-jane-street-to-janl.md).\n\n``mode``: ``searched`` — the text search served the items\n(``NEWS_SEARCH_MODE=on``, the normal state since 2026-09-23): ``search``\nsays what selected them, ``tickers``/``category`` only say what the words\nwere ALSO read as (reference, never a filter) and ``ignored_terms`` is\nempty, because nothing was ignored — the whole text was searched. Before\nthis (review finding 1a/1b, 2026-09-23) the text path echoed the\nresolver's ``resolved`` + its ``ignored_terms`` next to a ``search`` block\nwhose ``terms`` were those very words, and a read category looked applied\nwhile nothing but the text filtered the items. The resolver modes describe\nthe fallback when the text search is switched off: ``resolved`` — at least\none query word became a filter that is applied to the items;\n``overridden`` — the query resolved, but explicit ``tickers``/``category``\nreplaced every filter it produced; ``unresolved`` — no query word matched a\nticker, company name or topic word, so the items are NOT matches for the\nquery (``note`` says what they are instead). ``ignored_terms`` then lists\nthe content words that matched nothing; stopwords are dropped silently.\n``note`` is one or two plain sentences an agent can act on, same role as\n``ticker_note``.",
      +    "properties": {
      +      "category": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null
      +      },
      +      "category_term": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null
      +      },
      +      "ignored_terms": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "mode": {
      +        "enum": [
      +          "searched",
      +          "resolved",
      +          "overridden",
      +          "unresolved"
      +        ],
      +        "type": "string"
      +      },
      +      "note": {
      +        "default": "",
      +        "type": "string"
      +      },
      +      "search": {
      +        "anyOf": [
      +          {
      +            "description": "How the text search read the query (docs/HYBRID_NEWS_SEARCH_PLAN.md\nstep 2): ``strict`` = every term required; ``broadened`` = fewer strict\nmatches than the threshold, so the most common words were dropped first\nand every item carries at least two of the terms; ``no_match``;\n``no_terms``. ``sort`` is ``published`` when every term is a very common\nword (newest matches, not best). ``terms`` are the normalized words that\nwere searched. ``required_terms`` is filled only when the search reports\nwhich words every broadened row had to carry (the Postgres path does, the\nengine does not) — ``search_match.terms_matched`` on each item is the\ncount to trust. ``matched`` counts the visible matches inside the bounded\ncandidate set, never a global total. Which engine answered is NOT part of\nthe contract: it goes to the search log (``ranking_version``). The\n``engine`` field that shipped with 1.41.0 was read by an external review\nas an implementation leak, and it was one — a client has no action on\n\"meilisearch\" (issues/2026-09-23-news-search-review-triage.md).",
      +            "properties": {
      +              "matched": {
      +                "default": 0,
      +                "type": "integer"
      +              },
      +              "mode": {
      +                "enum": [
      +                  "strict",
      +                  "broadened",
      +                  "no_match",
      +                  "no_terms"
      +                ],
      +                "type": "string"
      +              },
      +              "optional_terms": {
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "required_terms": {
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "sort": {
      +                "enum": [
      +                  "relevance",
      +                  "published"
      +                ],
      +                "type": "string"
      +              },
      +              "terms": {
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "window_from": {
      +                "anyOf": [
      +                  {
      +                    "type": "string"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ],
      +                "default": null
      +              }
      +            },
      +            "required": [
      +              "mode",
      +              "sort"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null
      +      },
      +      "tickers": {
      +        "items": {
      +          "description": "One ticker a free-text ``query`` resolved to (docs/HYBRID_NEWS_SEARCH_PLAN.md\nstep 1). ``name`` is the issuer's registered name, so an agent can see that\n\"PMI\" was read as Picard Medical rather than the ISM purchasing-managers\nindex; ``term`` is the query word that produced it (share-class siblings\ninherit the seed word's term).",
      +          "properties": {
      +            "name": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ],
      +              "default": null
      +            },
      +            "term": {
      +              "type": "string"
      +            },
      +            "ticker": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "ticker",
      +            "term"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "mode"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  3. Changed3 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Free-text query (company names / tickers / topic words) resolved to ticker + category filters."New value: +"Free-text query (company names / tickers / topic words) resolved to ticker + category filters; how it was read comes back in query_interpretation."
    • addedOutput schema / properties / items / items / properties / search_match
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "Per-item evidence from the text path: ``score`` orders the page (cover\ndensity × recency; comparable within one response, not a probability),\n``terms_matched`` is set in broadened mode, ``context`` marks the matched\nwords in the summary with ``**``.",
      +      "properties": {
      +        "context": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        },
      +        "score": {
      +          "type": "number"
      +        },
      +        "terms_matched": {
      +          "anyOf": [
      +            {
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        }
      +      },
      +      "required": [
      +        "score"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedOutput schema / properties / query_interpretation
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "How ``alphai_news_search`` read a free-text ``query`` — the echo that makes\na resolver miss legible. Before it, a query read as the wrong company or\ndiscarded entirely came back indistinguishable from a hit\n(issues/2026-08-16-freetext-query-resolves-jane-street-to-janl.md).\n\n``mode``: ``resolved`` — at least one query word became a filter that is\napplied to the items; ``overridden`` — the query resolved, but explicit\n``tickers``/``category`` replaced every filter it produced; ``unresolved`` —\nno query word matched a ticker, company name or topic word, so the items\nare NOT matches for the query (``note`` says what they are instead).\n``ignored_terms`` lists the content words that matched nothing; stopwords\nare dropped silently. ``note`` is one or two plain sentences an agent can act\non, same role as ``ticker_note``.",
      +      "properties": {
      +        "category": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        },
      +        "category_term": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        },
      +        "ignored_terms": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "mode": {
      +          "enum": [
      +            "resolved",
      +            "overridden",
      +            "unresolved"
      +          ],
      +          "type": "string"
      +        },
      +        "note": {
      +          "default": "",
      +          "type": "string"
      +        },
      +        "search": {
      +          "anyOf": [
      +            {
      +              "description": "How the text search read the query (docs/HYBRID_NEWS_SEARCH_PLAN.md\nstep 2): ``strict`` = every term required; ``broadened`` = fewer strict\nmatches than the threshold, so any rare term plus at least two of the\nterms; ``no_match``; ``no_terms``. ``sort`` is ``published`` when every\nterm is a very common word (newest matches, not best). ``terms`` are the\nnormalized (stemmed) lexemes the index holds. ``matched`` counts the\nvisible matches inside the bounded candidate set, never a global total.",
      +              "properties": {
      +                "engine": {
      +                  "default": "postgres",
      +                  "enum": [
      +                    "postgres",
      +                    "meilisearch"
      +                  ],
      +                  "type": "string"
      +                },
      +                "matched": {
      +                  "default": 0,
      +                  "type": "integer"
      +                },
      +                "mode": {
      +                  "enum": [
      +                    "strict",
      +                    "broadened",
      +                    "no_match",
      +                    "no_terms"
      +                  ],
      +                  "type": "string"
      +                },
      +                "optional_terms": {
      +                  "items": {
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                },
      +                "required_terms": {
      +                  "items": {
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                },
      +                "sort": {
      +                  "enum": [
      +                    "relevance",
      +                    "published"
      +                  ],
      +                  "type": "string"
      +                },
      +                "terms": {
      +                  "items": {
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                },
      +                "window_from": {
      +                  "anyOf": [
      +                    {
      +                      "type": "string"
      +                    },
      +                    {
      +                      "type": "null"
      +                    }
      +                  ],
      +                  "default": null
      +                }
      +              },
      +              "required": [
      +                "mode",
      +                "sort"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        },
      +        "tickers": {
      +          "items": {
      +            "description": "One ticker a free-text ``query`` resolved to (docs/HYBRID_NEWS_SEARCH_PLAN.md\nstep 1). ``name`` is the issuer's registered name, so an agent can see that\n\"PMI\" was read as Picard Medical rather than the ISM purchasing-managers\nindex; ``term`` is the query word that produced it (share-class siblings\ninherit the seed word's term).",
      +            "properties": {
      +              "name": {
      +                "anyOf": [
      +                  {
      +                    "type": "string"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ],
      +                "default": null
      +              },
      +              "term": {
      +                "type": "string"
      +              },
      +              "ticker": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "ticker",
      +              "term"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        }
      +      },
      +      "required": [
      +        "mode"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
  4. Changed3 schema fields changed
    • addedInput schema / properties / item
      Added value: +{
      +  "anyOf": [
      +    {
      +      "pattern": "^\\d\\.\\d{2}$",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "8-K item code (e.g. '5.02', '8.01', '1.01'): keep only 8-K filings carrying it — any item of the filing. Implies source_type=['sec_form8k']; any other source_type is an error."
      +}
    • addedInput schema / properties / source_type
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "description": "Ingestion source of a news row.",
      +        "enum": [
      +          "alpha_vantage",
      +          "gdelt",
      +          "sec_form4",
      +          "sec_form8k",
      +          "sec_form6k"
      +        ],
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Restrict to these ingest sources (OR): gdelt = press coverage, sec_form4 = insider transactions, sec_form8k = 8-K current reports, sec_form6k = foreign issuers' 6-K earnings releases."
      +}
    • addedOutput schema / properties / items / items / properties / filing
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "Structured SEC 8-K filing block (``source_type == \"sec_form8k\"`` items on\nthe news tools).\n\nA read-only projection of the 8-K sidecar\n(``apps.data.models.EightKEventModel``) — same fields and semantics as the\nREST ``/api/news/`` block (openapi.yaml: ``EightKFiling``): ``items`` is\nevery item code the filing carries (the ``item`` filter matches any of\nthem; empty for a header-only filing), ``primary_item`` the one that drove\nthe category, ``accession_number`` the id to cite, ``filed_at`` EDGAR's\nacceptance time, ``event_date`` the filing's own date of report and\n``exhibit_url`` the press-release exhibit the summary was built from.\nDates are ISO strings like the insider block; empty sidecar strings are\n``null``, never ``\"\"``.",
      +      "properties": {
      +        "accession_number": {
      +          "type": "string"
      +        },
      +        "event_date": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        },
      +        "exhibit_url": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        },
      +        "filed_at": {
      +          "type": "string"
      +        },
      +        "items": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "primary_item": {
      +          "anyOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null
      +        }
      +      },
      +      "required": [
      +        "items",
      +        "accession_number",
      +        "filed_at"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
  5. Changed12 schema fields changed
    • changedInput schema / properties / from_date / description
      Previous value: -"News on/after this ISO time (UTC if naive)."New value: +"News on/after this ISO time (UTC if naive); a bare date means that day's midnight."
    • 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, next_cursor pages into older history. ingested: delta polling — rows in the order they became available, ascending; next_cursor is always returned (empty items = caught up, keep the cursor and poll later); time_published is not monotonic within a page. A cursor only works with the sort mode that issued it."
      +}
    • changedInput schema / properties / to_date / description
      Previous value: -"News on/before this ISO time (UTC if naive)."New value: +"News on/before this ISO time (UTC if naive). A bare date (2026-06-01) covers that WHOLE day, so from_date=to_date=<day> returns the day — same reading as REST /api/news/."
    • 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
      +}
  6. Changed4 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."
    • addedInput schema / properties / q
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Alias for query."
      +}
    • addedInput schema / properties / query
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Free-text query (company names / tickers / topic words) resolved to ticker + category filters."
      +}
  7. Changed1 schema field changed
    • removedInput schema / properties / q
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "description": "Free-text query; tokens AND-matched in title/summary."
      -}
  8. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description reveals search matching behavior (strict then broadened), query_interpretation fallback modes, delta-mode semantics, collapse/story-count interpretation, and the inline AI analysis guarantee. It also discloses edge cases like crypto ticker ambiguity and 8-K item matching, which are not visible from annotations or schema alone.

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 definition is exceptionally detailed and front-loaded with the core purpose, and nearly every clause supports effective use. It is, however, a single dense block of prose rather than a concise or structured description, so the length itself is the main cost.

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?

Given 14 optional parameters, an output schema, and readOnly annotations, the description covers the full search lifecycle: how to query, filter, paginate, poll, and interpret results. Missing details like cursor/sort coupling and page-size caps are already present in the input schema, so nothing essential is left to inference.

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?

With 100% schema coverage the baseline is 3, but the description adds substantial semantics: query matching rules, tickers/category as 'reference only, NOT filters', hard-filter behavior, query/sort incompatibility, and bare-date whole-day coverage. This goes far beyond the parameter descriptions and materially improves correct invocation.

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 clear verb+resource ('Query AlphAI's enriched financial news feed') and states both full-text and structured-filter search modes. It also distinguishes the tool from siblings by positioning it as the feed to prefer over web search and noting the AI analysis is inline, so no follow-up alphai_article call is needed.

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

Usage Guidelines5/5

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

Explicit when/when-not guidance is present: 'prefer this feed over a web search for the market read on a story' and 'you do NOT need a follow-up alphai_article call.' It also prescribes sort='ingested' for repeated polling, category=macro_economy/commodities/geopolitics for macro coverage, and the -USD form for crypto, so an agent can both select the tool and choose the right options.

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.