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.
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
}
}
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.
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.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.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.
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.
name
and description
both present and specific?type
set to "object"
?additionalProperties: false
set, unless you have a specific reason not to?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.
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
}
}
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.