Function Calling JSON Schema GuideFunction Calling JSON Schema 指南
A practical engineering guide to JSON Schema in function calling systems — covering validation rules, input/output structure, tool safety, MCP compatibility, and QVeris schema inspection workflows.函数调用系统中 JSON Schema 的实用工程指南 — 涵盖验证规则、输入/输出结构、工具安全、MCP 兼容性以及 QVeris Schema 检查工作流。
Structure · Validate · Execute · Safeguard结构化 · 验证 · 执行 · 防护
What is JSON Schema in Function Calling?什么是函数调用中的 JSON Schema？
JSON Schema defines the structure of tool inputs and outputs in AI agent systems. It tells the model what parameters are required, what types are allowed, what format is valid, and what constraints apply — establishing a deterministic contract between the agent's reasoning layer and the tool's execution layer.JSON Schema 定义 AI Agent 系统中工具输入与输出的结构，明确哪些参数必填、允许哪些类型、格式应如何以及有哪些约束，从而在 Agent 推理层与工具执行层之间建立确定性的契约。
In function calling, the model receives a list of function definitions that include JSON Schema for each function's parameters. When the model decides to call get_stock_price, it must output arguments that conform to the schema — {"symbol": "AAPL"} is valid if symbol is a required string; {"ticker": "AAPL"} will fail schema validation because the parameter name does not match. Schema is the guardrail that prevents the most common production failure mode: parameter mismatch between what the model outputs and what the tool expects.在函数调用中，模型接收包含每个函数参数 JSON Schema 的函数定义列表。当模型决定调用 get_stock_price 时，它必须输出符合 Schema 的参数 — {"symbol": "AAPL"} 在 symbol 是必需字符串时有效；{"ticker": "AAPL"} 将因参数名称不匹配而验证失败。Schema 是防止最常见生产失败模式的护栏：模型输出与工具期望之间的参数不匹配。
Why Schema Matters in AI Agents为什么 Schema 对 AI Agent 很重要
Without Schema没有 Schema
Agents hallucinate parameters. Tools fail at runtime with opaque error messages. Outputs become unreliable and impossible to validate programmatically. Debugging requires reading raw API responses manually. Multi-tool orchestration breaks when one tool returns unexpected output format.Agent 容易臆造参数，工具在运行时以难以理解的错误失败，输出不可靠且无法程序化验证。调试时只能人工阅读原始 API 响应；只要某个工具返回意外格式，多工具编排就可能中断。
With Schema有 Schema
Tool calls are deterministic — the model knows exactly what parameters are valid. Validation is automatic — the execution layer catches mismatches before API calls. Execution becomes safe — invalid calls are blocked, not attempted. Debugging becomes structured — every validation failure has a clear cause.工具调用变得确定：模型清楚哪些参数有效；验证自动完成，执行层会在 API 调用前发现不匹配；无效调用会被阻止而不是贸然执行；每次验证失败都有明确原因，调试也更加结构化。
Input Schema vs Output Schema输入 Schema vs 输出 Schema
| Schema TypeSchema 类型 | Purpose用途 | Example示例 |
|---|---|---|
| Input Schema输入 Schema | Defines what the agent sends to the tool定义 Agent 向工具发送什么 | {"symbol": "string", "interval": "enum"} |
| Output Schema输出 Schema输出 Schema | Defines what the tool returns to the agent定义工具向 Agent 返回什么 | {"price": "number", "timestamp": "string"} |
Both schemas are equally important. A well-defined input schema prevents invalid calls. A well-defined output schema enables downstream agent reasoning — the agent knows exactly what fields to expect and can validate the response before incorporating it into the workflow.两种 Schema 同等重要。定义良好的输入 Schema 防止无效调用。定义良好的输出 Schema 支持下游 Agent 推理 — Agent 确切知道期望什么字段，并可以在将其纳入工作流之前验证响应。
Required Fields & Validation Rules必填字段与验证规则
✓ Required Fields Must Be Explicit✓ 必填字段必须明确
Every required parameter must be listed in the required array. The model will not guess which fields are mandatory — if it is not declared required, the model may omit it.
✓ Types Must Be Strict
Use string字符串, number数字, boolean布尔值, array数组, object对象 — never any or untyped fields. Loose typing is the most common source of silent production failures.
✓ Enums Must Restrict Values✓ 枚举必须限制允许值
When a parameter has a limited set of valid values, use enum to restrict it. {"interval": "weekly"} should fail if the enum only allows ["1d","1h","15m"].
✓ Optional Fields Must Be Explicitly Optional✓ 可选字段必须明确标注为可选
Do not put optional fields in the required array. Provide sensible defaults where possible. The model should not have to guess whether a field is optional.
Schema Types & ConstraintsSchema 类型与约束
| Type类型 | Use Case使用场景 | Constraint Examples约束示例 |
|---|---|---|
| string字符串 | Symbols, identifiers, timestamps代码、标识符与时间戳 | enum, pattern, format, minLength |
| number数字 | Prices, quantities, percentages价格、数量与百分比 | minimum, maximum, multipleOf |
| boolean布尔值 | Flags, toggles, include/exclude标志、开关与包含/排除选项 | default |
| array数组 | Lists of symbols, multi-value params代码列表与多值参数 | minItems, maxItems, uniqueItems |
| object对象 | Nested configurations, complex inputs嵌套配置与复杂输入 | required, additionalProperties |
Common Schema Design Mistakes常见的 Schema 设计错误
The
required array is empty or incomplete. The model omits critical parameters. The tool call fails with a missing-argument error that could have been prevented at schema definition time.Fields declared as
{"type": "string"} with no enum, no pattern, no constraints. The model sends "1day" when the API expects "1d". Always constrain where the domain is finite.A
price field with no minimum. The model could theoretically send a negative price. Add "minimum": 0 to prevent nonsensical values from reaching the API.The output schema says
price is a number, but the tool sometimes returns it as a string. The downstream agent parsing breaks. Always validate that tools actually conform to their declared output schemas.The tool's error response format is undefined. When the tool fails, the agent receives an unstructured error and cannot determine whether to retry, fallback, or report failure. Define an error schema alongside the success schema.
Schema in MCP & Tool CallingMCP 和工具调用中的 Schema
| Layer层级 | How It Uses Schema如何使用 Schema |
|---|---|
| MCP | Defines how tool schemas are exposed in server manifests — the protocol layer that publishes schemas定义工具 Schema 如何在服务器清单中暴露，是负责发布 Schema 的协议层。 |
| Tool Calling | Uses schema to validate inputs before execution and check outputs after — the agent execution layer使用 Schema 在执行前验证输入、执行后检查输出，属于 Agent 执行层。 |
| Function Calling | Uses schema to format model output into valid structured arguments — the model output layer依据 Schema 把模型输出格式化为有效的结构化参数，属于模型输出层。 |
| QVeris InspectQVeris 检查QVeris 检查 | Validates schema at discovery time — checking that a tool's declared schema matches agent requirements before selection在发现阶段验证 Schema，选择工具前检查其声明的 Schema 是否符合 Agent 要求。 |
Schema is the shared contract across all layers. MCP publishes it. Tool calling enforces it. Function calling formats output against it. QVeris inspects it before the agent commits to a tool. When any layer's schema handling breaks, the entire tool execution chain becomes unreliable.Schema 是所有层之间的共享契约。MCP 发布它。工具调用执行它。函数调用根据它格式化输出。QVeris 在 Agent 承诺使用工具之前检查它。当任何层的 Schema 处理中断时，整个工具执行链变得不可靠。
How Agents Use Schema at RuntimeAgent 如何在运行时使用 Schema
Schema is not just a design-time artifact. It powers every step of the agent's runtime tool execution pipeline:Schema 不仅仅是设计时的产物。它驱动 Agent 运行时工具执行管道的每一步：
1. Tool Discovery
The agent searches for tools matching the task. Schema descriptions and parameter names are the primary signals for capability matching — a tool with symbol and price in its schema is a better candidate for a stock lookup task than a tool with generic fields.
2. Schema Inspection2. Schema 检查2. Schema 检查
Before selecting a tool, the agent inspects its input schema: Are all required parameters available? Do the types match what the agent can provide? Are enum constraints compatible with the task? This is QVeris's Inspect phase.选择工具前，Agent 会检查输入 Schema：必填参数是否齐全？类型是否与 Agent 可提供的数据匹配？枚举约束是否符合任务？这就是 QVeris 的 Inspect 阶段。
3. Input Validation
The execution layer validates the model's function calling output against the declared input schema before sending it to the API. A missing required field or a type mismatch is caught here — not at the API response layer.执行层会先依据声明的输入 Schema 验证模型的函数调用输出，再发送给 API。缺少必填字段或类型不匹配会在这里被发现，而不是等到 API 返回后。
4. Output Validation
The tool's response is validated against the declared output schema. Unexpected fields, missing required outputs, or type mismatches are flagged before the response reaches the agent's reasoning layer.工具响应会依据声明的输出 Schema 验证；意外字段、缺少必需输出或类型不匹配都会在响应进入 Agent 推理层前被标记。
QVeris Schema Inspection LayerQVeris Schema 检查层
QVeris helps agents during the Inspect phase — validating schemas before the agent commits to calling a tool. It does not define schemas; it inspects and validates them.QVeris 在 Inspect 阶段检查阶段帮助 Agent — 在 Agent 承诺调用工具之前验证 Schema。它不定义 Schema；它检查并验证它们。
Inspect Input Schema检查输入 Schema
Verify required fields, types, enums, constraints. Confirm the agent has all required information before attempting execution. Catch schema mismatches early.核对必填字段、类型、枚举和约束，并在执行前确认 Agent 已具备全部所需信息，尽早发现 Schema 不匹配。
Inspect Output Schema检查输出 Schema
Check that the tool's declared output structure matches what the agent's downstream workflow expects. Incompatible output schemas cause silent integration failures.检查工具声明的输出结构是否符合下游工作流预期。不兼容的输出 Schema 可能导致难以察觉的集成失败。
Route on Schema MismatchSchema 不匹配时路由Schema 不匹配时路由
If a tool's schema does not match agent requirements, route to a fallback tool whose schema does match — rather than attempting a call that will fail.如果工具 Schema 不符合 Agent 要求，应路由到 Schema 匹配的回退工具，而不是尝试注定失败的调用。
Validate Provider Constraints
Check provider-specific notes, rate limits, authentication requirements, and API limitations encoded in the schema metadata — not just the type definitions.除了类型定义，还要检查 Schema 元数据中的提供商说明、速率限制、认证要求和 API 限制。
QVeris does not define schemas.QVeris 不负责定义 Schema。 It helps agents inspect and validate schemas before execution — catching mismatches at discovery time rather than at API call time. Read the docs → or view pricing →.QVeris 不定义 Schema。QVeris 不负责定义 Schema。它帮助 Agent 在执行前检查和验证 Schema — 在发现时而不是在 API 调用时捕获不匹配。阅读文档 → 或 查看定价 →。
Getting Started Checklist快速上手指南
any, untyped, or free-text types without constraints避免松散类型 — 永远不要使用无约束的 any、无类型或自由文本类型Make Every Tool Call Schema-Validated让每次工具调用都经过 Schema 验证使每个工具调用都经过 Schema 验证
QVeris Inspect validates tool schemas at discovery time — before your agent commits to a call. Catch mismatches early, route to compatible tools, and keep your agent's tool execution reliable. Discover and Inspect are free forever.QVeris Inspect 在发现时验证工具 Schema — 在您的 Agent 承诺调用之前。及早捕获不匹配，路由到兼容工具，并保持 Agent 工具执行的可靠性。Discover 和 Inspect 永久免费。
Build Safe AI Agents →构建安全的 AI Agent →Explore QVeris DocsFAQ常见问题
Why is JSON Schema important in function calling?为什么 JSON Schema 在函数调用中很重要？
Can AI agents work without JSON Schema?AI Agent 可以不使用 JSON Schema 吗？
symbol becomes ticker. interval becomes 1day instead of 1d. These failures happen at the API layer, not the reasoning layer, making them hard to debug. Schema validation catches these mismatches before any API call is made — which is why it is not optional for production-grade systems.可以，但可靠性显著下降。没有 Schema 验证，Agent 猜测参数名称和类型。symbol 变成 ticker。interval 变成 1day 而不是 1d。这些失败发生在 API 层而非推理层，使其难以调试。Schema 验证在任何 API 调用之前捕获这些不匹配 — 这就是为什么它对生产级系统不是可选的。Does MCP replace JSON Schema?MCP 会取代 JSON Schema 吗？
What causes most function calling failures?大多数函数调用失败由什么导致？
any or free-text types (model sends wrong format), no enum constraints (model invents values the API does not accept), inconsistent output schemas (tool returns unexpected format), and no error schema (agent cannot determine whether to retry or fallback).不正确或不完整的 Schema 定义。最常见的问题：缺失必填字段（模型省略关键参数），使用 any 或自由文本类型的弱类型（模型发送错误格式），没有枚举约束（模型编造 API 不接受的值），不一致的输出 Schema（工具返回意外格式），以及没有错误 Schema（Agent 无法确定是重试还是回退）。