---

如何让AI真正用好你的工具：Claude Code

我们一直在用编写确定性系统的思维，来为非确定性系统设计工具。这种错位，是AI智能体用不好工具的根本原因。

一个让人困惑的现象

你是否遇到过这样的情况：

精心封装了一个天气查询API，告诉AI“输入城市名，返回天气信息”。结果AI问用户“您所在城市的邮编是多少？”——它自己把“城市名”理解成了“邮编”。

又或者，你给AI配置了通讯录搜索工具，它每次搜索都返回全部1000个联系人，然后在上下文中逐条“阅读”，消耗海量Token，速度慢得像蜗牛爬。

更常见的是，你把内部所有微服务都封装成了工具，兴致勃勃地交给AI，结果它要么在几十个工具之间反复横跳，要么干脆“忘记”了某些工具的存在。

这不是AI“笨”，而是我们的工具设计出了问题。

我们一直在用编写确定性系统（函数）的思维，来为非确定性系统（AI）设计“认知工具”。这种错位，才是问题的根源。

在构建Claude Code的过程中，Anthropic团队经历了从“写工具”到“为AI设计认知延伸”的范式转变。这篇文章，就是他们的实战复盘。

为AI写工具，和传统编程有什么区别？

先看一个例子。

传统编程中，你写一个 get_all_contacts() 函数，返回所有联系人。程序遍历列表，逐个处理，毫无压力——计算机内存廉价，CPU循环高效。

但如果AI智能体调用同样的工具，返回1000个联系人，它需要逐Token阅读每一个人名、邮箱、电话。这不仅消耗宝贵的上下文窗口，还让AI在无关信息中“游泳”，难以聚焦真正相关的联系人。

对计算机来说廉价的操作，对AI来说可能是沉重的认知负担。

这意味着：为AI设计工具，本质是在设计它的认知延伸——工具决定了AI能“看到”什么、如何“思考”、怎样“行动”。好的工具扩展AI的能力边界，差的工具则成为AI的认知枷锁。

基于这个认知，Anthropic团队摸索出了一套方法论。

三步迭代法：从原型到精良工具

第一步：快速搭建原型

别在会议室里反复推敲工具设计。先做一个能用的版本，放到真实场景中测试。

如果你用Claude Code来编写工具，记得把相关SDK和API的文档提供给Claude。Anthropic官方推荐在文档网站提供 llms.txt 文件（例如他们的API文档就有），方便AI直接读取。

将工具封装到本地MCP服务器或桌面扩展（DXT）中，在Claude Code或Claude Desktop里实际跑一跑。亲自测试，找到那些“看起来没问题但AI就是用不好”的粗糙之处。

关键洞察：很多设计缺陷只有在AI真正调用时才会暴露。纸上谈兵发现不了问题。

第二步：运行评估，用数据说话

这是整个方法论中最有价值的环节。

生成评估任务： 让Claude Code基于你的工具快速生成数十个“提示词-响应对”。提示词必须基于真实使用场景和真实数据——内部知识库、真实客户记录、实际业务逻辑。避免使用过于简单的“沙盒”环境，那会让工具在虚假的舒适区里看起来很完美，一上战场就垮掉。

高质量的评估任务通常需要多次工具调用。比如：

“客户ID 9182报告说他们在一次购买尝试中被扣了三次款。查找所有相关日志条目，确定是否有其他客户受到同样问题的影响。”

运行评估： 通过直接调用LLM API以编程方式运行。在系统提示词中，要求AI不仅输出结构化响应块（用于验证），还要输出推理和反馈块——这能触发思维链行为，让你看到AI“为什么这么想”。

除了准确率，还要追踪：工具调用总次数、总Token消耗量、工具错误数、任务运行时间。这些指标会告诉你很多故事。

分析结果： 这是最有趣的部分。观察你的AI在哪里卡壳、困惑、犯错。

• 大量冗余的工具调用 → 分页或Token限制参数需要调整
• 大量无效参数错误 → 工具描述需要更清晰，或需要更好的示例
• AI不断跳过某个工具 → 该工具可能根本没有存在的必要

把评估日志直接喂给Claude Code，让它帮你分析问题并提出改进方案。 这就是“人机协作迭代”的闭环。

第三步：与AI协作迭代

将评估智能体的记录拼接起来，粘贴到Claude Code中。Claude擅长分析记录和一次性重构大量工具。

Anthropic团队发现，这种协作方式甚至能超越“专家级”工具实现——无论是研究人员手动编写的工具，还是Claude自己生成的工具，在反复迭代后都能获得额外性能提升。

核心循环是：人类设定目标 → AI执行评估 → AI分析结果 → 人类指导改进 → 新一轮评估。

黄金设计法则

法则一：克制是美德，不要提供所有工具

最常见的错误：把现有软件功能或API端点不加选择地全部封装成工具。

