OpenAI 与 Anthropic 工具调用 Schema 避坑指南

工具/函数调用的效果完全取决于其背后的 schema。一个在结构上有效的 schema 仍然可能导致 Agent 错误地调用你的工具——而一个存在细微问题的 schema 则可能静默失败。本文将探讨实际会出现哪些问题、如何在问题到达线上模型之前将其捕获，以及一个完整的修复示例。

两种格式，并排对比

OpenAI 和 Anthropic 都在工具/函数定义中包装了一个标准的 JSON Schema——只是将其嵌套在不同的字段名下。

OpenAI（function calling）：

{
  "name": "get_weather",
  "description": "Get the current weather for a given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City and state, e.g. San Francisco, CA" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"],
    "additionalProperties": false
  }
}

Anthropic（tool use）：形状相同，只是用 input_schema 替代了 parameters。

{
  "name": "get_weather",
  "description": "Get the current weather for a given location.",
  "input_schema": {
    "type": "object",
    "properties": { "location": { "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } },
    "required": ["location"],
    "additionalProperties": false
  }
}

五个容易出问题的地方——而且容易被忽略

根类型不是 "object"。两个提供商都期望工具参数以 JSON 对象的形式到达。如果一个 schema 的根类型是其他任何类型，都会被拒绝或表现不可预测——这虽然是一行代码就能修复的问题，但却是最常见的结构性错误。

缺少或模糊的 description 字段。这不是 JSON Schema 规范上的违规——description 在规范中不是必需的——但模型实际上是根据它来决定何时调用工具、如何调用工具，以及每个参数应该填写什么内容。一个在技术上有效但描述不足的 schema 会导致错误的调用，而不是报错。

没有设置 additionalProperties: false。如果没有这一设置，模型臆造出的额外参数仍然能通过验证。将其设置为 false 可以立即捕获这种臆造，而不是让它到达函数的实现层。

过度嵌套或模糊的 schema。深度嵌套、模糊的 oneOf 分支，或大量可选字段的扁平列表，都会增加模型猜错的几率。更扁平、更明确的 schema 能产生更可靠的调用。

枚举值与实际接受的值不匹配。一个相对于函数真实实现已经过时的枚举是一个静默的不匹配——schema 会验证通过，但调用仍然可能在下游失败。

部署前检查清单

• 整个工具定义是有效的 JSON 吗？
• name 和 description 都存在且具体吗？
• 参数 schema 的根类型设置为 "object" 了吗？
• additionalProperties: false 设置了吗，除非你有特定的理由不设置？
• 参数 schema 实际上能编译为有效的 JSON Schema 吗（关键字没有拼写错误、嵌套正确）？
• 一个现实的示例参数载荷——模型实际会发送的那种 JSON——满足这个 schema 吗？

这六项都可以离线检查，不需要调用线上模型。我构建了一个免费工具来运行这个检查清单：AI Tool / Function Calling Schema Validator——粘贴一个工具定义，选择 OpenAI 或 Anthropic，它会验证结构、编译 schema，并根据它检查示例参数，完全在你的浏览器中运行，不需要 API 调用。

完整示例：修复一个损坏的 schema

修复前——在技术上可解析，但存在上述三个问题：

{
  "name": "search",
  "parameters": {
    "properties": {
      "q": { "type": "string" },
      "limit": {}
    }
  }
}

没有 description（模型几乎没有任何依据可循）、没有根类型 "object"、没有 required、而且 limit 根本没有 type。

修复后：

{
  "name": "search",
  "description": "Search the product catalog by keyword and return matching items.",
  "parameters": {
    "type": "object",
    "properties": {
      "q": { "type": "string", "description": "Search keywords" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Max results to return" }
    },
    "required": ["q"],
    "additionalProperties": false
  }
}

将你自己的工具定义粘贴到 AI Tool Schema Validator 中，自动运行这个确切的检查清单，包括根据编译后的 schema 测试示例参数。没有任何内容被发送到 OpenAI、Anthropic 或任何服务器——这只是一个结构性的、离线的检查。