findscripter 何时使用
工具是 Agent 与世界交互的主要通道，是确定性系统与非确定性 Agent 之间的「契约」。与面向开发者的传统 API 不同，工具 API 是写给语言模型看的——模型要从自然语言意图里推断该调哪个工具、填什么参数。描述写得差，再多 prompt 工程也救不回来。
该用：
- 为 Agent 系统新建工具，或从零设计工具 API
- 排查工具相关的失败 / 误用
- 优化既有工具集以提升 Agent 表现
- 评估第三方工具能否接入 Agent
- 在代码库里统一工具命名 / 返回字段约定
不该用（负边界）：
- 给人类开发者写的普通 SDK / REST 文档——人能读契约、会主动纠错，约束没这么强
- 与 Agent 调用无关的纯后端接口设计
- 底层数据脏乱、文档缺失时，别急着做「架构精简」（见下）
步骤
- 梳理工作流：列出 Agent 真正要完成的独立工作流，而非现有函数。
- 整合工具：把同一工作流的相关动作合并成单个综合工具（见整合原则）。
- 写好描述：每个工具回答四问——做什么 / 何时用 / 收什么入参 / 返回什么。
- 定默认值与返回格式：默认值贴合常见场景；提供 concise / detailed 两档输出控制 token。
- 设计可恢复错误：错误信息要告诉 Agent「错在哪、怎么改」。
- 统一约定：动词-名词命名，跨工具复用同名参数与返回字段。
- 控制规模：多数应用 10-20 个工具，超出就用命名空间分组。
- 用真实 Agent 请求测试，并按观察到的失败模式迭代。
指令
整合原则（核心）：如果一个人类工程师都说不清某场景下该用哪个工具，就别指望 Agent 能做对。优先用单个综合工具覆盖整条工作流，而非让 Agent 串联多个窄工具。
- 反例：
list_users+list_events+create_event - 正例：
schedule_event（内部查可用时段并完成排期） - 但不要硬整合：行为根本不同、用在不同上下文、可能被独立调用的工具，应保持分离。
架构精简（整合的极致）：把大量专用工具换成一个通用原语。典型是「文件系统 Agent 模式」——只给一个命令执行工具，让 Agent 用 grep cat find ls 自由探索。
- 适用：数据层文档完善且结构一致；模型推理能力够；你的专用工具是在「束缚」而非「赋能」模型。
- 失败：底层数据脏乱 / 缺文档；领域需模型不具备的专业知识；有安全约束必须限制 Agent 能做什么。
- 反模式：为「保护」模型而预过滤上下文、收窄选项、层层包验证逻辑。随着模型变强，这些护栏会变成负债。每加一个工具都问：它在赋能新能力，还是在束缚模型本可自行处理的推理？为未来的模型留余地。
MCP 命名要求：始终用全限定名 ServerName:tool_name，否则多服务器场景会报 "tool not found"。
# 正确：全限定名
"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
# 错误：未限定，多服务器时可能失败
"Use the bigquery_schema tool..."
用 Agent 优化工具：把工具规格 + 观察到的失败喂给模型，让它诊断并改进描述，形成反馈闭环。生产实测可降低约 40% 任务完成时间。
def optimize_tool_description(tool_spec, failure_examples):
"""让 Agent 分析工具失败并改进描述。
1. Agent 在多样任务上尝试调用该工具
2. 收集失败模式与摩擦点
3. Agent 分析失败、提出改进
4. 用同一批任务测试改进后的描述
"""
prompt = f"""分析以下工具规格与观察到的失败。
Tool: {tool_spec}
Failures observed:
{failure_examples}
指出：1) Agent 为何失败 2) 描述缺了什么信息 3) 哪些歧义导致误用
给出改进后的工具描述。"""
return get_agent_response(prompt)
示例
好工具——名字、入参格式、返回、错误一应俱全：
def get_customer(customer_id: str, format: str = "concise"):
"""
按 ID 获取客户信息。
何时用：
- 用户询问某客户的具体信息
- 需要客户上下文来做决策 / 核验身份
Args:
customer_id: 格式 "CUST-######"（如 "CUST-000001"）
format: "concise" 仅关键字段，"detailed" 完整记录
Returns:
含所请求字段的客户对象
Errors:
NOT_FOUND: 客户 ID 不存在
INVALID_FORMAT: ID 必须匹配 CUST-###### 模式
"""
坏工具——典型反模式集合：
def search(query):
"""Search the database."""
pass
问题：名字含糊（搜什么）；缺参数说明（哪个库、query 什么格式）；无返回描述；无使用上下文；无错误处理。结果：Agent 不知何时该用、填不对格式、读不懂结果、错了也无法恢复。
注意事项
- 要避免的反模式：含糊描述（「helps with…」）、神秘参数名（
x/val/param1）、缺错误处理、命名不一致（一会id一会identifier一会customer_id）。 - 描述即 prompt：工具描述会进上下文并共同塑造 Agent 行为，它不是文档，是 prompt 工程。
- 默认值应反映常见用法，减少 Agent 负担、避免漏参出错。
- 返回格式显著影响上下文占用：concise 仅返回必要字段用于确认，detailed 返回完整对象用于决策；并在描述里说明何时用哪档。
- 错误信息面向两类读者：开发者调试 + Agent 恢复。对可重试错误给重试指引，对入参错误给正确格式，对缺数据给所需内容。
- 工具数量：研究表明描述重叠会让模型混淆，工具不是越多越好；多数应用 10-20 个，超出用命名空间分组，或用「伞形工具」路由到子工具。
- 评测维度：无歧义、完整、可恢复、高效、一致——用代表性请求测出实际调用再评判。
互见
- 上下文工程 / context-fundamentals：工具如何与上下文交互
- 多 Agent 模式 / multi-agent-patterns：按 Agent 配置专用工具
- 评测 / evaluation：工具有效性的测试方法
- 外部：MCP（Model Context Protocol）文档、各框架工具约定
采编自 sickn33/antigravity-awesome-skills（MIT 许可）。