Skip to main content
Glama
Tickerbot MCP Server

Tickerbot MCP Server

Official
by tickerbot

tickerbot_list_events

Lists stock-market events with SQL-style filters, date windows, tickers, and rollups. Deprecated: use tickerbot_query_events instead.

Instructions

Deprecated: works until 2027-01-12. Same as tickerbot_query_events; call that instead.

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_list_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. Changed32 schema fields changedv0.4.1
    • removedInput schema / properties / action
      Removed value: -{
      -  "description": "kind=analyst only. Exact rating-action filter.",
      -  "enum": [
      -    "upgrades",
      -    "downgrades",
      -    "initiates_coverage_on",
      -    "maintains",
      -    "reiterates",
      -    "assumes",
      -    "reinstates",
      -    "suspends",
      -    "terminates_coverage_on"
      -  ],
      -  "type": "string"
      -}
    • changedInput schema / properties / cursor / description
      Previous value: -"Opaque cursor from a prior response — carries the original filters, pass it alone (long q values must be resent alongside it)."New value: +"Opaque 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`."
    • addedInput schema / properties / dir / default
      Added value: +"desc"
    • changedInput schema / properties / dir / description
      Previous value: -"Aggregate-mode sort direction."New value: +"A 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."
    • removedInput schema / properties / dir / enum
      Removed value: -[
      -  "asc",
      -  "desc"
      -]
    • addedInput schema / properties / dir / pattern
      Added value: +"^\\s*([aA][sS][cC]|[dD][eE][sS][cC])\\s*$"
    • removedInput schema / properties / firm
      Removed value: -{
      -  "description": "kind=analyst only. Case-insensitive analyst-firm filter (e.g. \"Goldman Sachs\" matches \"goldman sachs\") — prefer this over a q payload match, which is case-sensitive.",
      -  "type": "string"
      -}
    • changedInput schema / properties / from / description
      Previous value: -"Events at or after this ISO date/datetime (inclusive; a bare YYYY-MM-DD means from the start of that day). `since` accepted as alias."New value: +"Events 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."
    • addedInput schema / properties / grain
      Added value: +{
      +  "default": "auto",
      +  "description": "Only 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.",
      +  "pattern": "^\\s*(1[mM]|1[hH]|1[dD]|[aA][uU][tT][oO])\\s*$",
      +  "type": "string"
      +}
    • changedInput schema / properties / group_by / description
      Previous value: -"Comma list of rollup keys — switches to aggregate rows, e.g. payload->>'firm' AS firm, or kind. `AS` names the JSON key; an un-named payload read is keyed by its payload key (payload->>'firm' -> firm)."New value: +"Comma 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`."
    • changedInput schema / properties / having / description
      Previous value: -"Post-aggregation filter (requires group_by), e.g. COUNT(*) > 5."New value: +"Only with `group_by`. Post-aggregation filter."
    • removedInput schema / properties / interval
      Removed value: -{
      -  "description": "Grain for join=state replay (finest covering tier by default).",
      -  "enum": [
      -    "1m",
      -    "1h",
      -    "1d"
      -  ],
      -  "type": "string"
      -}
    • changedInput schema / properties / join / description
      Previous value: -"join=state attaches each event's ticker STATE as of that event's moment (the replay join) under a `state` key — \"downgrades where rsi_14 was already under 40\" composes with q. Free on every plan."New value: +"Set 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)."
    • removedInput schema / properties / join / enum
      Removed value: -[
      -  "state"
      -]
    • addedInput schema / properties / join / pattern
      Added value: +"^\\s*([sS][tT][aA][tT][eE])\\s*$"
    • changedInput schema / properties / kind / description
      Previous value: -"Comma list of kinds to include. Default is the four corporate kinds: dividend, split, insider, analyst. Two more are opt-in and join only when named: `signal` (boolean-flag firings) and `news`."New value: +"Comma 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."
    • addedInput schema / properties / kind / pattern
      Added value: +"^\\s*([dD][iI][vV][iI][dD][eE][nN][dD]|[sS][pP][lL][iI][tT]|[iI][nN][sS][iI][dD][eE][rR]|[aA][nN][aA][lL][yY][sS][tT]|[eE][aA][rR][nN][iI][nN][gG][sS]|[fF][iI][lL][iI][nN][gG]|[sS][iI][gG][nN][aA][lL]|[nN][eE][wW][sS]|[eE][sS][tT][iI][mM][aA][tT][eE]_[rR][eE][vV][iI][sS][iI][oO][nN])(\\s*,\\s*([dD][iI][vV][iI][dD][eE][nN][dD]|[sS][pP][lL][iI][tT]|[iI][nN][sS][iI][dD][eE][rR]|[aA][nN][aA][lL][yY][sS][tT]|[eE][aA][rR][nN][iI][nN][gG][sS]|[fF][iI][lL][iI][nN][gG]|[sS][iI][gG][nN][aA][lL]|[nN][eE][wW][sS]|[eE][sS][tT][iI][mM][aA][tT][eE]_[rR][eE][vV][iI][sS][iI][oO][nN]))*\\s*$"
    • addedInput schema / properties / limit / default
      Added value: +50
    • changedInput schema / properties / limit / description
      Previous value: -"Page size. Max 1000."New value: +"Page 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."
    • addedInput schema / properties / merge_gap_seconds
      Added value: +{
      +  "description": "Only 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`.",
      +  "type": "integer"
      +}
    • changedInput schema / properties / order / description
      Previous value: -"Aggregate-mode sort column/alias. Default: events."New value: +"With `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."
    • changedInput schema / properties / q / description
      Previous value: -"SQL WHERE over (ticker, ts, kind, payload jsonb) — ONLY those four identifiers. Payload fields via jsonb operators: payload->>'firm' = 'Goldman Sachs', (payload->>'shares')::numeric > 1e6. On kind=signal this requires `signal` (the firing log is ~175M rows); kind=signal takes no group_by."New value: +"SQL 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."
    • changedInput schema / properties / select / description
      Previous value: -"Aggregate-mode output columns (requires group_by). Default: group keys + COUNT(*) AS events."New value: +"Without `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`."
    • changedInput schema / properties / signal / description
      Previous value: -"kind=signal only. One built-in boolean flag (e.g. golden_cross). REQUIRED to use `q` or `join` on kind=signal — naming the signal is what keeps the query on an index; optional otherwise."New value: +"Only 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."
    • changedInput schema / properties / ticker / description
      Previous value: -"Single-ticker filter, e.g. AAPL."New value: +"One 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."
    • removedInput schema / properties / tickers
      Removed value: -{
      -  "description": "Comma-separated tickers, max 50. Mutually exclusive with `universe`.",
      -  "type": "string"
      -}
    • changedInput schema / properties / to / description
      Previous value: -"Window end: a bare YYYY-MM-DD means through the END of that day (matching bars/series/spans); a timestamp is exclusive — events strictly before it. `until` accepted as alias."New value: +"Window 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."
    • changedInput schema / properties / transition / description
      Previous value: -"kind=signal only. `enter` (false->true) or `exit` (true->false). Always optional — an ordinary filter."New value: +"Only 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."
    • removedInput schema / properties / transition / enum
      Removed value: -[
      -  "enter",
      -  "exit"
      -]
    • addedInput schema / properties / transition / pattern
      Added value: +"^\\s*([eE][nN][tT][eE][rR]|[eE][xX][iI][tT])\\s*$"
    • changedInput schema / properties / universe / description
      Previous value: -"Universe slug (top_10, top_100, or a saved one) to scope the stream. Mutually exclusive with `tickers`."New value: +"Scope 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`."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "_advisories": {
      +      "description": "Present 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).",
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "_meta": {
      +      "description": "With `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_of": {
      +      "description": "Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "count": {
      +      "description": "The rows in `results` on this page: events, or groups on a rollup.",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "next_cursor": {
      +      "description": "Opaque 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.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "not_found": {
      +      "description": "With `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\".",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    },
      +    "q_truncated": {
      +      "description": "Only when an oversized `q` could not ride the cursor: resend `q` with `cursor` on later pages."
      +    },
      +    "query": {
      +      "description": "Your 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`.",
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "results": {
      +      "description": "One result per event (with `select`: `id`, `ticker`, `ts`, `kind` and the named keys), or rollups plus `truncated: true` when an aggregate exceeds `limit`.",
      +      "items": {
      +        "properties": {
      +          "id": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "kind": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "payload": {
      +            "anyOf": [
      +              {
      +                "properties": {
      +                  "available_at": {},
      +                  "available_at_source": {
      +                    "description": "One of: `report_time`, `assumed`."
      +                  },
      +                  "estimated_eps": {},
      +                  "fiscal_period_end": {},
      +                  "report_time": {
      +                    "description": "One of: `pre-market`, `post-market`."
      +                  },
      +                  "reported_eps": {},
      +                  "surprise": {},
      +                  "surprise_pct": {}
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "amount": {},
      +                  "declared_date": {},
      +                  "dividend_type": {
      +                    "description": "One of: `CD`, `SC`."
      +                  },
      +                  "ex_date": {},
      +                  "frequency": {},
      +                  "pay_date": {},
      +                  "record_date": {}
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "ratio": {},
      +                  "split_from": {},
      +                  "split_to": {}
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "accession": {},
      +                  "available_at": {},
      +                  "cik": {},
      +                  "fiscal_period": {
      +                    "description": "One of: `FY`, `Q1`, `Q2`, `Q3`, `Q4`, `H1`, `CY`."
      +                  },
      +                  "fiscal_year": {},
      +                  "form": {
      +                    "description": "One of: `10-K`, `20-F`, `40-F`, `10-Q`."
      +                  },
      +                  "period_end": {},
      +                  "period_start": {},
      +                  "url": {}
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "action": {
      +                    "description": "One of: `P`, `S`, `V`, `A`, `D`, `F`, `I`, `M`, `C`, `E`, `H`, `O`, `X`, `G`, `L`, `W`, `Z`, `J`, `K`, `U`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "executive": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "price": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "security_type": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "shares": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "title": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "value": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  }
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "action": {
      +                    "description": "One of: `upgrades`, `downgrades`, `maintains`, `reiterates`, `initiates_coverage_on`, `assumes`, `reinstates`, `suspends`, `terminates_coverage_on`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "analyst": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "currency": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "event_id": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "firm": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "importance": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "previous_price_target": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "previous_rating": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "price_target": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "price_target_action": {
      +                    "description": "One of: `raises`, `lowers`, `maintains`, `announces`, `adjusts`, `removes`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "rating": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "analyst_count": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "change_pct": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "direction": {
      +                    "description": "One of: `up`, `down`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "fiscal_date": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "horizon": {
      +                    "description": "One of: `fiscal quarter`, `fiscal year`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "new_estimate": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "old_estimate": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  }
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "relevance": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "sentiment": {
      +                    "description": "One of: `Bearish`, `Somewhat-Bearish`, `Neutral`, `Somewhat-Bullish`, `Bullish`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "sentiment_score": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "source": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "title": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "url": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                }
      +              },
      +              {
      +                "properties": {
      +                  "definition_version": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "grain": {
      +                    "description": "One of: `1m`, `1h`, `1d`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "price": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "signal": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "transition": {
      +                    "description": "One of: `enter`, `exit`.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                }
      +              }
      +            ],
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "ticker": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "ts": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          }
      +        }
      +      },
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    },
      +    "truncated": {
      +      "description": "Aggregate mode only (`group_by`): `true` when the rollup stopped at its result cap. Aggregate responses are unpaged, so `next_cursor` is absent there."
      +    }
      +  },
      +  "required": [
      +    "as_of",
      +    "query",
      +    "count",
      +    "results"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.2.0

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does supply one genuinely behavioral fact: a sunset date implying the tool fails after 2027-01-12. However it says nothing about what the tool returns, its failure modes post-sunset, or any constraints, deferring all of that to the sibling.

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?

One short sentence-pair with the deprecation notice front-loaded and the redirect immediately after. Every clause earns its place and nothing is padded.

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

Completeness3/5

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

For a deprecated alias of a highly complex 18-parameter tool, the redirect is sufficient to prevent misuse, but it leaves the agent entirely dependent on the sibling's definition for actual capability. It does not state the post-sunset behavior (error vs. empty result), which is the one gap an agent could still trip on.

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% across 18 well-documented parameters, so the baseline of 3 applies. The description adds no parameter meaning at all, but none is needed given the schema's detail.

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

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description never states what the tool actually does with its own verb+resource; the only functional information is the equivalence claim 'Same as tickerbot_query_events.' That equivalence does convey the purpose indirectly, but an agent reading this alone gets no description of the resource or the operation.

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 gives an explicit alternative ('call that instead') and a hard condition (works until 2027-01-12), so an agent knows exactly when this tool is acceptable and what to prefer. There are no exclusions left to infer.

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