Skip to main content
Glama
Tickerbot MCP Server

Tickerbot MCP Server

Official
by tickerbot

tickerbot_query_events

Query corporate events—earnings, dividends, splits, filings, insider trades, analyst actions, news and signals—with SQL filters by ticker or time window. Get stable IDs for deduplication.

Instructions

Queries events with SQL across every ticker or a screen's matches: earnings, dividends, splits, filings, insider trades and analyst actions, plus opt-in estimate revisions, news and signal firings. Requires at least one bound: a ticker scope (ticker/universe) or a time window (from/to); q alone is not a bound. With one kind, its payload fields are bare names in q/select/group_by (q: firm ILIKE 'Morgan Stanley', q: relevance >= 0.8 on news); tickerbot_list_event_kinds lists them. join: state adds the ticker's signals as of each event. Every result has a stable id: use it to drop duplicates. kind: signal takes custom signals too.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "tickerbot_query_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSQL WHERE over `id`, `ticker`, `ts`, `kind` and `payload` (plus the ticker's signals with `join=state`). With one `kind`, its payload fields are typed columns by bare name: `amount > 1`, `firm ILIKE 'Morgan Stanley'`, `relevance >= 0.8` on news (List event kinds lists them); with several kinds, use `payload->>'…'`. Max 4000 chars. ANDs with the other filters.
toNoWindow end, in the same strict ISO subset. A bare `YYYY-MM-DD` means through the end of that day; a timestamp is exclusive (events strictly before it). For news, analyst ratings and estimate revisions the day is the ET calendar day; dated kinds use their own dates. For `signal`, the ticker's home-market day: ET for stocks and ETFs, UTC for crypto, FX and rates.
dirNoA list: `desc` (default) is newest first, `asc` oldest first, paging forward. With `group_by`: the rollup's sort direction. Values: asc: Ascending: smallest or earliest first. desc: Descending: largest or most recent first.desc
fromNoEvents at or after this instant, in strict ISO: `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM[:SS]Z`. A bare `YYYY-MM-DD` means from the start of that day. For news, analyst ratings and estimate revisions the day is the ET calendar day (a story at 21:00 ET on Nov 2 is Nov 2); dated kinds use their own dates. For `signal`, the ticker's home-market day: ET for stocks and ETFs, UTC for crypto, FX and rates.
joinNoSet to `state` to use the ticker's signals in `q`, `select`, `group_by` and `having`, read as of each event's timestamp at the grain `grain` picks. On the daily grain an event on day D reads D-1's row, never D's close. A signal and a payload field with the same name (`price` on insider and signal events, `cik` on filing) resolve to the signal; spell the field `payload->>'price'`. Needs `q`, `group_by` or a ticker signal in `select`. Values: state: Add the ticker’s signals, read as of each event’s timestamp at the grain `grain` picks (default `auto`, which blends hourly and daily per event).
kindNoComma list of kinds. Leave it out for earnings, dividend, split, filing, insider and analyst. News, signal and estimate_revision come back only when named. List event kinds lists each kind, its fields and its filters. Values: earnings: Quarterly earnings reports: reported vs estimated EPS and the surprise, timestamped at the report date. Default. No filters of its own. Payload. dividend: Cash-dividend declarations, timestamped at the ex-dividend date. Default. No filters of its own. Payload. split: Stock splits and reverse splits, timestamped at the execution date. Default. No filters of its own. Payload. filing: SEC annual and quarterly reports (10-K, 20-F, 40-F, 10-Q), timestamped at the filing date. Default. No filters of its own. Payload. insider: Officer and director trades, one event per reported Form 4 transaction. Default. No filters of its own. Payload. analyst: Upgrades, downgrades, initiations and price-target changes; lands within the hour, 24/7. Default. Filter it with `q` (`firm ILIKE 'Morgan Stanley'`). Payload. estimate_revision: Moves in consensus EPS estimates. Opt-in: included only when named. No filters of its own. Payload. news: Headlines, one event per article × tagged ticker. Opt-in: included only when named. `q=relevance >= 0.8` keeps the articles about the ticker. Payload. signal: A yes/no signal turning on or off, built-in or custom. Opt-in: included only when named. Filters: `signal`, `transition`, `merge_gap_seconds`. Payload.
grainNoOnly with `kind=signal` or `join=state`. With `kind=signal`, the grain the flips are read at: `1m`, `1h` or `1d`, or `auto` (the default), the coarsest grain the signal is stored at. With `join=state`, the grain the ticker's signals are read at: `auto` (default) blends hourly and the last closed daily session per event; see as of a past date. Values: 1m: Minute. With `kind=signal`, the signal turning on and off in the one-minute state. With `join=state`, signals read from the one-minute state at or before each event. 1h: Hour. With `kind=signal`, the signal turning on and off in the hourly state. With `join=state`, signals read from the hourly state at or before each event. 1d: Day. With `kind=signal`, the signal turning on and off in the daily state. With `join=state`, signals read from the last daily session closed before each event. auto: Auto. With `kind=signal`, each signal at its own grain, the coarsest it is stored at (`above_sma_200` at `1d`). With `join=state`, each signal from its freshest grain at or before the event, hourly or the last closed daily session; `group_by` reads use the daily session.auto
limitNoPage size for a list (default 50): up to 1000 until 2027-01-12, then 100, and the rest pages with `next_cursor`. A `group_by` rollup returns every group up to `limit` (default and max 1000) and sets `truncated: true` when there are more. A larger value is clamped to the max, not an error; see Deprecations.
orderNoWith `group_by`: the rollup sort, a bare column or output name (put expressions in `select` and sort by their alias); a group key's name works too: `group_by=payload->>'firm' AS firm&order=firm`. Default: `events`, or with your own `select`, its last column's alias. A list is sorted by `ts`: `order=ts` is accepted there and changes nothing.
cursorNoOpaque cursor from the previous response. It carries the filters, `dir` and `select`, so pass it alone. A `q`, `ticker` list or `select` too long to ride in it is kept as a fingerprint instead: send that param again with `cursor`, the same as on the first page (`q_truncated` flags `q`). A missing or different value is a 400 naming the param. Not valid with `group_by`.
havingNoOnly with `group_by`. Post-aggregation filter.
selectNoWithout `group_by`: what each result carries. `id`, `ticker`, `ts` and `kind` always, then the names you list, each at the top level of the result: `payload`, a payload field of the one kind named (`firm`, or `payload->>'firm'`) and with `join=state` a ticker signal. `*` is every field: the whole `payload`, and with `join=state` every signal the read's grain stores. With `group_by`: the rollup's output columns (default: the group keys + `COUNT(*) AS events`), named with `AS` or for you as on `group_by`.
signalNoOnly with `kind=signal`. One signal or a comma list of up to 5: built-in yes/no signals or your custom signals. Required with `q` or `join=state`. An unknown name filters nothing in and is listed in `not_found` (every name unknown: no signal events). See Signal firings.
tickerNoOne ticker or a comma list (up to 50). Not combinable with `universe`. A crypto, FX or rate symbol (`X:BTCUSD`) takes `kind=signal`; every other kind is equities-only and returns `400` naming the symbol's asset class.
group_byNoComma list of rollup keys; it switches the response to rollups. Columns (`kind`, `ticker`), payload fields (`firm`, or the explicit `payload->>'firm'`) and expressions over them all roll up. Name a key with `AS` to choose its JSON key: `payload->>'firm' AS firm`. Un-named keys are named for you: a payload read takes its key (`payload->>'firm'` → `firm`), a function keeps the function's name (`lower(ticker)` → `lower`), and anything else falls back to `group_1`, `group_2`.
universeNoScope to a built-in universe (`top_10`, `top_100`) or one of your own, by id. An unknown one answers 200 with no results and its id in `not_found`. Not combinable with `ticker`.
transitionNoOnly with `kind=signal`. `enter` (false→true) or `exit` (true→false). Values: enter: Enter. The signal turned on: false to true. exit: Exit. The signal turned off: true to false.
merge_gap_secondsNoOnly with `kind=signal`. Merges an exit and re-entry closer than N seconds into one span. Needs one `signal` and a `ticker` list, and does not combine with `q`, `group_by` or `join=state`.

