Validating OpenAI & Anthropic Tool-Calling Schemas

---

title: Validating OpenAI & Anthropic Tool-Calling Schemas

published: true

tags: ai, openai, anthropic, json

description: A practical guide to writing and validating JSON Schemas for OpenAI function calling and Anthropic tool use - common mistakes, a pre-deploy checklist, and a worked example.

canonical_url: https://www.json-util.com/guides/validating-ai-tool-schemas

---

Tool/function calling only works as well as the schema behind it. A structurally valid schema can still make an agent call your tool wrong — and a subtly broken one can fail silently. This post covers what actually goes wrong, how to catch it before it reaches a live model, and a worked example.

The two formats, side by side

OpenAI and Anthropic both wrap a standard JSON Schema in a tool/function definition — they just nest it under a different field name.

**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):** identical shape, just `input_schema` instead of `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
  }
}

Five things that go wrong — and are easy to miss

1. **Root type isn't "object".** Both providers expect tool arguments to arrive as a JSON object. A schema whose root `type` is anything else gets rejected or behaves unpredictably — a one-line fix, but the single most common structural mistake.

2. **Missing or vague `description` fields.** Not a JSON Schema violation — `description` isn't required by the spec — but it's what the model actually reads to decide when and how to call the tool, and what to put in each argument. A schema that's technically valid but under-described leads to wrong calls, not errors.

3. **No `additionalProperties: false`.** Without it, a model that hallucinates an extra argument still passes validation. Setting it to `false` catches the hallucination immediately instead of letting it reach your function's implementation.

4. **Overly nested or ambiguous schemas.** Deep nesting, ambiguous `oneOf` branches, or a huge flat list of optional fields all increase the model's chance of guessing wrong. Flatter, more explicit schemas produce more reliable calls.

5. **Enum values that don't match what you actually accept.** An `enum` that's stale relative to your function's real implementation is a silent mismatch — the schema will validate, bu