工具 Schema 校验

贴上工具定义，弄清它为什么被拒绝——或者为什么被错误调用。

工具定义描述着内部系统与端点。一切都在浏览器里校验，不会上传。

从零构建一份定义

关于 工具模式校验器

一份工具定义里住着两类问题。第一类是结构性的：不是 JSON Schema 类型的类型、不在属性里的必填名、没有 items 的数组、缺了严格模式所要求规则的严格模式。这些会被拒绝，而返回的消息通常只点出字段、不说原因。第二类完全通得过校验，却造成另一种麻烦：工具在错误的时机被调用，或某个参数里塞着看似合理的胡话，因为 schema 里没有任何地方说明这些东西是什么意思。这里两类都查，每条结论都附上它的来源路径，而且你贴什么形状都接受：单个工具、一个数组、一段请求片段，或者只是一份 schema。

功能特性

• 接受单个工具、数组、tools 片段或独立 schema
• 每条结论都带上它的来源路径
• 识别无效类型，包括单个属性上的
• 识别不在属性里的必填名
• 落实严格模式的规则，并点名违规的属性
• 标出放在错误键下的 schema
• 识别数组中重复的工具名
• 对无描述的参数和空枚举发出警告

如何使用 工具模式校验器

1. 按你手头的形状贴上定义
2. 对照路径读结论
3. 先改错误，再补描述
4. 反复检查，直到什么都不剩

示例

输入

"required": ["email", "customer_id"]

输出

Error: “customer_id” is required but is not among the properties

没有对应属性的必填名会被直接拒绝。

常见错误与故障排除

• API 拒绝了工具却不点出字段。 — 贴到这里来——结论带路径，会直接点名出问题的节点，不必自己去找。
• 它说我的 schema 放在错误的键下。 — Messages API 读的是 input_schema。为其他约定写的定义常用 parameters，那是合法 JSON，只是不会被读取。
• 看起来没问题的 schema 却过不了严格模式。 — 严格模式需要 additionalProperties: false，且所有属性都必填。两点都会检查，并点名违规的属性。
• 它给的是描述方面的警告而不是错误。 — 那是第二类问题。它们不会妨碍工具被接受；它们正是工具被传错参数的原因。

常见问题

我能贴哪些形状？

一个工具对象、一个工具数组、一段 {"tools": [...]} 片段，或者一份独立的输入 schema。独立 schema 会被识别并注明，因为一个工具还需要名称和描述。

为什么要对缺失的描述发出警告？

因为它们是工具被错误调用最常见的原因，而且从不产生报错。一个只有名字没有描述的参数，会让含义只能从名字去猜。

它会拿真实参数来校验我的 schema 吗？

不会——它校验的是定义本身。某一组具体参数能不能通过是另一个问题，由 API 在你调用时回答。

支持 $ref 吗？

会被标出。引用在工具 schema 里未必能可靠解析，所以依赖引用的定义常常表现得和作者读到的不一样。把定义内联展开就绕开了这个问题。

能一次校验多个工具吗？

可以，把整个数组贴上来。集合中重复的名字会被抓到——这个问题只有把工具放在一起看时才会显现。

相关工具

• MCP 工具模式构建器 — 定义工具并得到 JSON Schema，严格模式一并校验。
• MCP 服务器配置 — 为 stdio、HTTP 或 SSE 生成 MCP 服务器条目。
• SSE 流查看器 — 粘贴原始流式响应，取回正文、工具调用与用量。
• 系统提示检查器 — 找出自相矛盾、无效指令与未替换的占位符。
• JSONL 查看与校验 — 逐行读取、筛选并检查 JSONL 文件。
• 子代理构建器 — 生成子代理定义文件，含工具与模型设置。

更多AI 与智能体工具

• 技能构建器 — 编写 SKILL.md，边输入边检查 frontmatter。
• 技能检查器 — 粘贴 SKILL.md，看清是什么让它无法与任务匹配。
• 子代理构建器 — 生成子代理定义文件，含工具与模型设置。
• 斜杠命令构建器 — 构建自定义命令，带参数与工具白名单。
• 项目说明构建器 — 写一份对得起每次请求开销的 CLAUDE.md。
• 插件清单构建器 — 生成 plugin.json，并查看它所预设的目录结构。
• 钩子构建器 — 构建 settings.json 钩子，找出永远不会触发的匹配式。
• 权限规则测试器 — 用真实命令测试允许、询问与拒绝规则。
• MCP 服务器配置 — 为 stdio、HTTP 或 SSE 生成 MCP 服务器条目。
• MCP 工具模式构建器 — 定义工具并得到 JSON Schema，严格模式一并校验。
• 提示模板填充 — 把一条提示展开到整张表格，并看清缺了哪些值。
• 系统提示检查器 — 找出自相矛盾、无效指令与未替换的占位符。
• 提示差异比较 — 逐词比较两个提示版本，并给出 token 差额。
• 少样本示例构建器 — 把输入输出对转成带标签、JSON 或对话格式的示例。
• XML 提示分节构建器 — 用内容无法越出的标签包裹提示的各个部分。
• JSONL 查看与校验 — 逐行读取、筛选并检查 JSONL 文件。
• 对话记录转换 — 把消息数组转成可读记录，也能转回去。
• 微调数据集校验 — 检查 chat 格式 JSONL，找出会中断训练的错误。
• SSE 流查看器 — 粘贴原始流式响应，取回正文、工具调用与用量。
• 上下文窗口规划 — 在提示、工具、历史与回复之间分配上下文窗口。
• 提示缓存规划 — 重排请求的各块，让可缓存前缀尽可能长。
• 文本切分 — 把文档切成有重叠的片段，只在真正的边界处断开。
• 代理循环成本估算 — 逐轮估算成本，计入重发的历史与缓存。
• 批量请求构建器 — 把表格转成批量任务，每条请求都有唯一 id。

查看全部AI 与智能体工具 · 全部工具