AI PRO·Context Day 5 工具描述与动态组装：让AI正确使用工具

![配图待生成]

一句话总结

工具描述 = AI的”使用说明书”，写得好不好，直接决定AI能不能正确使用工具。

工具是AI的”手”，但AI需要先”看懂说明书”才能动手。

---

为什么工具描述很重要？

想象一下，你给实习生一个工具箱：

• 工具没有标签 → 实习生不知道这是什么
• 标签写得模糊 → 实习生可能用错工具
• 没有使用说明 → 实习生不知道什么时候该用

AI也是一样：

工具描述不清的后果

问题	后果

|——|——|

描述模糊	AI选错工具
参数不明	AI传错参数
使用时机不清	AI在不该用时用了
缺少示例	AI不知道怎么调用

---

工具描述的结构

一个完整的工具描述应该包含：

`json

{

“name”: “search_files”,

“description”: “在指定目录中搜索文件内容，支持正则表达式”,

“parameters”: {

“query”: {

“type”: “string”,

“description”: “搜索关键词或正则表达式”,

“required”: true

},

“path”: {

“type”: “string”,

“description”: “搜索目录，默认当前工作目录”,

“default”: “.”

},

“file_glob”: {

“type”: “string”,

“description”: “文件名过滤，如 ‘*.py’”,

“optional”: true

}

},

“when_to_use”: “需要查找文件内容、定位代码位置时”,

“when_not_to_use”: “需要读取完整文件内容时，应使用read_file”,

“examples”: [

{

“description”: “搜索Python文件中的函数定义”,

“call”: “search_files(query=’def ‘, file_glob=’*.py’)”

}

]

}

`

---

工具名称设计

好的命名

名称	说明

|——|——|

search_files	搜索文件
read_file	读取文件
write_file	写入文件
create_document	创建文档
delete_item	删除项目

坏的命名

名称	问题

|——|——|

do_stuff	太模糊
handle_files	不知道具体做什么
process	太泛
util	工具箱？工具？

命名原则

1. 动词+名词：清晰表达功能
2. 一致的命名风格：全用snake_case或camelCase
3. 避免歧义：search_files vs find_files，选一个
4. 长度适中：太短不清晰，太长浪费token

---

描述的写法

好的描述

`

“description”: “在指定目录中搜索文件内容，支持正则表达式匹配”

`

• ✅ 一句话说明功能
• ✅ 说明支持的特性
• ✅ 清晰无歧义

坏的描述

`

“description”: “搜索”

`

• ❌ 太简短
• ❌ 不知道搜什么
• ❌ 不知道支持什么

`

“description”: “这是一个非常强大的搜索工具，可以搜索各种文件，支持多种格式，速度很快，功能很多…”

`

• ❌ 太冗长
• ❌ 浪费token
• ❌ 重点不突出

描述原则

1. 一句话：用一句话说清楚功能
2. 关键词：包含核心功能的关键词
3. 特性：说明支持的特殊特性
4. 长度：20-50个字最佳

---

参数说明

必须说明的内容

字段	说明	示例

|——|——|——|

type	参数类型	string, number, boolean, array, object
description	参数含义	“搜索关键词”
required	是否必须	true/false
default	默认值	“.”
enum	可选值	[“asc”, “desc”]

示例

`json

{

“query”: {

“type”: “string”,

“description”: “搜索关键词或正则表达式”,

“required”: true

},

“limit”: {

“type”: “number”,

“description”: “返回结果数量”,

“default”: 10,

“min”: 1,

“max”: 100

}

}

`

---

使用时机说明

为什么需要？

AI可能在不该用的时候用了工具，或者该用的时候没用。

示例

`json

{

“when_to_use”: “需要查找文件内容、定位代码位置时”,

“when_not_to_use”: “需要读取完整文件内容时，应使用read_file”

}

`

常见场景

工具	when_to_use	when_not_to_use

