MCP server 最常见的失败不是技术问题,是"给了十个工具,模型一个都不爱用"。原因是描述含糊、返回太大、或者工具之间职责重叠。
约束一:工具数量控制在 3–5 个
每个工具的描述都会占上下文。十个工具的 server,光描述就能吃掉几千 token,而且模型要在里面做选择——选择成本比执行成本高。
一个知识库 server,三个工具就够:检索、读取、列目录。
约束二:描述写"什么时候用",不写"它是什么"
差:search_notes: 搜索笔记 好:search_notes: 按关键词检索本地笔记的标题与正文;当用户问"我以前记过什么"或需要引用自己的旧笔记时使用
差别在于后者告诉模型触发条件。
约束三:返回要小、要带定位
返回整篇文章会烧上下文。返回"前 3 条命中 + 每条的片段 + 行号"才是可用形态:
{
"hits": [
{"path": "70-服务器/3x-ui.md", "line": 12, "snippet": "…salamander…"}
]
}
有了行号,模型可以二次读取精确区间,而不是整篇吞进去。
约束四:错误信息要能指导下一步
差:{"error": "failed"} 好:{"error": "file not found", "hint": "用 list_tree 确认路径;注意排除 98-剪报 目录"}
模型不会猜,它只会照着提示做。错误信息写得具体,等于把排障知识前置到了工具层。
一个反例
我第一版写了七个工具(搜索、标签、日期范围、统计、导出…),结果模型几乎只用搜索。删到三个之后,使用率反而上升。
工具不是越多越好,是越准越好。
再加一条:不要做"万能工具"
run_shell(command) 这类工具看起来很强大,实际是灾难:模型会把复杂逻辑塞进一条命令里,出错时你无法从返回值判断哪一步错了。
正确做法是拆成有语义的工具:list_files、read_file、search_text。每个工具只做一件事,返回值结构固定,模型才学得会。
参数的写法
参数名要能自解释:q 不如 keyword,p 不如 path。类型尽量用枚举而不是自由字符串——format: "json"|"text" 比 format: string 少一半误用。
版本与兼容
工具描述改动会影响模型行为,等同于改接口。加工具可以,改已有工具的参数名要谨慎——最好新增一个工具,旧的标记 deprecated,跑一段时间再删。
一句总结
MCP server 的成败不在协议实现,在工具描述写得像不像给新人看的说明书。
一个真实案例
把"读数据库"做成一个 query(sql) 工具,模型很快就开始拼复杂 join,出错时只拿到"语法错误"。改成 list_tables、describe_table、sample_rows(table, limit) 三个工具后,模型反而能自己一步步查对——因为每一步都有确定返回值。
结论很直白:工具的粒度决定模型的成功率,不是模型不够聪明。
最后一个实践:先本地、再远程
本地 stdio 版本调试成本最低——日志直接打在终端里,改一行立刻重启。等工具语义稳定了,再包成远程 HTTP 服务,加上鉴权和限流。顺序反了,你会在排查网络问题里耗掉大部分时间。