企业官网建设流程全解析

摘要

在 Claude Code、Cursor 等 AI 编码环境中通过 MCP 接入行情数据时，决定调用准确率的关键因素之一是工具描述和参数 schema 的质量。描述模糊、参数缺少约束、错误码未暴露，模型就容易选错工具或填入无效参数。本文以 TickDB 的 MCP 行情工具为设计参照，拆解description、inputSchema的编写原则，给出 MCP/REST/CLI 命名空间对照、好坏描述对比及发布前自检清单。配置片段仅供思路参考，部署前请以当前官方文档为准。

正文

1. 一个越来越常见的场景

你在 Claude Code 里说：

“帮我查一下贵州茅台和宁德时代的最新价，判断哪一个今天涨跌幅更大。”

模型开始思考，调用了一个叫get_current_price的工具，参数填了symbols=["茅台", "300750"]。结果一个无效，一个只返回了最新价却没有涨跌幅字段，模型又调了一次，来回三次才勉强拿到数据。

问题出在哪儿？不是 MCP 传输层有问题，也不是行情接口挂了，而是工具描述没有教会模型“怎么正确使用这个工具”。

本文聚焦被很多人忽略的一环：为行情工具编写高质量的description和参数 schema。安装步骤一笔带过，重心放在“描述什么、怎么描述、模型才会对”。

2. 先厘清命名空间：MCP / REST / CLI 各司其职

在 AI 编码环境中获取行情数据，有三条常见路径。混用概念会让模型选择错误的入口。

关键区分：MCP 工具调用不等于 REST 封装。MCP Server 内部可能对接 REST，但模型眼中它是一个带有明确 contract 的函数签名——只关心参数和返回值结构，不关心底层是 HTTP 还是 WebSocket。当 MCP 工具和 REST 脚本背后是同一数据源时，symbol 格式、字段名的统一会降低模型在两种模式间切换的出错率。

四类 MCP 行情工具的边界：设计工具描述前，先要明确不同工具各自能做什么。以 TickDB 的 MCP 服务（端点https://mcp.tickdb.ai/）为例，其行情工具分为四类，每类有严格的适用边界：

工具描述必须让模型能区分这四类工具。如果get_ticker的描述写得含糊，模型可能用它去查历史数据，反复调用直到超限。TickDB 的get_ticker、get_kline等工具已在统一代码仓https://github.com/TickDB/tickdb-unified-realtime-marketdata-api中提供 schema 定义，设计自己的 MCP 工具时可作为字段命名的参照。

3. 工具描述是重要防线

模型选择工具并调用的流程：

1. 读取工具列表（含name、description、inputSchema）
2. 根据用户意图匹配工具
3. 按照inputSchema的约束生成参数
4. 调用工具，解析返回，决定下一步

description 和 inputSchema 是影响第 2、3 步准确率的重要因素，但不能保证模型一定选对。模型的工具选择还受上下文、用户措辞、温度参数等多重变量影响。但一份精确的描述能显著降低选错和填错参数的概率。描述不够精确的常见后果：模型选错工具、填入非法参数、对返回字段产生幻觉。

核心原则：描述要明确“能做什么”和“不能做什么”。否定边界比泛泛的功能列表更有价值。

4. 参数 schema 的四个设计要点

inputSchema使用 JSON Schema 格式。以下四个要点对行情工具尤其关键：

① 枚举优于自由文本

参数只有少数合法值时，用enum约束。

"market":{"type":"string","enum":["A","HK","US"],"description":"市场代码：A 股为 A，港股为 HK，美股为 US"}

示意写法，enum 取值以官方文档为准，发布前复核。

② 示例值放在描述里

并非所有 MCP Client 都支持解析examples字段，最稳妥的做法是把示例直接写入description。

"symbols":{"type":"string","description":"品种代码列表，逗号分隔，格式为 CODE.EXCHANGE。示例：600519.SH,300750.SZ,700.HK,AAPL.US。数量上限以接口文档为准。"}

示意写法，参数类型和数量上限以官方文档为准，发布前复核。

③ 返回结构要在描述中预告

模型拿到返回结果前对数据结构一无所知。在工具描述中预告关键字段及其含义，能明显提升模型解读结果的准确率。

示例描述片段：
“返回data数组，每项含symbol、last_price（字符串，建议用 Decimal 处理）、timestamp（时间戳，具体精度以接口文档为准）等字段。”

④ 错误路径要提前约定

不要让模型从错误中自行归纳。描述中给出错误码含义和处理建议，模型遇到3001时知道等待而非连续重试。

5. 一个设计参照：TickDB 的 MCP 行情工具

以下不是完整可运行的配置文件，而是一份设计思路的参照，展示工具描述和参数 schema 可以到达的精确程度。

工具定义概览（示意写法，以官方文档和实测为准）：

• name：get_ticker
• description：
  “获取指定品种的实时行情快照。返回最新价、涨跌幅、成交量、最高/最低价等字段。仅限单次查询，不支持历史 K 线。交易时段和返回数据情况以各市场实际交易时间为准。”

参数 schema 要点：

• symbols：品种代码列表，格式CODE.EXCHANGE，示例["600519.SH","300750.SZ"]。分隔方式和数量限制以接口文档为准。
• 无interval、start_date等 K 线参数——向模型明确这是快照接口。

返回结构描述要点：

• 顶层code（0 成功）、data数组
• data[].last_price：字符串，调用方需转为高精度数值
• data[].timestamp：时间戳，具体精度以接口文档为准
• 错误码：1001Key 无效，3001限流需读Retry-After

⚠️ 以上字段和参数以 TickDB 当前 MCP 文档及代码仓https://github.com/TickDB/tickdb-unified-realtime-marketdata-api为准，发布前请用 MCP 工具实测复核。不同数据源的字段名和错误码体系存在差异，设计自己的工具时不要直接照搬。

TickDB 的设计思路是把 REST 层的字段命名与 MCP 工具的 schema 保持统一——这让开发者在对话和脚本两种模式间切换时，同一套 symbol 格式和字段名可以复用。对 Claude Code 用户来说，工具描述中约定的 symbol 格式和last_price类型提示，无论模型走 MCP 调用还是生成 REST 代码，都能保持一致。MCP 接入细节见docs.tickdb.ai。

📡 本文行情数据及 MCP 工具示例由 TickDB.ai 提供
⚠️ 本文为技术教程，不构成任何投资建议

互动：你在 Claude Code 或 Cursor 中接入 MCP 工具时，遇到过因为描述不清晰导致模型反复调用失败的情况吗？你是怎么排查出是 schema 的问题的？欢迎分享你的调试过程。

标签
Claude Code、Cursor、MCP、行情数据接入、TickDB、Python

参考文档

• https://docs.tickdb.ai（MCP 工具描述与字段文档）
• https://mcp.tickdb.ai/（TickDB MCP 端点）
• https://github.com/TickDB/tickdb-unified-realtime-marketdata-api（统一代码仓）