|——|————-|—————–|

search_files	查找文件内容	读取完整文件
read_file	读取完整文件	只需要搜索
write_file	创建/覆盖文件	修改文件片段
patch	修改文件片段	创建新文件

---

提供示例

为什么需要示例？

• 文字描述可能有歧义
• 示例最直观
• 减少AI试错

示例格式

`json

{

“examples”: [

{

“description”: “搜索Python文件中的函数定义”,

“call”: “search_files(query=’def ‘, file_glob=’*.py’)”

},

{

“description”: “在指定目录搜索”,

“call”: “search_files(query=’error’, path=’/var/log’)”

}

]

}

`

示例原则

1. 1-3个：不要太多，浪费token
2. 典型场景：覆盖最常见的用法
3. 多样化：展示不同参数组合
4. 简洁：不要写太长

---

动态上下文组装

什么是动态组装？

根据当前任务，动态选择需要加载的工具和上下文。

为什么需要？

• 工具太多，全部加载浪费token
• 不同任务需要不同的工具
• 需要根据情况调整上下文

策略

1. 按任务类型

`python

task_tools = {

“coding”: [“read_file”, “write_file”, “search_files”, “terminal”],

“writing”: [“search_files”, “browser_navigate”, “browser_snapshot”],

“research”: [“web_search”, “browser_navigate”, “read_file”]

}

`

2. 按用户意图

`python

if “写文章” in user_message:

load_tools([“search_files”, “browser_navigate”])

load_skills([“wechat-article-publisher”])

elif “调试代码” in user_message:

load_tools([“terminal”, “read_file”, “search_files”])

load_skills([“debugging”])

`

3. 按上下文窗口

`python

remaining_tokens = max_tokens – used_tokens

if remaining_tokens < 5000:

# 只加载必要的工具

load_tools([“read_file”, “terminal”])

else:

# 加载更多工具

load_tools(all_tools)

`

---

Token预算管理

什么是Token预算？

上下文窗口是有限的，需要为每个组件分配token预算。

预算分配示例

组件	Token预算	占比

|——|———–|——|

System Prompt	2,000	5%
RAG结果	15,000	37%
Tool描述	5,000	12%
Memory	8,000	20%
对话历史	8,000	20%
留给输出	2,000	5%
总计	40,000	100%

超限处理

当某个组件超出预算时：

1. 截断：保留前面的内容
2. 压缩：用摘要替代原文
3. 优先级：保留重要的，删除次要的
4. 动态调整：根据任务调整预算

---

🚇 地铁深读：工具描述的进化

早期：纯文本描述

`

search_files: 搜索文件

`

中期：JSON Schema

`json

{

“name”: “search_files”,

“description”: “搜索文件”,

“parameters”: {

“query”: {“type”: “string”}

}

}

`

现在：增强描述

`json

{

“name”: “search_files”,

“description”: “搜索文件”,

“when_to_use”: “…”,

“when_not_to_use”: “…”,

“examples”: […]

}

`

未来：自适应描述

AI自己决定需要什么工具，自动检索工具描述：

`

用户问题 → AI分析需要什么能力 → 检索相关工具 → 动态加载描述

`

---

今日小结

要素	作用	最佳实践

|——|——|———-|

名称	标识工具	动词+名词，一致风格
描述	说明功能	一句话，20-50字
参数	使用细节	类型、描述、默认值
使用时机	何时该用	when_to_use + when_not_to_use
示例	怎么用	1-3个典型场景

一句话记住： 工具描述是AI的”使用说明书”，写清楚了AI才能正确使用。

---

下期预告

AI PRO·Context Day 6 实战：构建完整的Context Engineering系统

我们将从零搭建一个完整的上下文工程系统，把前面学到的所有知识整合起来。

---

*攀岩者 | 技术总监 | 19年IT全栈实战*

*每天分享AI学习笔记，陪你从零基础到AI达人*