Agent 开发如何设计工具的描述与输入输出契约？

1. 工具描述：性能的关键单一因素

工具描述是影响工具调用性能最重要的单一因素。描述应当说明：这个工具做什么、什么情况下该用、什么情况下不该用、每个参数的含义及其如何影响工具行为、以及重要限制（例如工具不返回什么信息）。Anthropic 建议非复杂工具的描述也至少写 3~4 句，复杂工具则应更长。

2. 输入契约与示例

输入契约使用 JSON Schema 表达。对于嵌套对象、可选参数众多、或对格式敏感的工具，仅靠 Schema 不足以让模型正确调用，此时应补充示例输入（Anthropic 的 Tool Use Examples）——Anthropic 内部测试显示，示例可将复杂参数处理的准确率从 72% 提升至 90%。由于示例会增加 Token 开销，这一手段应按需使用而非全量铺开。

3. 输出契约的高信号原则

输出契约的设计目标是"只返回高信号信息"：返回语义化、稳定的标识符而非不透明内部引用，只包含模型推理下一步所需字段，避免臃肿返回体挤占上下文。

4. 减少工具数量与选择歧义

减少工具数量与选择歧义同样关键：将相关操作合并为单一带动作参数的工具，而非为每个动作各建一个；工具跨多服务时用服务名前缀做命名空间（如 github_list_prs、slack_send_message），使选择无歧义，尤其在启用工具搜索时更为必要。此外，工具数量本身存在上限约束，业界普遍建议将活跃工具控制在个位数到十余个以内（Anthropic 亦主张 fewer, more capable tools），过多会降低选择准确率。