Validating OpenAI & Anthropic Tool-Calling 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, but the call can still fail downstream.

A pre-deploy checklist

1. Is the whole tool definition valid JSON?
2. Are name and description both present and specific?
3. Is the parameter schema's root type set to "object"?
4. Is additionalProperties: false set, unless you have a specific reason not to?
5. Does the parameter schema actually compile as valid JSON Schema (no typos in keywords, correct nesting)?
6. Does a realistic sample arguments payload — the kind of JSON the model would actually send — satisfy the schema?

All six of these are checkable offline, without a live model call. I built a free tool that runs exactly this checklist: AI Tool / Function Calling Schema Validator — paste a tool definition, pick OpenAI or Anthropic, and it validates structure, compiles the schema, and checks sample arguments against it, entirely in your browser, no API calls.

Worked example: fixing a broken schema

Before — technically parseable, but has three of the problems above:

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

No description (the model has almost nothing to go on), no root type: "object", no required, and limit has no type at all.

After:

{
  "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
  }
}

Try it

Paste your own tool definition into the AI Tool Schema Validator and run through this exact checklist automatically, including testing sample arguments against the compiled schema. Nothing is sent to OpenAI, Anthropic, or any server — it's a structural, offline check only.