04. 工具 Schema 怎样改变 Agent 的行为

同一个只读任务，Codex 生成了一条复合 Shell 命令，Kimi 生成了两个并行 Bash 调用。这不能只解释为模型风格差异，因为模型看到的工具接口并不相同。

工具 Schema是工具名称、用途说明、参数类型、必填字段和取值范围组成的结构化契约。模型根据这份契约选择工具并生成参数，执行器再按同一契约校验输入。

工具定义同时影响能力与决策

若工具叫 run_anything，参数只有一个任意字符串，模型需要自行构造命令，执行器也很难在执行前判断影响。若拆成 read_file(path) 和 list_directory(path, limit)，动作意图在参数层就已经可见。

描述不是越长越好

描述要回答三个问题：工具做什么、什么时候使用、什么情况不能使用。过短会让相近工具难以区分；过长会增加每轮固定上下文，并把权限规则分散到自然语言中。

一个用于目录读取的接口至少应说明：

• 只返回一层还是递归。
• 是否包含隐藏文件。
• 最大返回数量。
• 路径必须位于哪个根目录。
• 符号链接怎样处理。

其中最后两项不能只写在描述里。路径根目录和链接策略还要由执行器校验。

参数校验要发生两次

模型生成参数后，运行时先做结构校验，再做策略校验。

结构正确不等于操作被授权。{"path":"/etc/passwd"} 可能符合字符串类型，却不符合工作区读取策略。

我会怎样验证 Schema 的影响

保持模型、任务和文件目录不变，只修改工具定义：

每组运行 30 次，记录工具选择正确率、参数校验失败率、模型轮次和输入 Token。单次轨迹只能展示机制，重复样本才能比较 Schema 是否稳定地改变行为。

工具返回也需要契约

返回值若只是一段文本，模型和日志系统无法可靠区分成功、空结果、截断和失败。至少要保留状态、耗时、错误类型、是否截断和结果正文。

Kimi 抓包中的两条工具消息使用 tool_call_id 对应 Bash_0 与 Bash_1。这个标识让并行结果能够回到正确调用。工具名称告诉运行时调用谁，调用标识告诉运行时结果属于哪一次动作。

工具 Schema 因此不是 API 文档的附属内容。它是 Agent 的动作空间，也是权限检查和轨迹重放的入口。