MCP工具定义踩坑：1个好命名能让AI准确率翻倍

去年有个团队跟我吐槽，他们的AI助手总把"查询未支付订单"和"查询退款记录"搞混。排查了三个月模型参数，最后发现问题出在工具命名上——两个函数都叫get_order_data。

这就是MCP（模型上下文协议，Model Context Protocol）工具定义的典型陷阱。理论上你只需定义函数、描述功能，AI会在需要时调用。但实践中，工具定义的质量直接决定AI是"懂行助手"还是"瞎猜笨蛋"。

命名灾难：当AI面对12个"get_data"

来看一个真实存在的反面教材：

{ "name": "get_data", "description": "Gets data from the system" }

每个工具都"获取数据"。AI怎么判断该调这个还是别的？这就像让实习生去档案室找文件，却只说"拿份资料"——他得猜你要的是合同、发票还是考勤表。

对比这个改写版本：

{ "name": "get_overdue_device_patches", "description": "Returns a list of devices that have not received a security patch in the specified number of days. Defaults to 30 days if not specified." }

动词（get）+ 名词（overdue device patches）+ 上下文（未打补丁的设备）。AI现在明确知道：用户问补丁状态、逾期更新、设备合规性时，该调这个。

Conexor.io的工程师有个简单法则：命名要像资深工程师写的函数。不是写给机器看的，是写给六个月后的自己——以及此刻的AI——看的。

参数迷雾：AI不该猜你的"query"是什么

参数描述是第二个重灾区。看这个：

{ "parameters": { "query": { "type": "string", "description": "The query" } } }

什么query？SQL语句？自然语言？搜索关键词？AI只能赌一把。赌错的代价是报错、幻觉、或者更糟——用错误参数执行了正确函数，结果悄无声息地返回垃圾数据。

正确的打开方式：

{ "parameters": { "days_since_last_patch": { "type": "integer", "description": "Number of days since last patch. Returns devices that haven't been patched within this window. Default: 30", "default": 30 }, "os_filter": { "type": "string", "description": "Optional: filter by OS type ('windows', 'macos', 'linux'). Omit to include all.", "required": false } } }

类型明确、描述具体、默认值标注、可选参数说明省略规则。AI不需要"理解"你的业务，它只需要知道该传什么。

这里有个反直觉的点：参数越"啰嗦"，AI表现越聪明。因为大模型的上下文窗口足够大，多几行描述不会拖慢速度，但少一行就可能导致一次错误调用。

瑞士军刀陷阱：一个工具干五件事，等于五个工具都干不好

最常见的架构错误是"万能工具"——一个函数接收query_type参数，内部再分支处理。看起来像减少代码量，实则给AI出阅读理解题。

拆成三个独立工具：get_active_devices、get_overdue_patches、get_device_by_id。每个只做一件事，但做得明明白白。

好处不只是AI更容易理解。小工具失败得更优雅——get_device_by_id找不到设备时，你知道是ID问题；万能工具报错时，你得排查是查询类型错了、参数格式错了、还是权限问题。

Conexor.io的实践数据很能说明问题。他们从数据库Schema自动生成MCP工具定义，初期只做了表级描述，AI生成的查询经常幻觉列名、搞错类型。

加上列级描述和具体参数类型后，查询准确率显著提升——幻觉列名减少，类型错配消失。工具定义质量从"事后优化项"变成了"一级关注点"。

最后一点：好工具让AI"懂"你的系统

回到开头那个踩坑团队。他们把函数改名成get_unpaid_orders和get_refund_records，加了参数描述，两周后混淆率降到接近零。

没有换模型，没有调温度参数，没有搞RAG。只是把工具定义写清楚了。

这像什么？像你给新来的产品经理写需求文档。写得模糊，他来回确认十遍还做错；写得具体，他第一次就能交付可用版本。AI就是那个产品经理——智商在线，但对你的业务一无所知。

Conexor.io的工程师说，他们现在评审MCP工具定义和评审API文档一样严格。因为最终用户不会抱怨"工具定义写得烂"，只会说"你们AI不好用"。

你的MCP工具库里，有没有藏着几个get_data？