Guide · Updated August 2026

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 guide 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 - this is a one-line fix, but it's 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 falsecatches 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. Our AI Tool / Function Calling Schema Validator runs exactly this checklist: 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.

FAQ

Do OpenAI and Anthropic use the same schema format?

Both wrap a standard JSON Schema, but under different field names: OpenAI nests it under 'parameters', Anthropic under 'input_schema'. The schema contents themselves follow the same JSON Schema rules either way.

Why does my agent keep calling the tool with the wrong arguments?

Almost always a description problem, not a schema-validity problem. The model reads your name/description fields to decide what to put in each argument - a technically valid but vague schema still leads to bad calls.

Is there a way to check this without calling the model?

Yes - structural validation (is this valid JSON, is it shaped like a tool definition, does the parameter schema compile) can be checked entirely offline. Our AI Tool Schema Validator does exactly this, plus lets you test sample arguments against the schema.