将您的智能体连接到预计算的市场上下文，以提高推理能力并减少 Token 使用量。
将 TickerDB 连接到任何兼容 MCP 的客户端：Claude Desktop、Claude Code、Cursor、Windsurf、OpenClaw、LangChain、LlamaIndex、AutoGen、CrewAI 等。
工具 | 描述 |
| 单个代码的技术面 + 基本面摘要（支持日期范围、事件过滤和移动平均线距离回溯） |
| 通过分类状态和过滤器搜索资产 |
| 查看可用字段和过滤选项（始终免费，0 积分） |
| 您保存的自选股列表的实时数据 |
| 自上次流水线运行以来的字段级差异 |
| 将代码添加到您的自选股列表 |
| 从您的自选股列表中移除代码 |
| 账户详情、套餐等级和使用情况 |
| 为自选股变化注册 Webhook |
| 列出已注册的 Webhook |
| 移除 Webhook |
所有工具在每个等级（免费版、Plus 版、Pro 版）均可用 —— 等级区别在于速率限制、历史深度和自选股列表大小。详情请参阅 tickerdb.com/pricing。
在批量同步日期范围内的代码时，请使用带有 start/end 参数的 get_summary；或者使用 field/band 参数来查询事件发生情况。当您想要聚合事件区间和后续分布而不是原始行数据时，请在事件模式下添加 stats=true。
get_watchlist 不接受时间范围。请使用 get_watchlist_changes 获取每日或每周的差异。
当前的摘要快照还通过 as_of_date 暴露顶层新鲜度，提供更丰富的 volume 字段（如 price_direction_on_volume），可选的付费等级元数据（如 support_level.status_meta），Pro 级的 sector_context 字段（如 agreement 和 overbought_count），以及在可用时提供仅限股票的嵌套 fundamentals.insider_activity。
移动平均线（MA）距离字段在整个堆栈中均可用：
使用扁平的 schema/search/event 名称，如 trend_distance_ma8、trend_distance_ma20、trend_distance_ma50、trend_distance_ma100 和 trend_distance_ma200。
摘要快照在 trend.distance_from_ma_band.ma_8 到 ma_200 下暴露嵌套的 MA 距离区间。
MA 事件查询除了支持像 slightly_above 这样的细粒度值外，还支持分组的 band=above 和 band=below 别名。
get_summary 默认隐藏同级的 _meta 对象，以便主要区间标签保持在最显眼的位置。传递 meta: true 可在响应中包含完整的付费等级稳定性元数据，或者仅请求您需要的特定 *_meta 字段。get_watchlist 默认包含付费等级的 _meta 对象，而 get_watchlist_changes 会在每个变更对象内联返回稳定性字段。
稳定性标签包括 fresh（新鲜）、holding（持有）、established（已确立）或 volatile（波动）。完整元数据包括 periods_in_current_state、flips_recent 和 flips_lookback，这有助于智能体区分刚进入的状态和已持续多个周期的状态。
Related MCP server: FinanceKit MCP
位于 mcp.tickerdb.com 的远程服务器支持 Claude.ai 连接器的 OAuth 2.1。无需管理 API 密钥 —— 使用您的 TickerDB 账户登录，Claude.ai 会处理其余事项。
将任何 MCP 客户端连接到 https://mcp.tickerdb.com/mcp，并将您的 API 密钥作为 Bearer token 使用。
添加到您的 Claude Desktop 配置 (claude_desktop_config.json) 中：
{
"mcpServers": {
"tickerdb": {
"command": "npx",
"args": ["tickerdb-mcp"],
"env": {
"TICKERDB_KEY": "tdb_your_api_key_here"
}
}
}
}在 tickerdb.com/dashboard 获取 API 密钥。
这是一个包含三个包的工作区：
shared/ —— 共享工具定义、API 客户端和服务器工厂（内部，未发布）
remote/ —— 部署在 mcp.tickerdb.com 的 Cloudflare Worker（流式 HTTP 传输 + OAuth 2.1）
local/ —— 已发布的 npm 包 tickerdb-mcp（stdio 传输）
远程服务器和 npm 包都使用来自 shared/ 的相同工具定义。MCP 服务器是一个轻量级代理 —— 所有基于等级的访问控制、速率限制和字段过滤均由 TickerDB HTTP API 处理。
远程服务器支持两种身份验证方法：
Bearer token —— 直接将您的 tdb_* API 密钥作为 Authorization: Bearer tdb_... 传递
OAuth 2.1 —— 由 Claude.ai 连接器使用。服务器实现了动态客户端注册、PKCE、令牌交换和撤销。/authorize 端点会重定向到 TickerDB 主站以获取授权。
对于使用混合身份验证的 OAuth 支持的 MCP 客户端，Worker 允许在 POST /mcp 上进行未经身份验证的 initialize 和 tools/list 发现，但执行实际工具时需要身份验证。受保护的工具调用会返回标准的 401 Bearer 质询，其中 resource_metadata 指向 /.well-known/oauth-protected-resource/mcp，以便客户端可以重新授权或重新挂载。
远程 Worker 默认为 无状态 MCP 传输。这是有意为之的：所有 TickerDB MCP 工具都是请求/响应无状态的，而 Cloudflare Worker 内存是隔离的本地内存，可能会在请求之间发生漂移。默认为无状态传输可避免边缘会话丢失，从而防止连接器发现的 link_... 命名空间在链式调用中失效。在无状态模式下，Worker 仅接受 POST /mcp 请求，使用 JSON 请求/响应模式，并拒绝 GET/DELETE 会话生命周期请求，以防止连接器运行时意外拆除或重新绑定从未打算有状态的命名空间。
如果您需要调试显式的 MCP 会话行为，请设置 MCP_SESSION_MODE=stateful。在该模式下，陈旧或缺失的 Mcp-Session-Id 标头会返回显式错误，而不是静默降级为新的传输。
# Install dependencies
npm install
# Type-check the remote worker/shared sources
npm run build
# Dev server for remote worker
npx wrangler dev
# Build the npm package
cd local && npm install && npm run build远程服务器：
npx wrangler deploynpm 包 + MCP 注册表（推荐）：
# From the monorepo root
export MCP_PUBLISHER_KEY="your_saved_tickerdb_registry_private_key_hex"
./release.sh mcp patch这会提升 local/package.json 版本，保持 server.json 同步，将 tickerdb-mcp 发布到 npm，刷新 tickerdb.com 的 DNS 验证，并将 MCP 服务器元数据发布到官方 MCP 注册表。
仅 npm 包（手动）：
cd local
npm version patch
npm run build
npm publishAdd tickers to the user's saved watchlist. Duplicates are skipped. Only call this when the user explicitly asks to track, save, or watch a ticker; do not add tickers just because they came up in conversation. The watchlist is capped by the plan's watchlist_limit (see get_account), so the request can be rejected or accepted only in part. Report back which tickers the response actually confirms rather than assuming every requested ticker was added.
| Name | Required | Description | Default |
|---|---|---|---|
| tickers | Yes | Array of ticker symbols to add, e.g. ["AAPL", "MSFT", "BTCUSD"] |
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint, readOnlyHint false), the description discloses that duplicates are skipped, that the watchlist has a plan-dependent cap that can cause partial acceptance, and that the agent should report confirmed tickers rather than assuming all were added. This adds meaningful behavioral transparency that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each serving a distinct purpose: purpose, idempotency, usage condition, and limit/reporting. It is front-loaded with the primary action and contains no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an add-to-watchlist tool with an output schema present, the description covers when to call, duplicate handling, plan limits, partial acceptance, and reporting requirements. The sibling tools and annotations complement this, making the description complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the 'tickers' parameter with an example array (['AAPL', 'MSFT', 'BTCUSD']), achieving 100% schema description coverage. The description does not add additional parameter-level detail beyond referencing tickers in context, so the baseline 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add tickers to the user's saved watchlist', a specific verb+resource statement that clearly distinguishes the tool from the sibling get_watchlist and remove_from_watchlist. The duplicate-skipping behavior further clarifies the operation's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Only call this when the user explicitly asks to track, save, or watch a ticker; do not add tickers just because they came up in conversation.' It also points to get_account for the plan's watchlist_limit, providing a cross-reference for capacity constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your account details including current plan tier, monthly credit limits, and current usage. Response includes tier, limits (monthly_requests, overage_enabled, watchlist_limit, search_results, webhook_urls, history_days), and usage (monthly_requests_used, monthly_requests_remaining, credit_balance for pay-per-use accounts). Also returns scheduled_tier and scheduled_change_at if a plan change is pending.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint=false. The description adds useful context about response fields, pending plan changes, and pay-per-use credit balances, exceeding the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, front-loaded with the main purpose, then structured enumeration of response fields. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with strong annotations and an existing output schema, the description fully covers response details and special cases (pay-per-use, pending plan changes). It leaves no material gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is trivially 100%. With no parameters to explain, the baseline of 4 applies, and the description appropriately focuses on response semantics rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves account details including plan tier, limits, and usage, distinguishing it from sibling tools that handle market data or watchlist operations. The verb 'get' plus specific resource delineation makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Though it doesn't explicitly name alternatives, the scope 'your account' contrasts sharply with sibling tools focused on market data or watchlists, making the intended use clear. It lacks explicit when/when-not guidance, but the context is strong enough to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get stored end-of-day OHLCV candles for a stock, ETF, or crypto ticker, daily or weekly. Use this for exact-return calculations, charts, and backtests after get_summary identifies a setup. Results are paginated; pass next_cursor back as cursor to continue. Equity and ETF bars are split-and-dividend adjusted; crypto bars are unadjusted. Credit cost is 1 credit per 100 bars returned, rounded up, with a 1 credit minimum.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Inclusive end date (YYYY-MM-DD). Compared against the candle date. | |
| limit | No | Maximum candles to return (1-1000). Default: 100. | |
| order | No | Sort by candle date. Default: desc. | |
| start | No | Inclusive start date (YYYY-MM-DD). Compared against the candle date, so for weekly this is the Sunday week end. Lookback is limited by plan. | |
| cursor | No | Exclusive date cursor from next_cursor for pagination (YYYY-MM-DD). | |
| ticker | Yes | Ticker symbol, e.g. AAPL, BTCUSD, SPY | |
| timeframe | No | Candle timeframe. Default: daily. Weekly candles cover Monday-Sunday and are dated by the Sunday week end, matching get_summary with timeframe=weekly. The in-progress week is not returned. |
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses crucial behaviors: pagination via next_cursor, split/dividend adjustments for equities vs. unadjusted crypto, and a specific credit cost formula. This adds significant context for expected behavior and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, using five sentences to cover purpose, use case, pagination, adjustment policy, and cost. Every sentence contributes unique value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, output schema present, multiple asset types), the description covers all essential aspects: what it does, when to use it, pagination, adjustment nuances, and cost implications. It references siblings appropriately and works well with the rich schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents all parameters. The description adds value by clarifying pagination usage ('pass next_cursor back as cursor') and the credit cost tied to the limit parameter, which enhances understanding of cursor and limit beyond their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves stored end-of-day OHLCV candles for stocks, ETFs, or crypto, with daily or weekly timeframes. It uses a specific verb ('Get') and resource ('OHLCV candles'), and distinguishes itself from siblings like get_summary by its focus on historical candle data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use: 'Use this for exact-return calculations, charts, and backtests after get_summary identifies a setup.' This provides clear context and references the sibling get_summary as a precursor, making the workflow obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the schema of all available fields and their valid band values. Use this when the user asks 'what fields are available?', 'what bands does momentum_rsi_zone have?', 'what sectors exist?', or when you need to validate field/band names before calling get_summary with event parameters or get_search with filters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the tool's role in validation and references downstream tools (get_summary, get_search), which enriches behavioral understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences. The first sentence is a clear, direct statement of purpose; the second provides quick usage contexts and integration points. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only schema tool with an output schema present, the description fully covers what it does, when to use it, and how it relates to sibling tools. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4. The description adds meaning by explaining what the returned schema contains (fields and valid band values), which is useful even though no parameters need explaining.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the schema of all available fields and their valid band values.' It names the specific resource (schema) and provides concrete example user queries, distinguishing it from sibling tools like get_summary or get_search by positioning it as a validation/preparatory step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use scenarios: user questions about fields, bands, sectors, and validating names before get_summary/get_search. It does not state when-not-to-use or alternative tools, but the guidance is clear enough to be more than merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for assets matching filter criteria, including categorical states (e.g. oversold assets, strong uptrends, bull/bear flag setups, triangle or wedge setups, free-cash-flow surplus or burn, recent golden crosses, weekly stage 2 assets near the 40w MA with high volume, volatility squeeze active, volume climax detected, insider buying zone, sector-aligned breakouts) or rankings by a field such as market_cap on a historical date. Pass filters as a JSON-encoded array of {field, op, value} objects. Use get_schema to discover valid field names; fields use clean flat names for raw values such as pe_ratio, ma8, and ma200, and full expanded names for semantic fields such as momentum_rsi_zone, pattern_bull_flag, pattern_bull_flag_breakout, pattern_bear_flag_breakdown, pattern_ascending_triangle, pattern_rising_wedge, trend_ma_crossover_event, trend_distance_ma40, trend_stage, fundamentals_free_cash_flow, insider_zone, sector_agreement, volatility_squeeze_active, volume_climax_detected, fundamentals_analyst_consensus, and fundamentals_earnings_proximity, fundamentals_earnings_proximity_basis. Use fields to control returned columns and sort_by to rank results server-side.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Historical snapshot date (YYYY-MM-DD). Omit for latest per asset class. | |
| limit | No | Max results to return. Tier-gated: Starter 25, Plus 100, Pro 500. Default: 20 | |
| fields | No | JSON-encoded array of column names to return. Example: ["ticker", "sector", "market_cap", "pe_ratio", "trend_stage", "ma40", "trend_ma50_slope", "trend_ma_crossover_event", "trend_distance_ma40", "pattern_bull_flag", "pattern_bull_flag_breakout", "pattern_bear_flag_breakdown", "pattern_ascending_triangle", "fundamentals_free_cash_flow", "volume_ratio_band", "insider_zone", "sector_agreement", "volatility_squeeze_active", "volume_climax_detected", "fundamentals_analyst_consensus", "fundamentals_earnings_proximity", "fundamentals_earnings_proximity_basis"]. Omit to get a default core subset: ticker, asset_class, sector, market_cap, market_cap_tier, performance, trend_direction, trend_ma20_slope, trend_ma_compression_band, trend_ma_crossover_event, momentum_rsi_zone, extremes_condition, extremes_condition_rarity, volatility_regime, volume_ratio_band, pattern_bull_flag, pattern_bull_flag_breakout, pattern_bear_flag, pattern_bear_flag_breakdown, pattern_ascending_triangle, pattern_descending_triangle, pattern_symmetrical_triangle, pattern_rising_wedge, pattern_falling_wedge, fundamentals_valuation_zone, range_position. Request fundamentals_free_cash_flow explicitly when you need the stock-only free cash flow burn/surplus band. Request ma8 through ma200 for raw MA values and trend_ma8_slope through trend_ma200_slope for the full MA slope set. Use ["*"] for all fields. Specify fields to reduce token usage. trend_stage is weekly-only and should be requested with timeframe=weekly. Insider fields (insider_zone, insider_net_direction) and sector context fields (sector_rsi_zone, sector_trend, sector_agreement) are available on paid tiers. | |
| filters | Yes | JSON-encoded filter array. Each filter: {"field": "column_name", "op": "eq|neq|in|gt|gte|lt|lte", "value": "..."}. Example: [{"field": "momentum_rsi_zone", "op": "in", "value": ["oversold", "deep_oversold"]}, {"field": "sector", "op": "eq", "value": "Technology"}] | |
| sort_by | No | Column name to sort results by (e.g. "market_cap", "pe_ratio", "extremes_condition_percentile", "fundamentals_valuation_percentile", "volume_percentile", "sector_oversold_count", "sector_breakout_count"). Must be a valid field name from the schema. Server-side sorting avoids pulling extra fields for client-side ranking. | |
| timeframe | No | Analysis timeframe. Default: daily | |
| sort_direction | No | Sort direction. Default: desc. Use 'asc' for lowest-first (e.g. cheapest valuation percentile). |
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior, so the description doesn't need to repeat that. It adds valuable context about filter encoding, field naming conventions, and server-side sorting, which helps agents understand the tool's expected inputs and behavior. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph but front-loaded with the core purpose. Every sentence provides useful information about filter types, field naming, and usage. While somewhat long, it avoids fluff and structures the information logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, output schema present, annotations available), the description covers key aspects: search use cases, filter format, field discoverability, and column/sort control. It leaves mention of pagination and defaults to the schema, which is acceptable given the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the JSON-encoded filter format, listing example semantic fields, and clarifying the distinction between raw and expanded field names, which goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for assets matching filter criteria, including categorical states and rankings by fields. It distinguishes itself from sibling tools like get_summary and get_ohlcv by focusing on filtered asset search, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (searching assets with filters) and provides a cross-reference to get_schema for field discovery. It does not explicitly state when not to use it versus alternatives, but the guidance on filters and fields implies its role as the primary search tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get pre-computed market intelligence for a specific stock, crypto, or ETF ticker. Supports 4 modes: (1) Snapshot (default) for the latest categorical state; (2) Historical snapshot by date; (3) Historical series with start and end dates; (4) Events by field and optional band, including aftermath fields on paid tiers, weekly trend_stage analysis, pattern setup states such as pattern_bull_flag and pattern_ascending_triangle, MA signal fields, trend_ma_crossover_event, MA distance lookbacks such as trend_distance_ma40, and stock-only fundamentals_free_cash_flow events. Add stats=true in event mode to return aggregate event-band and aftermath distributions instead of raw rows. Results can include freshness via as_of_date, same-candle OHLCV, market_cap, market_cap_tier, trend, momentum (including divergence_detected, divergence_type, stochastic_zone), volatility (including squeeze_active, squeeze_days), volume (including climax_detected, climax_type), patterns, support/resistance, levels (paid tiers), sector_context (rsi_zone, trend, agreement, asset_vs_sector_rsi), and stock-only fundamentals such as raw pe_ratio (latest ratio on or before the snapshot date; negative values preserved and unavailable values null), free_cash_flow, growth_zone, earnings_proximity, earnings_proximity_basis, analyst_consensus, valuation_percentile, and nested insider_activity when available. Summary keeps sibling _meta objects off by default; set meta=true or request explicit *_meta fields when paid-tier stability metadata is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Range end date (YYYY-MM-DD). Use with start for historical series. | |
| band | No | Filter events to a specific band value (e.g. deep_oversold, strong_uptrend, stage_2_growth). For MA distance event fields such as trend_distance_ma40, grouped aliases above and below are also supported. Only used with field. | |
| date | No | Historical date (YYYY-MM-DD) for a point-in-time snapshot. Requires Plus or Pro plan. Omit for latest. | |
| meta | No | Snapshot and history modes only. Add true to include sibling _meta / status_meta stability objects across the response. Explicit *_meta field paths in fields still work without this flag. | |
| after | No | Return events after this date (YYYY-MM-DD). Only used with field. | |
| field | No | Band field name for event queries (e.g. momentum_rsi_zone, extremes_condition, trend_direction, trend_stage, pattern_bull_flag, pattern_ascending_triangle, pattern_rising_wedge, trend_ma8_slope through trend_ma200_slope, trend_ma_crossover_event, trend_distance_ma40, fundamentals_valuation_zone, fundamentals_free_cash_flow, insider_zone, sector_rsi_zone, momentum_divergence_detected, fundamentals_analyst_consensus). When provided, returns band transition history instead of a snapshot. | |
| limit | No | For event mode: max results (1-50), returned newest-first by default. For sample=even date ranges: requested sampled rows, capped by plan (Free 3, Plus 10, Pro 50). | |
| start | No | Range start date (YYYY-MM-DD). Use with end for historical series. | |
| stats | No | Event mode only. Add true to return aggregate stats instead of raw event rows. | |
| before | No | Return events before this date (YYYY-MM-DD). Only used with field. | |
| fields | No | Optional summary fields to return. Identity fields such as market_cap and market_cap_tier are always kept. Pass sections like ohlcv, trend, momentum, volatility, volume, patterns, extremes, support_level, resistance_level, fundamentals, sector_context, or levels (paid tiers). Or pass dotted paths like ohlcv.close, trend.direction, trend.stage, trend.ma_slopes.ma_8, trend.ma_slopes.ma_20, trend.ma_slopes.ma_40, trend.ma_slopes.ma_50, trend.ma_slopes.ma_100, trend.ma_slopes.ma_200, trend.moving_average_values.ma_8, trend.ma_crossover_event, trend.direction_meta, trend.distance_from_ma_band.ma_40, trend.volume_confirmation, momentum.rsi_zone, momentum.stochastic_zone, momentum.xtrm_score, momentum.divergence_detected, momentum.divergence_type, momentum.macd_state, patterns.bull_flag, patterns.bull_flag_breakout, patterns.bear_flag, patterns.bear_flag_breakdown, patterns.ascending_triangle, patterns.rising_wedge, volatility.squeeze_active, volatility.squeeze_days, volatility.regime_trend, volume.climax_detected, volume.climax_type, volume.accumulation_state, volume.price_direction_on_volume, support_level.level_price, support_level.status_meta, resistance_level.level_price, sector_context.rsi_zone, sector_context.trend, sector_context.agreement, sector_context.asset_vs_sector_rsi, sector_context.asset_vs_sector_trend, sector_context.oversold_count, sector_context.valuation_zone, fundamentals.pe_ratio, fundamentals.valuation_zone, fundamentals.growth_zone, fundamentals.free_cash_flow, fundamentals.earnings_proximity, fundamentals.earnings_proximity_basis, fundamentals.last_earnings_surprise, fundamentals.analyst_consensus, fundamentals.analyst_consensus_direction, fundamentals.valuation_percentile, fundamentals.pe_vs_historical_zone, fundamentals.pe_vs_sector_zone, fundamentals.insider_activity, fundamentals.insider_activity.zone, fundamentals.insider_activity.net_direction, levels, levels.support_levels, levels.resistance_levels. trend.stage is populated on weekly snapshots when stage evidence is sufficient. Event field names should prefer full schema names such as momentum_rsi_zone, extremes_condition, trend_stage, pattern_bull_flag, pattern_ascending_triangle, pattern_rising_wedge, trend_ma8_slope through trend_ma200_slope, trend_ma_crossover_event, trend_distance_ma40, fundamentals_valuation_zone, fundamentals_free_cash_flow, insider_zone, sector_rsi_zone, momentum_divergence_detected, and fundamentals_analyst_consensus. | |
| sample | No | Date range mode only. Use 'even' to evenly distribute snapshots across the full start/end range. | |
| ticker | Yes | Ticker symbol, e.g. AAPL, BTCUSD, SPY | |
| timeframe | No | Analysis timeframe. Default: daily | |
| context_band | No | Only return events where the context ticker was in this band (e.g. downtrend). For MA distance context fields, grouped aliases above and below are also supported. Must be provided with context_ticker and context_field. | |
| context_field | No | Band field to check on the context ticker (e.g. trend_direction, trend_stage, or trend_distance_ma40). Must be provided with context_ticker and context_band. | |
| context_ticker | No | Cross-asset correlation: a second ticker to filter against (e.g. SPY). Requires context_field and context_band. Plus/Pro only. |
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, and the description goes far beyond by disclosing behavioral nuances: it explains that _meta objects are off by default, that certain fields require paid tiers, that identity fields are always returned, and that event mode returns band transition history. It also explains the semantics of 'stats' and 'sample' modes, adding substantial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long but information-dense, systematically covering modes, fields, and special behaviors. It could be slightly more scannable with bullet points, but every section adds value, and it avoids fluff. The length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 17 parameters and rich output schema, the description is exceptionally complete. It explains all four modes, parameter combinations, output field categories, tier restrictions, and special result behaviors. Even without seeing the output schema, the description gives enough detail to understand the response shape and key fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema provides 100% parameter descriptions, the tool description enriches them by explaining how parameters combine into modes, e.g., 'field' triggers event queries, 'start'+'end' define series, and 'meta' only affects snapshot/history modes. It also clarifies edge cases like negative PE ratio preservation and the distinction between event field names and dotted paths, going well beyond the schema's per-parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Get pre-computed market intelligence for a specific stock, crypto, or ETF ticker.' It further differentiates from siblings by describing four distinct modes (snapshot, historical snapshot, historical series, events) and the breadth of intelligence fields, clearly distinguishing it from raw price data tools like get_ohlcv.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed usage guidance by enumerating four modes and their parameters, such as using 'date' for historical snapshot, 'start'/'end' for series, 'field' for events, and 'stats=true' for aggregates. It also clarifies when meta is available and notes paid-tier restrictions, effectively telling the agent how to select the right mode for the task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get analytical summaries for every ticker on the user's saved watchlist. This supports requests about the user's watchlist, tracked stocks, portfolio tickers, or an overview of tracked assets. Each item includes trend, momentum, volatility, volume, extremes, support/resistance prices, and a notable_changes array of human-readable day-over-day change alerts (e.g. 'entered deep_oversold', 'volume spike', 'trend reversed to downtrend', 'earnings within days', 'squeeze activated', 'MA crossover: golden cross'). Additional per-item fields include squeeze_active, squeeze_days, climax_detected, climax_type, divergence_detected, divergence_type. Plus/Pro plans also return analyst_consensus, earnings_proximity, growth_zone, free_cash_flow. Pro plans also return insider_activity and insider_net_direction. Band fields include _meta stability objects on Plus and Pro plans. Use this only for questions that span the whole tracked set; for a question about one specific ticker use get_summary instead, even if that ticker is on the watchlist. When the question is only whether anything changed, prefer get_watchlist_changes: it returns just the deltas, whereas this returns a full summary per ticker and grows large on a watchlist of many assets. Use add_to_watchlist to save tickers first; an empty watchlist means the user has not saved any tickers yet, not that the lookup failed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context beyond that: it enumerates the analytical fields returned, notes plan-dependent fields (Plus/Pro and Pro-only), warns that the response grows large on many assets, and clarifies that an empty watchlist is not a failure. This fully discloses the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with the core purpose, follows with a detailed field enumeration, and ends with usage guidance. Every sentence adds value, though the 'supports requests about...' sentence is somewhat redundant with the first sentence. It is dense but efficient for such a rich output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description focuses on high-level semantics and usage decisions. It fully explains the tool's scope, the meaning of an empty watchlist, plan-dependent field availability, and alternatives for narrower queries. This is complete for an analyst agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so there are no parameter semantics to elaborate. The description fully covers the invocation context by describing what the tool operates on (the user's saved watchlist) and what it returns. Baseline for 0 params is 4, and the description exceeds any need by clarifying plan-dependent outputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get analytical summaries for every ticker on the user's saved watchlist.' It clearly differentiates from siblings by naming get_summary for single tickers and get_watchlist_changes for change-only queries, making the purpose distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('only for questions that span the whole tracked set') and when not to ('for a question about one specific ticker use get_summary instead', 'prefer get_watchlist_changes' for change detection). It also advises using add_to_watchlist first and clarifies that an empty watchlist is a valid state, not an error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get field-level state changes for all tickers on the user's saved watchlist since the last pipeline run. Supports daily day-over-day and weekly week-over-week comparisons. Each change object includes stability metadata such as stability, periods_in_current_state, flips_recent, and flips_lookback when available. Stability metadata requires a Plus or Pro plan. Prefer this over get_watchlist for monitoring questions such as whether anything moved, turned bearish, or became overbought, and for tracking a watchlist over time: it returns only what changed, while get_watchlist returns full summaries for every tracked ticker and is far larger on a big watchlist. Use get_watchlist when the current state of the whole list is needed rather than just the deltas. This is the only way to get week-over-week changes; the notable_changes array on get_watchlist is day-over-day only.
| Name | Required | Description | Default |
|---|---|---|---|
| timeframe | No | Change comparison period. daily = day-over-day, weekly = week-over-week. Default: daily |
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint false. The description adds valuable behavioral context: it returns only changed records, requires a Plus or Pro plan for stability metadata, and works relative to the last pipeline run. This goes beyond annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer but every sentence contributes: core function, supported comparisons, metadata plan requirement, and guidance versus sibling tools. It is front-loaded and well-structured, though slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and existing output schema, the description covers the data scope, use cases, and plan limitations. It explains why this tool should be chosen over get_watchlist and mentions the day-over-day only limitation of the sibling's notable_changes array.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the enum described. The description adds meaning by explaining 'daily' as day-over-day and 'weekly' as week-over-week, and notes the default. This supplements the schema without repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets field-level state changes for watchlist tickers since the last pipeline run, with a specific verb and resource. It also distinguishes itself from get_watchlist by emphasizing it returns only deltas, not full summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use and when-not-to-use guidance: prefer it over get_watchlist for monitoring changes, use get_watchlist for current full state, and notes it is the only way to get week-over-week changes. Names the alternative tool directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove tickers from the user's saved watchlist. Only call this when the user explicitly asks to stop tracking, remove, or drop a ticker; never prune the watchlist on your own initiative. Removal only stops tracking and can be undone with add_to_watchlist.
| Name | Required | Description | Default |
|---|---|---|---|
| tickers | Yes | Array of ticker symbols to remove, e.g. ["MSFT"] |
| Name | Required | Description |
|---|---|---|
| data | No | The TickerDB API response payload for this tool call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate write/destructive/idempotent traits, but the description adds that removal 'only stops tracking and can be undone with add_to_watchlist,' clarifying scope and reversibility beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver purpose, usage guidance, and behavioral context without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter removal tool with detailed annotations and an output schema, the description fully covers purpose, constraints, and consequences, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'tickers' is fully described in the schema with an example. The tool description does not add additional parameter-specific details, so the baseline 3 applies given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific verb+resource statement: 'Remove tickers from the user's saved watchlist.' It clearly distinguishes from siblings like add_to_watchlist and get_watchlist by stating the removal action and its reversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use ('when the user explicitly asks to stop tracking, remove, or drop a ticker') and when not to ('never prune the watchlist on your own initiative'), and names add_to_watchlist as the undo alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_to_watchlistget_accountget_ohlcvget_schemaget_searchget_summaryget_watchlistget_watchlist_changesremove_from_watchlistScored across 9 tools
Each tool targets a distinct resource/action. get_summary is for single-ticker analytics, get_watchlist for full watchlist summaries, get_watchlist_changes for deltas, and get_ohlcv for raw candles. Descriptions explicitly clarify when to use which, even in overlapping areas.
All read operations use get_ prefix (get_summary, get_ohlcv, get_search, get_schema, get_account, get_watchlist, get_watchlist_changes) and write operations use add_to_/remove_from_ (add_to_watchlist, remove_from_watchlist). The pattern is consistent and predictable.
9 tools is well within the ideal 3-15 range. The toolset covers market data retrieval, search, schema discovery, account management, and watchlist CRUD + monitoring — each tool earns its place with a clear purpose.
The domain is well covered: field discovery (get_schema), asset search (get_search), single-ticker analytics (get_summary), price history (get_ohlcv), watchlist management (add/remove/list/changes), and account status. No obvious dead ends or missing core operations.
Market intelligence for AI agents. Real-time data, cross-market analysis, and regime detection.
Crypto market signals, technical indicators, and sentiment analysis for AI agents.
Prediction markets, on-chain flows, ETF flows, equities and macro intelligence for AI agents.
US stock market data for AI agents: SEC filings, financials, insider trades, 13F, options, macro.
