Claude Code / Cursor 接行情数据：为什么 MCP 工具的 description 不是注释
TickDB Research ·
摘要
给 Claude Code 或 Cursor 接了 MCP 行情工具，AI 却用历史 K 线接口去查当前价格，或者用实时快照接口去做历史回测——问题大概率不在模型能力，而在 MCP 工具的 description 写得太含糊。本文基于 MCP 官方规范、Claude Code 和 Cursor 的官方文档，以及一篇 2026 年 arXiv 论文，解释 MCP 工具描述为什么是 AI 选择工具时的重要路由信号，并给出一套行情场景下的工具描述编写方法和开发者自检清单。
一、AI 接了行情工具，却用错了接口
你给 Claude Code 或 Cursor 接了一个 MCP 行情服务，工具列表里有 get_ticker、get_kline、get_order_book、get_recent_trades。然后你提了一个很简单的需求：“帮我查一下贵州茅台现在的价格。”
AI 调用工具。返回了数据。价格看起来合理。
但你后来发现，它调的是 get_kline——历史 K 线接口，而不是 get_ticker——实时快照接口。它拿到的“最新价”其实是最近一根日 K 线的收盘价，不是此刻市场上的成交价。
这不是模型“选错了工具”，而是你的 MCP 工具描述没有告诉它这两个工具的区别。
MCP 工具 description 不是写给维护者看的注释，不是写给文档的摘要。它是写给 AI 的重要路由信号——AI 在决定调用哪个工具之前，会读取每个工具的 name 和 description，然后根据用户意图做匹配。如果两个工具的 description 都写“获取行情数据”，AI 选错工具的概率就会明显上升。description 能降低歧义，但不能保证模型一定选对工具；它是在多个相似工具之间帮模型做判断的关键信息，而不是唯一依据。
二、MCP 的三层结构：AI 客户端 → MCP Tool → 底层 API
在深入 description 写法之前，先理清三个层级的关系。这是很多开发者搞混的地方。
| 层级 | 是什么 | 举例 | 谁关心 |
|---|---|---|---|
| AI 客户端 | 用户的编程环境，通过 MCP 协议连接外部工具 | Claude Code、Cursor | 开发者 |
| MCP Tool | 暴露给 AI 的工具接口，包含 name、description、inputSchema | get_ticker、get_kline、get_order_book | AI 模型（通过 description 理解工具用途） |
| 底层 API | 实际执行数据查询的接口 | GET /v1/market/ticker、GET /v1/market/kline | MCP Server 开发者 |
关键认知：MCP Tool 的 description 是 AI 理解工具用途的重要路由信号。AI 无法直接看到底层 API 的实现代码和数据库 schema，它主要依靠 description 来判断这个工具是用来查实时行情还是查历史 K 线的。此外，Claude Code 等客户端还支持 tool search、server instructions 等机制，并非完全依赖单一 description 字段——但 description 仍是最直接、最基础的工具意图说明。
MCP 官方 Tools 规范定义了 Tool 对象的四个关键字段：name（工具标识）、description（人类可读的工具用途说明）、inputSchema（参数定义）和 annotations（工具属性标注，如只读、破坏性等）。其中 description 被定位为帮助模型理解工具用途的功能描述，它不会单独决定模型行为，但缺失或模糊时会显著增加选错工具的风险。
2026 年一篇 arXiv 论文（编号 2602.14878）专门研究了 MCP 工具描述对 Agent 工具选择的影响，结论指向两个要点：其一，描述质量会显著影响 Agent 选择工具的正确率和任务完成效果；其二，描述也不是越长越好——冗余信息反而可能让模型在多个工具之间犹豫。这个结论对行情场景尤为重要：行情工具通常数量多、功能相近，描述的精确性比描述的丰富性更关键。
三、行情场景下最容易混淆的四类工具
金融数据接口有天然的相似性：都需要品种代码作为输入，都返回价格相关字段，查询格式看起来都差不多。以下是 MCP 行情工具中最容易因描述含糊而被 AI 误选的四类工具：
| 工具 | 正确用途 | 关键字段 | 如果被误用于…… | 会出什么问题 |
|---|---|---|---|---|
get_ticker | 查询当前快照：最新成交价 | last_price | 历史回测 | 没有历史数据，回测样本完全错误 |
get_kline | 查询历史 K 线：OHLC | close | 查当前价 | 拿到的是最近一根 K 线的收盘价，不是实时价 |
get_order_book | 查询盘口深度：买卖档位 | bids/asks | 查当前价 | 拿不到 last_price，盘口最优价不等于最新成交价 |
get_recent_trades | 查询最近成交明细 | price/quantity/side/timestamp（每笔成交信息） | 查当前价 | 返回的是一个成交序列，不是单一价格快照 |
一个常见的排查场景：有位开发者用 Claude Code 接了一个 MCP 行情服务，想实现“股价突破某个阈值时提醒我”。他写了 prompt，AI 开始调工具。几天后他发现，AI 一直在调 get_kline，用的是每天收盘后的日 K 线来做判断——等“突破阈值”被检测到时，已经收盘好几个小时了。排查到最后，问题出在 get_ticker 的 description 写的是“获取股票市场数据”，get_kline 的 description 写的也是“获取股票 K 线数据”。两个描述都没有说明适用场景和不适用的场景。AI 选 get_kline 的逻辑很简单——用户要“监控价格变化”，K 线数据包含多个时间点的价格序列，看起来比 ticker 更适合做“监控”。
四、坏描述 vs 好描述
以下是四类行情工具的 description 对比。左侧是常见的“含糊写法”，右侧是本文推荐的“路由提示写法”。
| 工具 | 坏描述（含糊） | 好描述（路由提示） |
|---|---|---|
get_ticker | “获取市场数据” | “获取品种的实时快照（最新成交价 last_price、毫秒级 UTC 时间戳）。不要使用此工具获取历史 K 线数据——历史 K 线应使用 get_kline。不适用于盘口深度查询。” |
get_kline | “获取 K 线数据” | “获取品种的历史 K 线数据（OHLC，含 close 收盘价）。适用于回测和历史趋势分析。不要使用此工具查询当前实时价格——当前价格应使用 get_ticker。注意：此工具不提供 last_price 字段。” |
get_order_book | “获取深度数据” | “获取品种的盘口深度（买卖档位 bids/asks）。适用于流动性分析和挂单策略。不要使用此工具查询最新成交价——最新成交价应使用 get_ticker。盘口最优价不等于成交价。” |
get_recent_trades | “获取成交明细” | “获取品种的最近成交明细（每笔的 price、quantity、side、timestamp）。适用于微观结构分析和逐笔数据研究。不要使用此工具查询当前最新价——当前最新价应使用 get_ticker。此工具返回成交序列，不返回单一价格快照。” |
好描述的四个共同特征：
- 首句定义用途：第一句话就说清楚这个工具是干什么的，不铺垫，不迂回。
- 列出关键字段：明确写出返回数据里最重要的字段名，让 AI 知道这个工具能提供什么、不能提供什么。
- 写排他性声明：明确写“不要使用此工具做 X——X 应使用另一个工具 Y”。这是最关键的“路由逻辑”。
- 写清不适用的场景：如果不写“此工具不提供 X 字段”，AI 可能会默认这个工具能提供 X。
五、命名空间不可互推：REST endpoint ≠ MCP tool ≠ CLI command
另一个容易踩的坑，是把 REST endpoint、MCP tool 和 CLI command 三个命名空间里的名字混用。它们属于完全不同的协议层，命名逻辑和调用方式不同。
| 维度 | REST Endpoint | MCP Tool | CLI Command |
|---|---|---|---|
| 什么协议 | HTTP | MCP（JSON-RPC） | Shell |
| 谁调用 | 开发者 / HTTP Client | AI 客户端（Claude Code、Cursor 等） | 开发者 / 脚本 |
| 命名风格 | /v1/market/ticker | get_ticker | 需以当前 CLI help/实测为准 |
| 命名空间 | URL 路径 | MCP 工具注册表 | 终端命令 |
| 示例 | GET /v1/market/ticker?symbols=AAPL.US | get_ticker({"symbols": "AAPL.US"})（通用示意，非具体客户端调用格式） | 需以当前 CLI help/实测为准 |
核心规则：
- 不要把 MCP 工具名写成 REST endpoint：
get_ticker不是/v1/market/ticker - REST 的盘口端点
/v1/market/depth对应的是 MCP 工具get_order_book，不能从 REST endpoint 反推出 MCP 工具名叫get_depth - 不要在 CLI 帮助文档里写 MCP 工具名，反之亦然——三个命名空间各自独立
六、以 TickDB 为例：MCP 行情工具描述的建议写法
以下以 TickDB 的 MCP 服务作为示例场景，展示上述四个原则在行情工具描述中如何落地。选择它作为示例，是因为它的工具命名、字段定义和错误码设计提供了一套可参考的规范——你可以用同样的标准去衡量你自己的数据源。
TickDB 的 MCP 端点 https://mcp.tickdb.ai/ 向 AI 客户端暴露多个行情工具（名称如 get_ticker、get_kline、get_order_book、get_recent_trades 等），GitHub 入口为 https://github.com/TickDB/tickdb-unified-realtime-marketdata-api。
以下为建议的工具描述结构和写法示例，用于说明排他性声明和关键字段标注的原则如何应用到具体工具描述中（以官方文档和实际注册的 description 为准）：
统一命名与结构：建议工具名使用 get_ 前缀加业务语义命名（如 get_ticker 表示快照查询、get_order_book 表示盘口深度），不与 REST 端点路径 /v1/market/xxx 混用，确保调用方无需关心底层 HTTP 路径，只需理解工具名和描述语义。
工具描述含排他性声明：以 get_ticker 和 get_kline 为例，建议在 description 第一句就区分用途（如“获取品种实时快照” vs “获取品种历史 K 线”），末尾各自声明“不要使用此工具获取 X——X 应使用 get_YYY”。对比模糊写法（“获取市场数据”“获取 K 线数据”），排他性声明能帮 AI 在名称相似的工具之间做出更准确的判断。
关键字段显式标注：建议在每个工具的 description 中列出返回数据中的关键字段。例如 get_ticker 标注 last_price（最新成交价）和 timestamp（毫秒 UTC），get_kline 标注 close（收盘价）和 time（K 线时间戳），get_recent_trades 标注 price、quantity、side、timestamp。AI 可以根据这些字段名判断工具能提供什么数据、不能提供什么——如果 get_kline 的 description 里没有出现 last_price，AI 就不会默认它能返回最新成交价。
错误码语义统一：建议所有工具在 description 或配套文档中统一错误码含义——例如 3001 表示限流（应退避重试），1001 表示鉴权失败（应直接阻断）。AI 在处理工具调用失败时，可以根据错误码选择正确的处理策略，而不是盲目重试或直接放弃。不同错误码对应不同的处理路径，这个逻辑应该在工具描述层面就明确传达。
不同接入方式的字段路径有明确定义：如果你通过 REST 直接调用而不是通过 MCP，字段路径遵循 /v1/market/xxx 的文档约定——ticker 返回 data["data"] 数组，kline 返回 data["data"]["klines"] 数组。REST 路径和 MCP 工具名不互推，但对应同一底层 API 接口。
如果你在给其他数据源写 MCP 工具描述，可以用同样的四个原则去衡量：首句有没有定义用途？关键字段有没有列出？排他性声明有没有写？不适用场景有没有标注？
七、开发者自检清单：发布 MCP 工具前的 6 问
在把你的 MCP 行情工具交给 AI 之前，逐项核对这些内容：
| # | 检查项 | 能回答才发布 |
|---|---|---|
| 1 | 同类工具（ticker/kline/order_book/recent_trades）的 description 首句是否已区分用途？ | ✅ |
| 2 | 每个工具的 description 是否写了“不要使用此工具做 X”？ | ✅ |
| 3 | 关键字段（last_price、close、bids/asks、price/quantity/side）是否在 description 中列出？ | ✅ |
| 4 | 错误码（至少区分“限流”和“鉴权失败”）是否在 description 中说明？ | ✅ |
| 5 | MCP 工具名是否与 REST endpoint 路径保持独立命名，不互相反推？ | ✅ |
| 6 | 是否确认过 AI 客户端实际读取到的工具描述与预期一致？ | ✅ |
工具描述不是写给同事看的接口文档。它是在多个相似工具之间帮 AI 降低歧义的路由信号。
八、不能从本文推出什么
- 不能推出“只要 description 写好，AI 就绝不会选错工具”——工具选择受模型版本、上下文长度、用户 prompt 等多因素影响，description 能降低选错概率，但不是充分条件。
- 不能推出 Claude Code / Cursor 默认已接入 TickDB 或其他特定 MCP 服务——本文仅以 TickDB 作为 MCP 工具描述编写范本。
- 不能推出投资建议、自动交易策略或任何买卖信号。
- 不能替代 MCP Server 的完整安全审计——Cursor 文档提醒验证来源、权限、API Key 和审计代码；Claude Code 文档明确提到 prompt injection 风险。如自行配置 Claude Code 或 Cursor 的 MCP 连接，请以官方最新文档为准，本文不提供可直接复制使用的配置命令。
九、结尾
MCP 工具描述这件事，本质上是用自然语言写路由规则。你写下的每一个“不要使用此工具做 X”，都是替 AI 在选择工具时多放了一个路标。
你给 AI 接过 MCP 行情工具吗？它有没有因为 description 含糊而选错过接口？欢迎分享你的经历——这些“选错工具”的排查经验，比成功案例更能帮到后来的开发者。
本文主要参考来源
- MCP 官方 Tools 规范（Model Context Protocol – Tools specification）：定义 Tool 对象的 name / description / inputSchema / annotations。https://modelcontextprotocol.io/specification/2025-03-26/server/tools
- Claude Code 官方 MCP 文档：说明 Claude Code 可通过 MCP 连接外部工具，并明确提到 prompt injection 风险。https://docs.anthropic.com/en/docs/claude-code/mcp
- Cursor 官方 MCP 文档：说明 Cursor 可通过 MCP 连接外部工具和数据源，文档提醒验证来源、权限、API Key 和审计代码。https://docs.cursor.com/context/mcp
- arXiv 论文 2602.14878：研究 MCP 工具描述质量对 Agent 工具选择的影响，指出描述影响任务表现但并非越长越好。https://arxiv.org/abs/2602.14878
- TickDB GitHub 仓库：TickDB 统一实时行情 API 项目入口。https://github.com/TickDB/tickdb-unified-realtime-marketdata-api
- TickDB MCP 服务端点：
https://mcp.tickdb.ai/