Output Schema

NameRequiredDescriptionDefault
_metaNoWith `join=state` only. `grain`, the grain the joined state was read at (`auto` or the pin), and `state_blended: true` under `auto`. Shared keys: see the `_meta` reference.
as_ofYesServer time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).
countYesThe rows in `results` on this page: events, or groups on a rollup.
queryYesYour request with each param's effective value, in the documented param order: `kind` (a comma string; `all` when you left it out, meaning the six default kinds), `ticker` (a list), `universe`, `from` and `to` (ISO 8601), the kind's own filters (`signal`, `transition`, `merge_gap_seconds`), `q`, `join`, `grain`, `select`, `group_by`, `having`, `order` (rollups), `dir` and `limit`. `q`, `select`, `group_by` and `having` come back in your spelling, not the SQL they compile to. A param you did not send is `null`.
resultsYesOne result per event (with `select`: `id`, `ticker`, `ts`, `kind` and the named keys), or rollups plus `truncated: true` when an aggregate exceeds `limit`.
not_foundNoWith `ticker`, `universe` or `signal`: what you named that does not exist, in request order: the symbols we do not track, an unknown `universe` id, then unknown `signal` names; an empty array when every one was found. A typo here is listed, not read as "no events".
truncatedNoAggregate mode only (`group_by`): `true` when the rollup stopped at its result cap. Aggregate responses are unpaged, so `next_cursor` is absent there.
_advisoriesNoPresent only when the response carried a warning: `deprecated` (since, sunset_on, successor, warning; on a deprecated tool, successor names the tool to call), `rate_limit` (warning, retry_after_seconds, limit, remaining, reset_epoch_s) or `monthly_quota` (warning, limit, remaining, reset_epoch_s).
next_cursorNoOpaque token for the next page; `null` on the last page. A `kind=signal` page can hold fewer than `limit` results, or none, and still carry a `next_cursor`: the read covers a long window in steps and returns what it has after about 6 s (`q` or `join=state`) or 10 s (filter params only), so keep paging until `next_cursor` is `null`. A page that read nothing retries a shorter stretch; if three pages in a row read nothing that way, the read answers `503` `unavailable` with `Retry-After` instead of another empty page, and the same `cursor` can be retried.
q_truncatedNoOnly when an oversized `q` could not ride the cursor: resend `q` with `cursor` on later pages.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.1

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: scope requirements, default vs opt-in kind sets, `id` stability for deduplication, and what `join: state` does to result shape. It also surfaces quirks that matter behaviorally — `kind: signal` reading at a chosen grain and custom signals being accepted. It stops short of describing pagination/limit behavior (deferred to the schema) and says nothing about auth or cost.

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?

