现象
给 Agent 挂了 8 个工具后，出现两类问题：
- 模糊问题也会硬调工具
- 参数名对，但语义填错（把项目名塞进 query）
提示词加长也不稳。后来发现多数问题在工具定义本身。
工具名：短，但别歧义
from langchain.tools import tool
@tool
def search_notes(query: str) -> str:
"""Search personal tech notes by keyword.
Use only for questions about past experiment logs.
Do NOT use for general web search or live news.
"""
return f"notes about: {query}"要点：
- 名字说明「动作 + 对象」：
search_notes优于search - docstring 写清 何时用 和 何时不用
- 参数用
.describe()补语义（TS/部分模型更吃 schema 描述）
描述里要写负面约束
很多人只写正面说明。对 Agent 更有用的是：
Use when: ...
Do not use when: ...
Return format: ...因为模型判断「该不该调」时，负面样例往往比再堆参数说明更有效。
失败要可恢复，而不是炸整轮
@tool
def fetch_config(name: str) -> str:
"""Load a named config by exact id."""
try:
return load(name)
except FileNotFoundError:
return f"ERROR: config '{name}' not found. Try list_configs first."让错误信息告诉模型下一步，而不是抛异常终止。
我的检查清单
- 工具名是否自解释
- docstring 是否有 Use / Do not use
- 参数是否有语义描述
- 返回是否是模型好消化的字符串/结构
- 失败是否给出可行动提示
结论
工具不是越多越好。
少而准的工具 + 清晰边界，通常比 20 个模糊工具更稳。