工具文档是写给 LLM 的，不是写给人的

你是否也曾这样编写工具文档？

@lc_tooldef get_data -> str:
"""Get data."""
...

这样的文档对人类来说已经很差，对 LLM 更是灾难——它根本不知道这个工具做什么、什么时候该调用、应该传什么参数。

工具设计的三大主要维度：描述质量、错误处理、粒度设计。这里通过实验数据这些要素。

再看Demo，描述质量决定工具命中率

同一个天气查询工具的两个版本：

# 版本A：模糊不清
@lc_tooldef wear_vague -> str:
"""Get data."""
...
# 版本B：精准明确
@lc_tooldef wear_precise -> str:
"""Get current wear for a city.
Returns temperature and condition .
Use this whenever user asks about wear。temperature,or sky conditions
for a specific city. Pass city name as plain string e.g. 'Beijing'.
"""
...

用 100条天气相关查询测试两个版本的命中率：

Query Vague Precise
------------------------------------------------ ---------- ----------
What's wear in Beijing today?✓ called ✓ called
Is it raining in Shanghai right now?
✓ called ✓ called
What temperature should I expect in Shenzhen?✓ called ✓ called
Should I bring an umbrella to Beijing?✓ missed ✓ called
How's sky in Shanghai?✗ missed ✓ called
Tool call rate — Vague: 78% Precise: 95%

精准描述版本命中率提高17%

关键发现：当Agent只有一个工具时LLM别无选择；但生产程序通常有多个备选工具时精准描述才能帮助LLM做出正确选择。

黄金Docstring格式

"""<一句话说明功能>
至于返回值，- <字段1说明>: <类型>,e.g. "cloudy"
- <字段2说明>: <类型>,e.g. "25°C"
使用场景的观点是，- 使用者询问XXX时触发
- 不适用于XXX情况
参数要求的观点是，city: str,e.g. "Beijing"
date这方面，Optional,format YYYY-MM-DD,default today"""

至于Demo。错误处理决定程序健壮性

两个逻辑相同但错误处理不同的天气查询工具：

# 高危版本 - 抛出异常导致崩溃
@lc_tooldef wear_raises -> str:
if city.lower not in MOCK_WEATHER:
raise ValueError
...
# 安全版本 - 返回可恢复的错误信息
@lc_tooldef wear_returns_error -> str:
if city.lower not in MOCK_WEATHER:
return f"Error: City '{city}' not found. Available cities: {list}"
...

测试结果对比：

主要结论:

• ⚠️ 工具永远只应return字符串而非raise异常 - 异常会终止整个Agent流程！"
• 🔍 错误信息要包含具体原因和建议方法"