MCP工具定义藏了3个坑，90%的AI项目踩过

一个MCP工具定义的好坏，直接决定你的AI是"懂行助手"还是"人工智障"。Conexor.io的实测数据显示：给参数加上具体描述和类型限制后，AI生成查询的准确率显著提升——幻觉列名少了，类型错配也少了。

但大多数团队把这当成"配置文件的边角料"。

命名陷阱：你的函数名在误导AI

来看这个反面教材：

`"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."`

现在AI明确了：用户问补丁状态、逾期更新、设备合规性时，才触发这个工具。命名要像资深工程师写的函数，一眼能看懂调用场景。

参数迷雾：让AI猜谜是最贵的错误

模糊参数是另一个重灾区：

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

什么query？SQL语句？自然语言？搜索字符串？AI只能靠猜，猜错就翻车。

对比这个版本：

`"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不用推理，直接执行。

万能工具病：一个函数干所有事

最常见的架构错误：做一个"query_type"参数内部分支的万能工具。

这相当于让同一个接口既查订单又改密码还发邮件——AI推理负担爆炸，出错时连哪条分支出问题都定位不了。

正确做法：拆成`get_active_devices`、`get_overdue_patches`、`get_device_by_id`。小而专的工具，AI好推理，失败也好排查。

Conexor.io的做法是从数据库Schema自动生成MCP定义。他们发现，当列级描述和具体参数类型到位后，查询准确率明显改善。

好的工具定义让AI像"懂你家系统的老员工"；差的定义让它像"第一天上班还在看手册的新人"。

差别几乎全在定义本身——而多数人把它当配置文件的边角料。