Purpose and the binding constraint are front-loaded before the kind/field/join mechanics, so the most decision-relevant information arrives first. Sentences are dense but each carries distinct information; the inline SQL examples do useful work rather than padding. The heavy backtick/jargon density makes it slower to parse than it needs to be, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter tool with an output schema and 100% schema description coverage, the description supplies exactly the glue the schema cannot: the at-least-one-bound rule, default vs opt-in kinds, and the single-kind bare-field convention. Return values need not be explained because an output schema exists. Remaining gaps (pagination, cursor flow, grain interactions) are all covered by the parameter descriptions.

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%, so the baseline is 3 and the schema already documents every parameter in depth. The description does add cross-parameter meaning the schema cannot express: the binding rule that `q` alone is insufficient, and the convention that with a single `kind` payload fields become bare column names in `q`/`select`/`group_by` (with escaped examples). That is genuine added value, but it is the only real semantic contribution beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/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 — SQL queries over events — and enumerates the covered domains (earnings, dividends, splits, filings, insider, analyst, plus opt-in estimate_revision/news/signal). That is far more than a restatement of the name. It never explicitly contrasts itself with the sibling tickerbot_list_events or tickerbot_query_news, so an agent must infer the split from the 'SQL' framing alone.

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 states a hard precondition ('Requires at least one bound: a ticker scope or a time window; `q` alone is not a bound') and clarifies which kinds are default versus opt-in, which is real when-to-use guidance. It also points to tickerbot_list_event_kinds for payload field names. What is missing is guidance on when to prefer this over sibling list/query tools.

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