mcp-tool-design

该技能用于设计 MCP 工具的名称、描述与参数 schema，目标是让智能体第一次就正确调用工具，避免循环、选错工具或幻觉参数。适用场景：为 MCP 服务器新增工具、排查“模型从不选这个工具”或“选错工具”、审查新增工具的 PR、清理拥有 30 个以上工具的服务器。智能体按名称、描述、参数 schema 的顺序判断，三者都要强化。命名规则：<动词><对象>[<限定词>]，如下 search_issues、get_user_by_email、create_pr_comment、list_repos；若两个工具能回答同一查询，说明其中一个命名有误。描述约占 1-3 句，格式为“动词开头的动作 + 何时用/何时不用 + 注意事项”，其中“何时不用”用于消歧，收益最高。参数 schema：每个字段都要描述；封闭集合用 enum；常见可选值设默认；顶层优先用基本类型；避免自由格式 options 包。返回形状：先给摘要行，包含 ID 以便链式调用，主动截断并提示剩余数量，不要返回原始 HTML。工具总量超过约 15 个后选择准确率下降，需合并 CRUD 操作，但仅当子操作 schema 重合 80% 以上。反模式包括：万能工具 execute(query)、重复工具、隐藏必填参数、静默截断、跨服务器工具名冲突。上线前检查：命名是否动词开头且无歧义、是否有“何时不用”、参数是否都有描述、封闭集合是否用 enum、默认值是否覆盖常见情况、返回是否含 ID、是否摘要并截断、是否用 MCP Inspector 验证零样本可调用。建议先在一个真实对话中试用，再批量添加工具；用户反馈“不会用我的工具”时，先查描述，再查 schema，最后查名称；并记录无法解析的工具调用。