Skip to main content
Glama
Tickerbot MCP Server

Tickerbot MCP Server

Official
by tickerbot

tickerbot_get_signal

Retrieve a signal's catalog definition and screen US stocks or crypto tickers that match it live or as of a past date, using conditions to filter matches.

Instructions

Returns what one signal is (its catalog entry, the same object List signals returns for it) and every ticker matching it, live or on any past date with asof: a screen on that one signal. Returns catalog (what the signal is) every time. Booleans list their matches with no condition; every other type lists them only with one, typed like the signal: ">70" (numeric), "<YYYY-MM-DDTHH:MM:SSZ" (timestamp), ">=YYYY-MM-DD" (date), "=ETF" (string); without it you get the catalog entry and a note. Without order, a non-boolean sorts by its value in the direction the condition implies (< ascending, > descending). To know when each ticker started matching, use tickerbot_query_events with kind=signal, signal=, transition=enter.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "signal": "<signal>"
    },
    "name": "tickerbot_get_signal"
  }
}

Input Schema

NameRequiredDescriptionDefault
dirNoSort direction. Omitted: the direction the default order implies, else `desc`. Values: asc: Ascending: smallest or earliest first. desc: Descending: largest or most recent first.
asofNoTarget moment as `YYYY-MM-DD` (that day's close) or an ISO timestamp (that intraday moment; daily-only signals then carry the previous session's close, never that day's): the same read as it stood then, unlimited depth. Full contract under As of a past date.
grainNoOnly with `asof`. Grain the past state is read at: `1m`, `1h`, `1d` or `auto` (default). `auto` blends: each signal comes from its freshest grain at or before the instant (minute, then hourly, then the last closed daily session), so nothing is refused for grain and no ticker is dropped; `_meta.blended` and `_meta.grains_present` say what contributed. Pin a grain for the fastest response: one grain is read instead of three, and every ticker is captured on the same clock. A signal the pinned grain does not store is a `400 interval_unavailable` naming the grains that carry it (`rsi_14`, fundamentals and valuation ratios are `1d`-only). `1m` and `1h` need a timestamp `asof`; with a bare date they are a `400 interval_unavailable`. Values: 1m: Minute. The one-minute state at or before the instant. Covers the most liquid tickers and the signals stored at one minute. Needs a timestamp `asof`; with a bare date it is a `400 interval_unavailable`. 1h: Hour. The hourly state at or before the instant. Covers every ticker and the signals stored hourly. Needs a timestamp `asof`; with a bare date it is a `400 interval_unavailable`. 1d: Day. The last daily session closed before the instant; a bare date reads that day’s close. Covers every ticker and the most signals, including the daily-only ones such as `rsi_14`, fundamentals and valuation ratios. auto: Auto. Each signal from its freshest grain at or before the instant: minute, then hourly, then the last closed daily session. `_meta.blended` and `_meta.grains_present` say what contributed.auto
limitNoPage size. Max 200 until 2027-01-12, then 100 (a larger value is clamped to the max, not an error; `next_cursor` pages the rest; see Deprecations).
orderNoSignal to sort by (or `ticker`). Omitted: a yes/no signal lists tickers A→Z; any other signal sorts by its value in the direction the condition implies (`<`/`<=` ascending, `>`/`>=` descending).
cursorNoThe previous response's `next_cursor`. Send it with the same params as the first page (`limit` may change); a page whose params differ is a 400 naming the param.
selectNoSignals each match carries beside `value`, e.g. `market_cap,sector`. `*` is every signal: the whole live row, or on an as-of read every signal the read's grain stores. An unknown signal is a 400, beside `*` too.
signalYesA signal name. Booleans (e.g. `golden_cross`, `above_sma_50`) are detected automatically; every other type (numeric `rsi_14`, timestamp `price_asof`, date `earnings_date`, string `asset_class`) requires a `condition`. An object or list signal (`leadership`, `etf_holders`) has no `condition` form: the read returns its catalog entry and a `note`; screen on it with `POST /v2/scan`.
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`.
conditionNoLists the matches of a non-boolean signal; without it the response carries the catalog entry and a `note` instead of `results`. The shape follows the signal's `type` in the catalog. Single bound, `<op><value>`. numeric: `>70`, `<=200`, `!=0` (operators `>`, `>=`, `=`, `!=`, `<`, `<=`). timestamp: an ISO instant, `<YYYY-MM-DDTHH:MM:SSZ` or `>=YYYY-MM-DD` (a bare date is midnight UTC). date: `>=YYYY-MM-DD` or `=YYYY-MM-DD`. string: `=ETF` or `!=ETF` (`=` and `!=` only; quotes optional). A relative window ("older than 15 minutes") is a `/v2/scan` query: `price_asof < now() - interval '15 minutes'`. Sending a condition with a boolean or custom signal returns 400 (it does not apply).

Output Schema

NameRequiredDescriptionDefault
noteNoOnly on a non-boolean signal read without `condition`: says how to list its matches, or, for an object or list signal, to screen on it with `POST /v2/scan`. `count`, `next_cursor` and `results` are absent then.
_metaNoThis endpoint's own keys: `null_coverage` (how many in-scope tickers are `null` on the signal and so never match) and, with `asof`, `grain_scope` and `minute_only_signals_fell_back_to_daily`. 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).
countNoThe tickers in `results` on this page.
queryYesYour request echoed, each param with its effective value: `signal`, `condition`, `universe`, `asof`, `grain`, `select`, `order`, `dir`, `limit`.
signalYesThe signal you asked for.
catalogYesThe signal's catalog entry: the same object List signals returns for it (description, type, unit, refresh, grains). `null` only when the catalog could not be read; the matches are served regardless.
resultsNoMatching tickers: `ticker`, `name`, the signal `value` and any `select` signals.
not_foundNoWith `universe` only: the `universe` id you named when it does not exist (the read then has no results); an empty array or absent otherwise.
_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. Pass it back as `cursor`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.1

TDQS

A4.4/5.0
Behavior5/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: it discloses that a missing `condition` yields catalog plus a `note` instead of results, that booleans omit conditions, and that object/list signals have no condition form. It also names failure modes — 400 interval_unavailable for unsupported grains, 400 when a condition is sent with a boolean, 200 with `not_found` for an unknown universe — plus limit clamping and cursor param matching.

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 purpose leads, followed by conditional behaviors and error semantics, with no filler sentences. It is dense but appropriately sized for a ten-parameter tool. The default ordering rule is stated twice (once in the body, once for `order`), a minor redundancy.

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?

An output schema exists, so return values need not be spelled out, and the description still labels the key payload pieces (`catalog`, matches, `note`). For a complex read with as-of and grain modes, nothing an agent needs in order to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents `condition` shapes, `grain`, `asof`, `limit` clamping and `cursor`. The description restates much of this (the condition syntax examples, the default ordering rule) rather than adding new meaning. The only genuine additions, such as how `order` interacts with the implied condition direction, are already mirrored in the schema.

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?

States a specific verb and resource: returns one signal's catalog entry plus every ticker matching it, live or as-of a past date, framed as 'a screen on that one signal'. That framing distinguishes it from the catalog-listing and multi-signal scan siblings without needing their schemas.

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?

Gives concrete routing: use tickerbot_query_events with kind=signal and transition=enter to learn when tickers started matching, and POST /v2/scan for object/list signals and relative windows. It also explains when to omit `condition` (booleans) versus when it is required. It stops short of an explicit contrast with the tickerbot_scan tool, referencing the endpoint instead.

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