Skip to main content
Glama
Tickerbot MCP Server

Tickerbot MCP Server

Official
by tickerbot

tickerbot_subscribe_events

Subscribe to selected market event kinds and receive alerts via webhook, Discord, in-app feed, or mobile push when event-field and ticker-signal filters match.

Instructions

Gets you an alert by webhook when new events of the kinds you choose land, filtered on the event and on the ticker's signals. Webhooks need a paid plan (Free has no webhook slots). One q covers the event's fields (with one kind, bare: firm = 'Goldman Sachs') and the ticker's signals at fire time (market_cap > 1e10); on a name clash (price, cik) the ticker signal wins; the event's own value is payload->>'price'. Latency is the ingest cadence (analyst ≤1h, corporate kinds daily), not sub-minute.

Input Schema

NameRequiredDescriptionDefault
qNoThe filter, as on Query events with `join=state`: the event's own fields (`id`, `ticker`, `ts`, `kind`, `payload`, and with one kind its payload fields by bare name) and the ticker's signals at fire time, in one WHERE clause. A payload field and a signal with the same name resolve to the signal, as on Query events: `price` on insider, `cik` on filing. Spell the event's own value `payload->>'price'`. Custom signals are expanded and frozen at creation.
kindNoEvent kinds to fire on, an array or a comma list. `filing` fires when a 10-K, 20-F, 40-F or 10-Q lands (the next morning's EDGAR index read); `estimate_revision` when the nightly consensus refresh moves an EPS estimate, one event per fiscal period and horizon that moved (about 1,000 a night across the market). Values: earnings: Fires on each quarterly earnings report: reported vs estimated EPS and the surprise. dividend: Fires on each cash-dividend declaration. split: Fires on each stock split or reverse split. filing: Fires when a 10-K, 20-F, 40-F or 10-Q lands, from the next morning’s EDGAR index read. insider: Fires on each reported Form 4 transaction by an officer or director. analyst: Fires on each upgrade, downgrade, initiation or price-target change. estimate_revision: Fires when the nightly consensus refresh moves an EPS estimate, one event per fiscal period and horizon that moved (about 1,000 a night across the market).
nameNoDisplay name, up to 80 characters. Defaults to `events: <kinds> · <scope>`.
selectNoWhat each delivered event carries: `id`, `ticker`, `ts` and `kind` always, then the names you list, at the top level: `payload`, the payload fields of the one kind named, and ticker signals at fire time. Omitted: each event as on Query events (`payload` whole).
tickerNoOne ticker or a comma list (up to 50). Not combinable with `universe`. Omit both for every ticker.
channelNoDelivery channel: `webhook` (POST to `target_url`), `discord` (an embed at `discord_url`), `in_app` (the dashboard only) or `mobile_push` (to `device_id`). Inferred when omitted: `discord` if `discord_url` is set, else `mobile_push` if `device_id` is set, else `webhook` if `target_url` is set, else `in_app`. See Delivery channels. Values: webhook: POST the payload to an HTTPS endpoint you own, signed with `X-Tickerbot-Signature`. discord: Post to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed: the URL is itself the credential. in_app: Deliver to the in-app feed. No external receiver, so nothing to validate and no `test_url`. mobile_push: Push to a registered device. Requires a `device_id` from Register a device.
universeNoScope to a built-in universe (`top_10`, `top_100`) or one of your own, by id. An unknown one is a 400 `universe_not_found` naming it.
device_idNoOnly with `channel=mobile_push`. Device to notify, from `POST /v2/devices/register`. An unknown id is a 400 `device_not_found`.
target_urlNoOnly with `channel=webhook`. HTTPS URL each delivery is POSTed to.
discord_urlNoOnly with `channel=discord`. Discord incoming-webhook URL (`https://discord.com/api/webhooks/…`). Stored as a posting credential: the create response echoes it back under `channel_config`, but every later read (list, get, deliveries) strips it and sets `channel_config_present: true` instead.

Output Schema

NameRequiredDescriptionDefault
qYesThe stored predicate. Custom signals appear expanded: the SQL is frozen at creation. On an event webhook, the whole filter (the event's fields and the ticker's signals); `null` when it fires on every event. On a news webhook, the Query news `q`, or `null`.
idYesThe webhook id (`wh_…`), the handle for every other call on this record.
dirYesSort direction for those lists: `desc` unless you chose one. `null` on event and news webhooks. One of: `asc`, `desc`.
kindNoEvent webhooks only: the kinds subscribed. One of: `earnings`, `filing`, `dividend`, `split`, `insider`, `analyst`, `estimate_revision`.
nameYesYour label for the subscription.
_metaNoReturned on create only, and only when the rule or `select` named a signal under its pre-2026-09-07 spelling: `deprecated_signals` lists each one (`requested`, `use`, `note`). The stored rule carries the current name.
as_ofYesServer time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).
orderYesSort signal for each delivery's match lists: `market_cap` unless you chose one, so a broad alert lists the same top 100 names each time. `null` on event and news webhooks.
searchNoNews webhooks only: the full-text search it fires on, or `null`.
selectYesThe signals each delivered match carries, after `ticker`; `null` means the scan default row plus the signals the rule uses in `q` and `order`. On a news webhook, the article fields each delivered article carries.
statusYesWhether it is live. `disabled_reason` says why a webhook is disabled. One of: `active`, `disabled`.
tickerNoEvent and news webhooks only: the symbols it is scoped to, or `null` for the universe or the whole market.
cadenceNoScan, ticker and signal webhooks only: how often the trigger is evaluated. Event and news webhooks fire as rows land. One of: `realtime`, `hourly`, `nyse_open`.
channelYesWhere deliveries go. One of: `webhook`, `discord`, `in_app`, `mobile_push`.
test_urlNoReturned on create only, when the channel delivers outside the dashboard: the path of `POST /v2/webhooks/{webhook}/test` for this record.
universeYesUniverse the trigger is scoped to, or `null` for the whole market.
created_atYesCreation timestamp (epoch seconds).
last_errorNoThe last evaluation error; `null` on a healthy hook. The answer to "why is my webhook not firing?".
last_firedYesWhen a delivery last went out (epoch seconds); `null` if it never has.
target_urlYesYour HTTPS endpoint; `null` on every channel except `webhook`.
updated_atYesLast modification timestamp (epoch seconds).
_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).
disabled_atNoAfter an `evaluation_failure`, `plan_downgrade` or `subscription_canceled`: when it was disabled (epoch seconds).
next_eval_atNoWhen the evaluator will next consider this subscription (epoch seconds).
failing_sinceNoWhen the current failure streak began (epoch seconds); `null` while deliveries are succeeding.
min_relevanceNoNews webhooks only: the least `relevance` a scoped ticker needs, or `null`.
channel_configYesReturned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id).
last_match_setNoScan, ticker and signal webhooks only: tickers matching at the last evaluation, the set the next run is diffed against, which is what makes firing edge-triggered.
signing_secretYesReturned on create only, and shown once. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries.
disabled_reasonNoDisabled webhooks only: why it was turned off. Turn it back on with `PATCH /v2/webhooks/{webhook}` and `enabled: true`. One of: `user_disabled`, `delivery_failure`, `evaluation_failure`, `plan_downgrade`, `subscription_canceled`.
last_success_atNoWhen a delivery last reached your endpoint, in epoch seconds (`created_at` until the first one does).
last_evaluated_atNoScan, ticker and signal webhooks only: when it was last evaluated (epoch seconds); `null` until the first run.
last_eval_error_atNoWhen the last evaluation error happened (epoch seconds); `null` on a healthy hook.
disabled_last_errorNoAfter a `delivery_failure` or `evaluation_failure`: the error that disabled it; `null` when your endpoint answered with an HTTP status (see `disabled_last_status_code`).
subscription_originYesWhich subscribe route created it: `type` (`ticker`/`signal`/`scan`/`event`/`news`), its `ref` and the `condition` in display form.
consecutive_failuresNoDeliveries in a row that failed after the full retry ladder; resets on any success. Informational: a webhook is disabled when deliveries have kept failing for 72 hours (since `failing_since`) with none getting through, not on a count.
disabled_explanationNoAfter an `evaluation_failure`: what changed and what to use instead, for example the new name of a renamed signal.
disable_email_sent_atNoWhen we emailed you about the disable (epoch seconds).
channel_config_presentNoDiscord and mobile-push webhooks: `true` when delivery settings are stored. The Discord URL itself is never returned after create.
disabled_last_status_codeNoAfter a `delivery_failure`: the HTTP status your endpoint last returned.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv0.4.1
    • addedInput schema / anyOf
      Added value: +[
      +  {
      +    "required": [
      +      "kind"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "kinds"
      +    ]
      +  }
      +]
    • changedInput schema / properties / channel / description
      Previous value: -"Delivery channel."New value: +"Delivery channel: `webhook` (POST to `target_url`), `discord` (an embed at `discord_url`), `in_app` (the dashboard only) or `mobile_push` (to `device_id`). Inferred when omitted: `discord` if `discord_url` is set, else `mobile_push` if `device_id` is set, else `webhook` if `target_url` is set, else `in_app`. See Delivery channels. Values: webhook: POST the payload to an HTTPS endpoint you own, signed with `X-Tickerbot-Signature`. discord: Post to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed: the URL is itself the credential. in_app: Deliver to the in-app feed. No external receiver, so nothing to validate and no `test_url`. mobile_push: Push to a registered device. Requires a `device_id` from Register a device."
    • removedInput schema / properties / channel / enum
      Removed value: -[
      -  "webhook",
      -  "discord",
      -  "in_app",
      -  "mobile_push"
      -]
    • addedInput schema / properties / channel / pattern
      Added value: +"^\\s*([wW][eE][bB][hH][oO][oO][kK]|[dD][iI][sS][cC][oO][rR][dD]|[iI][nN]_[aA][pP][pP]|[mM][oO][bB][iI][lL][eE]_[pP][uU][sS][hH])\\s*$"
    • changedInput schema / properties / device_id / description
      Previous value: -"Registered device id from the mobile app (channel mobile_push)."New value: +"Only with `channel=mobile_push`. Device to notify, from `POST /v2/devices/register`. An unknown id is a 400 `device_not_found`."
    • changedInput schema / properties / discord_url / description
      Previous value: -"Discord incoming-webhook URL (channel discord)."New value: +"Only with `channel=discord`. Discord incoming-webhook URL (`https://discord.com/api/webhooks/…`). Stored as a posting credential: the create response echoes it back under `channel_config`, but every later read (list, get, deliveries) strips it and sets `channel_config_present: true` instead."
    • removedInput schema / properties / event_q
      Removed value: -{
      -  "description": "Optional event-CONTENT filter over (ticker, ts, kind, payload jsonb) — only those four identifiers, e.g. payload->>'firm' = 'Goldman Sachs' AND payload->>'action' = 'downgrades'.",
      -  "type": "string"
      -}
    • addedInput schema / properties / kind
      Added value: +{
      +  "anyOf": [
      +    {
      +      "pattern": "^\\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]|[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]|[eE][sS][tT][iI][mM][aA][tT][eE]_[rR][eE][vV][iI][sS][iI][oO][nN]))*\\s*$",
      +      "type": "string"
      +    },
      +    {
      +      "items": {
      +        "pattern": "^\\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]|[eE][sS][tT][iI][mM][aA][tT][eE]_[rR][eE][vV][iI][sS][iI][oO][nN])\\s*$",
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  ],
      +  "description": "Event kinds to fire on, an array or a comma list. `filing` fires when a 10-K, 20-F, 40-F or 10-Q lands (the next morning's EDGAR index read); `estimate_revision` when the nightly consensus refresh moves an EPS estimate, one event per fiscal period and horizon that moved (about 1,000 a night across the market). Values: earnings: Fires on each quarterly earnings report: reported vs estimated EPS and the surprise. dividend: Fires on each cash-dividend declaration. split: Fires on each stock split or reverse split. filing: Fires when a 10-K, 20-F, 40-F or 10-Q lands, from the next morning’s EDGAR index read. insider: Fires on each reported Form 4 transaction by an officer or director. analyst: Fires on each upgrade, downgrade, initiation or price-target change. estimate_revision: Fires when the nightly consensus refresh moves an EPS estimate, one event per fiscal period and horizon that moved (about 1,000 a night across the market)."
      +}
    • removedInput schema / properties / kinds
      Removed value: -{
      -  "description": "Comma list of kinds to fire on — any of: dividend, split, insider, analyst (e.g. \"split,analyst\"). NOTE: no enum here on purpose — a scalar enum would reject multi-kind values.",
      -  "type": "string"
      -}
    • changedInput schema / properties / name / description
      Previous value: -"Display name."New value: +"Display name, up to 80 characters. Defaults to `events: <kinds> · <scope>`."
    • changedInput schema / properties / q / description
      Previous value: -"Optional row-STATE filter evaluated against the event's ticker at fire time, e.g. market_cap > 1e10."New value: +"The filter, as on Query events with `join=state`: the event's own fields (`id`, `ticker`, `ts`, `kind`, `payload`, and with one kind its payload fields by bare name) and the ticker's signals at fire time, in one WHERE clause. A payload field and a signal with the same name resolve to the signal, as on Query events: `price` on insider, `cik` on filing. Spell the event's own value `payload->>'price'`. Custom signals are expanded and frozen at creation."
    • addedInput schema / properties / select
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  ],
      +  "description": "What each delivered event carries: `id`, `ticker`, `ts` and `kind` always, then the names you list, at the top level: `payload`, the payload fields of the one kind named, and ticker signals at fire time. Omitted: each event as on Query events (`payload` whole)."
      +}
    • changedInput schema / properties / target_url / description
      Previous value: -"HTTPS delivery URL. Omit for in-app delivery."New value: +"Only with `channel=webhook`. HTTPS URL each delivery is POSTed to."
    • addedInput schema / properties / ticker
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  ],
      +  "description": "One ticker or a comma list (up to 50). Not combinable with `universe`. Omit both for every ticker."
      +}
    • removedInput schema / properties / tickers
      Removed value: -{
      -  "description": "Scope to specific tickers (comma list, max 50). Mutually exclusive with universe; omit both for all tickers.",
      -  "type": "string"
      -}
    • changedInput schema / properties / universe / description
      Previous value: -"Scope to a universe slug (top_10, top_100, or a saved one)."New value: +"Scope to a built-in universe (`top_10`, `top_100`) or one of your own, by id. An unknown one is a 400 `universe_not_found` naming it."
    • removedInput schema / required
      Removed value: -[
      -  "kinds"
      -]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "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": "Returned on create only, and only when the rule or `select` named a signal under its pre-2026-09-07 spelling: `deprecated_signals` lists each one (`requested`, `use`, `note`). The stored rule carries the current name."
      +    },
      +    "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"
      +      ]
      +    },
      +    "cadence": {
      +      "description": "Scan, ticker and signal webhooks only: how often the trigger is evaluated. Event and news webhooks fire as rows land. One of: `realtime`, `hourly`, `nyse_open`.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "channel": {
      +      "description": "Where deliveries go. One of: `webhook`, `discord`, `in_app`, `mobile_push`.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "channel_config": {
      +      "description": "Returned on create only: the channel-specific delivery settings as stored (e.g. the Discord URL, the device id)."
      +    },
      +    "channel_config_present": {
      +      "description": "Discord and mobile-push webhooks: `true` when delivery settings are stored. The Discord URL itself is never returned after create."
      +    },
      +    "consecutive_failures": {
      +      "description": "Deliveries in a row that failed after the full retry ladder; resets on any success. Informational: a webhook is disabled when deliveries have kept failing for 72 hours (since `failing_since`) with none getting through, not on a count."
      +    },
      +    "created_at": {
      +      "description": "Creation timestamp (epoch seconds).",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "dir": {
      +      "description": "Sort direction for those lists: `desc` unless you chose one. `null` on event and news webhooks. One of: `asc`, `desc`.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "disable_email_sent_at": {
      +      "description": "When we emailed you about the disable (epoch seconds)."
      +    },
      +    "disabled_at": {
      +      "description": "After an `evaluation_failure`, `plan_downgrade` or `subscription_canceled`: when it was disabled (epoch seconds)."
      +    },
      +    "disabled_explanation": {
      +      "description": "After an `evaluation_failure`: what changed and what to use instead, for example the new name of a renamed signal."
      +    },
      +    "disabled_last_error": {
      +      "description": "After a `delivery_failure` or `evaluation_failure`: the error that disabled it; `null` when your endpoint answered with an HTTP status (see `disabled_last_status_code`)."
      +    },
      +    "disabled_last_status_code": {
      +      "description": "After a `delivery_failure`: the HTTP status your endpoint last returned."
      +    },
      +    "disabled_reason": {
      +      "description": "Disabled webhooks only: why it was turned off. Turn it back on with `PATCH /v2/webhooks/{webhook}` and `enabled: true`. One of: `user_disabled`, `delivery_failure`, `evaluation_failure`, `plan_downgrade`, `subscription_canceled`."
      +    },
      +    "failing_since": {
      +      "description": "When the current failure streak began (epoch seconds); `null` while deliveries are succeeding."
      +    },
      +    "id": {
      +      "description": "The webhook id (`wh_…`), the handle for every other call on this record.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "kind": {
      +      "description": "Event webhooks only: the kinds subscribed. One of: `earnings`, `filing`, `dividend`, `split`, `insider`, `analyst`, `estimate_revision`."
      +    },
      +    "last_error": {
      +      "description": "The last evaluation error; `null` on a healthy hook. The answer to \"why is my webhook not firing?\"."
      +    },
      +    "last_eval_error_at": {
      +      "description": "When the last evaluation error happened (epoch seconds); `null` on a healthy hook."
      +    },
      +    "last_evaluated_at": {
      +      "description": "Scan, ticker and signal webhooks only: when it was last evaluated (epoch seconds); `null` until the first run.",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "last_fired": {
      +      "description": "When a delivery last went out (epoch seconds); `null` if it never has."
      +    },
      +    "last_match_set": {
      +      "description": "Scan, ticker and signal webhooks only: tickers matching at the last evaluation, the set the next run is diffed against, which is what makes firing edge-triggered.",
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    },
      +    "last_success_at": {
      +      "description": "When a delivery last reached your endpoint, in epoch seconds (`created_at` until the first one does).",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "min_relevance": {
      +      "description": "News webhooks only: the least `relevance` a scoped ticker needs, or `null`."
      +    },
      +    "name": {
      +      "description": "Your label for the subscription.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "next_eval_at": {
      +      "description": "When the evaluator will next consider this subscription (epoch seconds).",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    },
      +    "order": {
      +      "description": "Sort signal for each delivery's match lists: `market_cap` unless you chose one, so a broad alert lists the same top 100 names each time. `null` on event and news webhooks.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "q": {
      +      "description": "The stored predicate. Custom signals appear expanded: the SQL is frozen at creation. On an event webhook, the whole filter (the event's fields and the ticker's signals); `null` when it fires on every event. On a news webhook, the Query news `q`, or `null`.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "search": {
      +      "description": "News webhooks only: the full-text search it fires on, or `null`."
      +    },
      +    "select": {
      +      "description": "The signals each delivered match carries, after `ticker`; `null` means the scan default row plus the signals the rule uses in `q` and `order`. On a news webhook, the article fields each delivered article carries."
      +    },
      +    "signing_secret": {
      +      "description": "Returned on create only, and shown once. HMAC key for verifying the `X-Tickerbot-Signature` header on deliveries."
      +    },
      +    "status": {
      +      "description": "Whether it is live. `disabled_reason` says why a webhook is disabled. One of: `active`, `disabled`.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "subscription_origin": {
      +      "description": "Which subscribe route created it: `type` (`ticker`/`signal`/`scan`/`event`/`news`), its `ref` and the `condition` in display form.",
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "target_url": {
      +      "description": "Your HTTPS endpoint; `null` on every channel except `webhook`."
      +    },
      +    "test_url": {
      +      "description": "Returned on create only, when the channel delivers outside the dashboard: the path of `POST /v2/webhooks/{webhook}/test` for this record."
      +    },
      +    "ticker": {
      +      "description": "Event and news webhooks only: the symbols it is scoped to, or `null` for the universe or the whole market."
      +    },
      +    "universe": {
      +      "description": "Universe the trigger is scoped to, or `null` for the whole market."
      +    },
      +    "updated_at": {
      +      "description": "Last modification timestamp (epoch seconds).",
      +      "type": [
      +        "number",
      +        "null"
      +      ]
      +    }
      +  },
      +  "required": [
      +    "as_of",
      +    "id",
      +    "name",
      +    "q",
      +    "select",
      +    "order",
      +    "dir",
      +    "universe",
      +    "channel",
      +    "target_url",
      +    "status",
      +    "subscription_origin",
      +    "created_at",
      +    "updated_at",
      +    "last_fired",
      +    "channel_config",
      +    "signing_secret"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.2.0

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full behavioral burden and does substantial work: it discloses the paid-plan prerequisite, the delivery latency model per kind, and the name-clash resolution rule where ticker signals override event payload fields. It stops short of stating subscription limits, idempotency, or auth requirements beyond the plan gate.

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?

Four sentences, front-loaded with purpose, then plan constraint, then the `q` filtering rule, then latency. Each sentence carries information, though the middle sentence is dense with SQL-flavored jargon that slows scanning.

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 10-parameter subscription tool with an output schema and full schema coverage, the description supplies what the structured fields cannot: plan gating, latency expectations, and filter resolution rules. The remaining gap is routing guidance against the four sibling subscribe tools, which an agent needs in order to select correctly.

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%, so every parameter is already documented and the baseline is 3. The description's explanation of `q` scope (event fields plus ticker signals at fire time) and the `payload->>'price'` escape hatch largely restates what the `q` schema entry already says, adding only the worked examples.

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: an alert fired when new events of chosen kinds land, filtered on event fields and ticker signals. That makes it distinguishable from the news/scan/signal subscribe siblings by resource. However, it frames delivery as "by webhook" even though the channel parameter allows discord, in_app and mobile_push, so the stated purpose is narrower than the tool's actual scope.

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?

It gives real usage context — webhooks require a paid plan, Free has no webhook slots, and latency follows ingest cadence rather than being sub-minute. What it never states is when to pick this over tickerbot_subscribe_signal, tickerbot_subscribe_scan or tickerbot_subscribe_news, so an agent must infer the choice from the resource name alone.

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