Skip to main content
Glama
Tickerbot MCP Server

Tickerbot MCP Server

Official
by tickerbot

tickerbot_scan

Screen every ticker with a SQL WHERE clause and return matches; run now or backtest past dates, with optional grouping into rollups.

Instructions

Screens every ticker with a SQL WHERE clause and returns the matches. Run it now, or add asof to backtest it on any past date. The q grammar is a flat SQL WHERE over signal names: AND/OR/NOT, comparisons, numeric and string literals, custom signals by name. No JOIN or subqueries. With group_by the result is rollup rows, not tickers. Example: gap_up AND market_cap < 2000000000 AND NOT earnings_this_week.

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": {
      "q": "<q>"
    },
    "name": "tickerbot_scan"
  }
}

Input Schema

NameRequiredDescriptionDefault
qYesSQL WHERE expression. Max 4000 chars; semicolons, comments and write keywords are rejected. Your custom signals are valid here: each expands to its SQL at run time. To scan named tickers: `ticker IN ('AAPL', 'MSFT')`; to scan one asset class: `asset_class = 'crypto'`.
dirNoSort direction. Values: asc: Ascending: smallest or earliest first. desc: Descending: largest or most recent first.desc
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. In `q`, `now()` and `current_date` mean that moment, so `last_earnings_date >= now() - interval '7 days'` backtests as written. 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 100. Grouped scans do not paginate: `truncated: true` when groups were cut, so sort with `order` to keep the ones you want.
orderNoSignal to sort by; it joins the default row. On a grouped scan the default is the count alias `tickers` (or, with a custom `select`, the last item's alias, so alias it with `AS`), sorted NULLS LAST with the group keys as tiebreak.change_1d_pct
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. Row scans only.
havingNoOnly with `group_by`. Filter the rollups. Custom signals are valid here too.
selectNoWhat each result carries, as in SQL. Omitted: the default row (ticker, name, asset_class, asset_type, price, change_1d_pct, gap_pct, relative_volume, market_cap) plus every signal used in `q` and `order`; a custom signal appears as its own value, and a cross-ticker reference (`SPY.sma_50`) is not added. A list: exactly those items, `ticker` always included; expressions with `AS` work (`price / sma_50 AS dist`) and are validated like `q`. `*`: every signal in the catalog. All aggregates (`count(*), avg(rsi_14)`) without `group_by`: one summary row, in `results`. With `group_by`, each item is an aggregate or a group key. Aggregates: count/avg/sum/min/max/stddev/string_agg/bool_and/bool_or, plus `FILTER (WHERE …)`.
group_byNoGroups the scan: 1–6 group keys (signals, expressions or one of your custom signals as a boolean key). Results become rollups in `results`, each carrying its keys. Name a key with `AS` to choose its JSON key (`market_cap > 1e11 AS mega`); an un-named expression is named for you. Default `select`: the keys + `COUNT(*) AS tickers`. Works with `asof`; does not paginate.
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`. Omitted, the screen runs across every ticker.

Output Schema

NameRequiredDescriptionDefault
_metaNoPresent when there is something to disclose. Row scans add `null_coverage`: per signal in the predicate (under `signals`), how many in-scope tickers are `null` and therefore never evaluated; absence from `results` means "no value", not "did not match". With `asof`: `grain_scope` (the snapshot spans every ticker in scope at one grain), `signals_not_stored_at_grain` (default-row signals this grain does not store, returned as `null`), `minute_only_signals_fell_back_to_daily`, `empty_diagnostic` (on an empty result, each signal's coverage at that instant) and a `note` naming the signals that have no history and show today's value. 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).
countYesRows in this page (matches on a row scan, groups on a grouped scan). It is not a total: for one, scan with `select=count(*)`.
queryYesYour query, echoed in param order (`q`, `universe`, `asof`, `grain`, `select`, `group_by`, `having`, `order`, `dir`, `limit`, `cursor`), each with its effective value: `select` lists the signals each result carries.
resultsYesRow scans: one result per match, carrying what `select` asked for (see `select`). Grouped scans (`group_by`, or a `select` of aggregates alone): one row per group, carrying the group keys, then the `select` items under their aliases (default: `tickers`, the count). A `select` of aggregates alone without `group_by` returns one row.
not_foundNoWith `universe` only: the `universe` id you named when it does not exist (the scan then has no results). Absent otherwise.
truncatedNoOn grouped scans (`group_by`, or a `select` of aggregates alone), on every response: `true` when the rollup stopped at its result cap, `false` when the list is whole. Grouped 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. Pass it back as `cursor`. Row scans only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changedv0.4.1
    • changedInput schema / properties / asof / description
      Previous value: -"Optional YYYY-MM-DD or ISO timestamp for a historical scan. Unlimited depth on every plan."New value: +"Target 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. In `q`, `now()` and `current_date` mean that moment, so `last_earnings_date >= now() - interval '7 days'` backtests as written. Full contract under As of a past date."
    • changedInput schema / properties / cursor / description
      Previous value: -"Opaque cursor (row mode only)."New value: +"The 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. Row scans only."
    • addedInput schema / properties / dir / default
      Added value: +"desc"
    • changedInput schema / properties / dir / description
      Previous value: -"Sort direction."New value: +"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 / fields
      Removed value: -{
      -  "description": "Comma-separated extra columns to include (row mode only).",
      -  "type": "string"
      -}
    • removedInput schema / properties / full
      Removed value: -{
      -  "description": "Row mode: return the FULL wide row for each match (every column) instead of the slim default projection.",
      -  "type": "boolean"
      -}
    • addedInput schema / properties / grain
      Added value: +{
      +  "default": "auto",
      +  "description": "Only 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.",
      +  "pattern": "^\\s*(1[mM]|1[hH]|1[dD]|[aA][uU][tT][oO])\\s*$",
      +  "type": "string"
      +}
    • addedInput schema / properties / group_by / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  }
      +]
    • changedInput schema / properties / group_by / description
      Previous value: -"AGGREGATE MODE: 1–6 comma-separated group keys (columns or expressions, e.g. `sector`). Results become rollup rows instead of tickers. Alias a key with `AS` to name its JSON key; un-named expressions are named for you."New value: +"Groups the scan: 1–6 group keys (signals, expressions or one of your custom signals as a boolean key). Results become rollups in `results`, each carrying its keys. Name a key with `AS` to choose its JSON key (`market_cap > 1e11 AS mega`); an un-named expression is named for you. Default `select`: the keys + `COUNT(*) AS tickers`. Works with `asof`; does not paginate."
    • removedInput schema / properties / group_by / type
      Removed value: -"string"
    • changedInput schema / properties / having / description
      Previous value: -"Aggregate filter (requires group_by). Example: `COUNT(*) >= 10`."New value: +"Only with `group_by`. Filter the rollups. Custom signals are valid here too."
    • addedInput schema / properties / limit / default
      Added value: +50
    • changedInput schema / properties / limit / description
      Previous value: -"Page size. Max 100. Default 50. Aggregate mode does not paginate — response sets `truncated: true` when groups were cut."New value: +"Page size. Max 100. Grouped scans do not paginate: `truncated: true` when groups were cut, so sort with `order` to keep the ones you want."
    • addedInput schema / properties / order / default
      Added value: +"change_1d_pct"
    • changedInput schema / properties / order / description
      Previous value: -"Sort column. Default day_change_pct (rows) / tickers (aggregate)."New value: +"Signal to sort by; it joins the default row. On a grouped scan the default is the count alias `tickers` (or, with a custom `select`, the last item's alias, so alias it with `AS`), sorted NULLS LAST with the group keys as tiebreak."
    • changedInput schema / properties / q / description
      Previous value: -"SQL WHERE expression. Max 4000 chars."New value: +"SQL WHERE expression. Max 4000 chars; semicolons, comments and write keywords are rejected. Your custom signals are valid here: each expands to its SQL at run time. To scan named tickers: `ticker IN ('AAPL', 'MSFT')`; to scan one asset class: `asset_class = 'crypto'`."
    • addedInput schema / properties / select / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  }
      +]
    • changedInput schema / properties / select / description
      Previous value: -"Aggregate output items (requires group_by). Default: group keys + COUNT(*) AS tickers. Aggregates: count/avg/sum/min/max/stddev/string_agg + FILTER (WHERE …). Alias items with AS. Example: `sector, COUNT(*) AS n, AVG(rsi_14) AS avg_rsi`."New value: +"What each result carries, as in SQL. Omitted: the default row (ticker, name, asset_class, asset_type, price, change_1d_pct, gap_pct, relative_volume, market_cap) plus every signal used in `q` and `order`; a custom signal appears as its own value, and a cross-ticker reference (`SPY.sma_50`) is not added. A list: exactly those items, `ticker` always included; expressions with `AS` work (`price / sma_50 AS dist`) and are validated like `q`. `*`: every signal in the catalog. All aggregates (`count(*), avg(rsi_14)`) without `group_by`: one summary row, in `results`. With `group_by`, each item is an aggregate or a group key. Aggregates: count/avg/sum/min/max/stddev/string_agg/bool_and/bool_or, plus `FILTER (WHERE …)`."
    • removedInput schema / properties / select / type
      Removed value: -"string"
    • changedInput schema / properties / universe / description
      Previous value: -"Optional universe slug."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`. Omitted, the screen runs across every 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": "Present when there is something to disclose. Row scans add `null_coverage`: per signal in the predicate (under `signals`), how many in-scope tickers are `null` and therefore never evaluated; absence from `results` means \"no value\", not \"did not match\". With `asof`: `grain_scope` (the snapshot spans every ticker in scope at one grain), `signals_not_stored_at_grain` (default-row signals this grain does not store, returned as `null`), `minute_only_signals_fell_back_to_daily`, `empty_diagnostic` (on an empty result, each signal's coverage at that instant) and a `note` naming the signals that have no history and show today's value. Shared keys: see the `_meta` reference.",
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "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": "Rows in this page (matches on a row scan, groups on a grouped scan). It is not a total: for one, scan with `select=count(*)`.",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "next_cursor": {
      +      "description": "Opaque token for the next page; `null` on the last page. Pass it back as `cursor`. Row scans only.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "not_found": {
      +      "description": "With `universe` only: the `universe` id you named when it does not exist (the scan then has no results). Absent otherwise."
      +    },
      +    "query": {
      +      "description": "Your query, echoed in param order (`q`, `universe`, `asof`, `grain`, `select`, `group_by`, `having`, `order`, `dir`, `limit`, `cursor`), each with its effective value: `select` lists the signals each result carries.",
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "results": {
      +      "description": "Row scans: one result per match, carrying what `select` asked for (see `select`). Grouped scans (`group_by`, or a `select` of aggregates alone): one row per group, carrying the group keys, then the `select` items under their aliases (default: `tickers`, the count). A `select` of aggregates alone without `group_by` returns one row.",
      +      "items": {
      +        "properties": {
      +          "current_ticker": {},
      +          "date": {},
      +          "held_at_asof": {},
      +          "predecessors": {
      +            "items": {
      +              "properties": {
      +                "cik": {},
      +                "composite_figi": {},
      +                "name": {},
      +                "tenure_end": {},
      +                "tenure_start": {}
      +              }
      +            },
      +            "type": [
      +              "array",
      +              "null"
      +            ]
      +          },
      +          "prior_symbols": {
      +            "items": {
      +              "properties": {
      +                "tenure_end": {},
      +                "tenure_start": {},
      +                "ticker": {}
      +              }
      +            },
      +            "type": [
      +              "array",
      +              "null"
      +            ]
      +          },
      +          "symbol_reused": {
      +            "type": [
      +              "boolean",
      +              "null"
      +            ]
      +          },
      +          "tenure_end": {},
      +          "tenure_start": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "ticker": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    },
      +    "truncated": {
      +      "description": "On grouped scans (`group_by`, or a `select` of aggregates alone), on every response: `true` when the rollup stopped at its result cap, `false` when the list is whole. Grouped responses are unpaged, so `next_cursor` is absent there."
      +    }
      +  },
      +  "required": [
      +    "as_of",
      +    "query",
      +    "count",
      +    "results"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.2.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the burden and adds useful behavior: it is a screen/query, supports AND/OR/NOT comparisons on signal names, forbids JOIN/subqueries, and `group_by` returns rollup rows. It does not explicitly state read-only/no-side-effects, auth, or rate limits, but the core behavioral profile is clear.

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?

Front-loaded with purpose, then usage timing, query grammar constraints, grouping caveat, and a concrete example. Every sentence contributes useful orientation without excessive length.

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 a complex screening tool, the description covers the core action, backtesting trigger, query language limits, and grouped-result shape. Remaining details such as pagination, cursor behavior, select/having/order, and universe scoping are left to the rich schema and output schema, which is acceptable.

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 schema already documents all 11 parameters in depth. The description adds a concise `q` grammar summary and the `group_by` result-shape caveat, but most parameter meaning remains in the schema rather than the description.

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?

States a specific verb and resource: screens every ticker with a SQL WHERE clause and returns the matches. It clearly identifies the core action, though it does not explicitly name a sibling or contrast itself with list_tickers/get_ticker.

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

Usage Guidelines3/5

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

Gives one temporal usage cue ('Run it now, or add `asof` to backtest') and notes that `group_by` changes result shape. It does not say when to use this versus sibling ticker/query tools or when it is inappropriate.

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