对AI来说，更多工具并不等于更好。

以通讯录场景为例：与其实现 list_all_contacts（返回所有人），不如实现 search_contacts（按关键词搜索）和 message_contact（发消息给指定联系人）。后者让AI像人类一样“先搜索再操作”，而不是“先暴力读取再大海捞针”。

整合那些高频串联的操作：

❌ 多个分散的工具	✅ 一个整合的工具
list_users + list_events + create_event	schedule_event（自动查找空闲时间并安排）
read_logs（全部日志）	search_logs（只返回相关行+上下文）
get_customer + list_transactions + list_notes	get_customer_context（一次性汇总所有资讯）

确保每个工具都有清晰、明确、不可替代的目的。功能重叠的工具会让AI选择困难，最终影响任务完成率。

法则二：命名即引导，划定边界

AI智能体可能同时访问几十个MCP服务器和数百个工具。当工具功能相似时，AI会混淆该用哪一个。

用命名空间来划定边界： 按服务划分（asana_search vs jira_search），再按资源细分（asana_projects_search vs asana_users_search）。

有趣的是，选择前缀式还是后缀式的命名方式，对工具使用评估有不可忽视的影响。 不同LLM的反应不同，建议通过你的评估数据来决定哪种更有效。

核心原则：工具名称应反映任务的自然细分方式。 好的命名帮助AI在正确的时间选择正确的工具。

法则三：返回上下文，而非数据

工具应该返回高价值信息，而不是“原始数据”。

低级技术标识符（UUID、ID、MIME类型）对AI的决策帮助有限。 相反，语义化的名称和描述能直接为AI的下一步行动提供信息。

Anthropic团队发现：仅仅将任意字母数字UUID解析为更有语义意义的名称，就能显著提高Claude在检索任务中的精确度。

举个例子：

❌ 返回一堆ID	✅ 返回有意义的上下文
{"user_id": "a3f9k2", "dept_id": "d7e1"}	{"name": "张三", "department": "技术部"}

但也要注意灵活性：AI可能需要技术ID来触发后续工具调用（比如搜索到 name='张三' 后，需要 user_id 来发送消息）。

解决方案： 在工具中暴露一个 response_format 枚举参数，让AI自主控制返回“详细版”还是“简洁版”。类似GraphQL的设计，让AI按需获取信息。

法则四：Token效率是隐形天花板

对可能消耗大量上下文的工具响应，务必实施分页、过滤、截断的组合策略，并设置合理的默认值。

Claude Code默认将工具响应限制为25,000个Token。即使上下文窗口在增长，对上下文高效工具的需求将持续存在。

截断时要有“引导”： 不要生硬切断，而是用清晰的提示告诉AI“响应已被截断，建议缩小搜索范围重试”。

错误信息也要设计：

❌ 无用的错误	✅ 有用的错误
Error Code: 500 - Internal Server Error	搜索返回了5000条结果，超过限制。建议：添加更具体的关键词或缩小日期范围后重试。

把晦涩的堆栈跟踪变成可操作的建议，让AI知道下一步该怎么做。

法则五：工具描述需要提示词工程

这是提升工具使用准确率性价比最高的方式。

工具描述会被加载到AI的上下文中，它们共同构成了AI对工具的“认知地图”。写工具描述时，想象你在向新员工介绍这个工具——那些你以为“不言而喻”的上下文，都要明确写出来。

好的描述应该包含：

• 明确的输入格式：参数名要自解释（用 user_id，而不是 user）
• 边界情况说明：什么时候工具不能用，返回什么
• 使用场景提示：什么情况下应该调用这个工具
• 示例参数：直接展示正确用法

Anthropic的Claude Sonnet 3.5在SWE-bench Verified上达到最先进性能的突破，正是源于对工具描述的精确改进——大幅降低了错误率，提高了任务完成率。

微小的描述改进，可能带来质的飞跃。

结语：从程序员到认知架构师

回顾整个方法论，一条主线贯穿始终：

为AI设计工具，不是技术问题，而是认知问题。

我们不再是在“写代码”，而是在设计AI智能体的认知延伸。好的工具扩展了AI能够有效解决问题的范围，差的工具则成为AI的枷锁。

这套方法论的核心是评估驱动——不靠直觉和猜测，而是用真实数据和系统化评估来迭代改进。在这个循环中，AI不仅是工具的使用者，更是工具设计的协作者。

未来，无论MCP协议如何演进，LLM本身如何升级，系统化的、评估驱动的方法论将持续有效。当我们把角色从“程序员”转变为“认知架构师”，为AI设计工具这件事，就会变得清晰而有力。

而这一切的起点，就是放下“函数思维”，开始追问一个更根本的问题：

“这个工具，是在帮助AI思考，还是在阻碍它思考？”

本文内容基于 Anthropic官方工程博客，结合作者在Claude Code源码学习中的实践心得整理而成。