[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Function Schema, Tool Selection

Tool Description

一句话定义

Tool Description 是给 LLM 看的工具用途说明。描述应明确用途、输入、输出和限制；是否改善选择准确率需用实际任务验证。

核心原理

好的描述 vs 差的描述

差: "查询数据"
好: "查询指定时间范围内的销售数据，返回每日销售额和订单数"

差: "搜索"
好: "在知识库中搜索与查询相关的文档片段，返回最相关的 top-k 结果"

差: "发送邮件"
好: "向指定收件人发送邮件。需要提供收件人、主题和正文。发送前请确认内容"

描述的组成

tool = {
    "name": "query_sales_data",
    "description": "查询指定时间范围内的销售数据。返回每日销售额和订单数。"
                   "用于回答关于销售趋势的问题。"
                   "参数 start_date 和 end_date 格式为 YYYY-MM-DD。",
    "parameters": {
        "type": "object",
        "properties": {
            "start_date": {"type": "string", "format": "date"},
            "end_date": {"type": "string", "format": "date"},
        },
        "required": ["start_date", "end_date"],
        "additionalProperties": False,
    }
}

描述中应该包含什么

要素	例子	重要性
用途	”查询销售数据”	必须
返回值	”返回每日销售额”	推荐
使用场景	”用于分析销售趋势”	推荐
参数说明	”格式为 YYYY-MM-DD”	推荐
限制	”最多返回 30 天数据”	可选

描述中的“确认后发送”只是说明，运行时仍需落实授权；日期格式、先后顺序和范围也需要实际校验，不能仅靠自然语言约束。

常见坑

1. 描述太短: “查询”两个字
2. 描述冗余: 删除重复说明，但没有通用的 500 字上限；关键约束不能为了短而省略
3. 不说明返回值: LLM 不知道工具会返回什么
4. 描述和实际不符: 描述说返回列表但实际返回字典

参考资料

• Building Effective Agents - Anthropic
• Function Schema