Claude Code / Cursor 接行情数据：为什么 MCP 工具的 description 不是注释

摘要

给 Claude Code 或 Cursor 接了 MCP 行情工具，AI 却用历史 K 线接口去查当前价格，或者用实时快照接口去做历史回测——问题大概率不在模型能力，而在 MCP 工具的 description 写得太含糊。本文基于 MCP 官方规范、Claude Code 和 Cursor 的官方文档，以及一篇 2026 年 arXiv 论文，解释 MCP 工具描述为什么是 AI 选择工具时的重要路由信号，并给出一套行情场景下的工具描述编写方法和开发者自检清单。

!image.png

一、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

!image.png

在深入 description 写法之前，先理清三个层级的关系。这是很多开发者搞混的地方。

关键认知：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 误选的四类工具：

!image.png

一个常见的排查场景：有位开发者用 Claude Code 接了一个 MCP 行情服务，想实现“股价突破某个阈值时提醒我”。他写了 prompt，AI 开始调工具。几天后他发现，AI 一直在调 get_kline，用的是每天收盘后的日 K 线来做判断——等“突破阈值”被检测到时，已经收盘好几个小时了。排查到最后，问题出在 get_ticker 的 description 写的是“获取股票市场数据”，get_kline 的 description 写的也是“获取股票 K 线数据”。两个描述都没有说明适用场景和不适用的场景。AI 选 get_kline 的逻辑很简单——用户要“监控价格变化”，K 线数据包含多个时间点的价格序列，看起来比 ticker 更适合做“监控”。

四、坏描述 vs 好描述

以下是四类行情工具的 description 对比。左侧是常见的“含糊写法”，右侧是本文推荐的“路由提示写法”。

!image.png

好描述的四个共同特征：

1. 首句定义用途：第一句话就说清楚这个工具是干什么的，不铺垫，不迂回。
2. 列出关键字段：明确写出返回数据里最重要的字段名，让 AI 知道这个工具能提供什么、不能提供什么。
3. 写排他性声明：明确写“不要使用此工具做 X——X 应使用另一个工具 Y”。这是最关键的“路由逻辑”。
4. 写清不适用的场景：如果不写“此工具不提供 X 字段”，AI 可能会默认这个工具能提供 X。

五、命名空间不可互推：REST endpoint ≠ MCP tool ≠ CLI command

!image.png

另一个容易踩的坑，是把 REST endpoint、MCP tool 和 CLI command 三个命名空间里的名字混用。它们属于完全不同的协议层，命名逻辑和调用方式不同。

核心规则：

• 不要把 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 问

!image.png

在把你的 MCP 行情工具交给 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 含糊而选错过接口？欢迎分享你的经历——这些“选错工具”的排查经验，比成功案例更能帮到后来的开发者。

本文主要参考来源

1. MCP 官方 Tools 规范（Model Context Protocol – Tools specification）：定义 Tool 对象的 name / description / inputSchema / annotations。https://modelcontextprotocol.io/specification/2025-03-26/server/tools
2. Claude Code 官方 MCP 文档：说明 Claude Code 可通过 MCP 连接外部工具，并明确提到 prompt injection 风险。https://docs.anthropic.com/en/docs/claude-code/mcp
3. Cursor 官方 MCP 文档：说明 Cursor 可通过 MCP 连接外部工具和数据源，文档提醒验证来源、权限、API Key 和审计代码。https://docs.cursor.com/context/mcp
4. arXiv 论文 2602.14878：研究 MCP 工具描述质量对 Agent 工具选择的影响，指出描述影响任务表现但并非越长越好。https://arxiv.org/abs/2602.14878
5. TickDB GitHub 仓库：TickDB 统一实时行情 API 项目入口。https://github.com/TickDB/tickdb-unified-realtime-marketdata-api
6. TickDB MCP 服务端点：https://mcp.tickdb.ai/

通过 TickDB API 获取实时行情数据

一个 API 接入外汇、加密货币、美股、港股、A股、贵金属和全球指数的实时行情。支持 WebSocket 低延迟推送，免费开始使用。