DEEP DIVE SERIES · #12

Schema Hardening for Deterministic Function Calling: Eliminating JSON Hallucinations and Type Failures

Luca Viscomi

· Published Sep 20, 2026 · Updated Sep 24, 2026 · 5 min read

When an AI agent fails to invoke a tool properly—sending an integer where a string was expected, omitting a mandatory property, or inventing an imaginary argument—developers often blame the model: “The LLM is hallucinating again.”

In 80% of production incident post-mortems, the fault lies entirely with the Tool Schema Architecture.

Language models do not “know” what your Python functions or TypeScript APIs expect. They are probabilistic token predictors conditioned on JSON Schema specifications embedded in their system prompt. If your schemas are ambiguous, unconstrained, or overly permissive, the model will inevitably generate invalid payloads.

Here is how to engineer hardened, deterministic function calling schemas that eliminate runtime tool failures.

1. The Anatomy of a Fragile Schema vs. a Hardened Schema

To see why schemas fail, compare these two definitions for an identical task: deploying a microservice.

The Fragile Schema (High Failure Rate)

{
  "name": "deploy_service",
  "description": "Deploys a microservice to the cloud",
  "parameters": {
    "type": "object",
    "properties": {
      "service": { "type": "string" },
      "environment": { "type": "string" },
      "config": { "type": "object" },
      "force": { "type": "boolean" }
    }
  }
}

Why this fails in production:

• service: No pattern or allowed values. The model sends "auth service", "Authentication", or "auth-api".
• environment: No enums. The model sends "prod", "production", "live", or "stage".
• config: Unconstrained object. The model invents arbitrary nested keys.
• required: Missing entirely! The model may omit service and send only force: true.

The Hardened Schema (Deterministic Reliability)

{
  "name": "deploy_service",
  "description": "Trigger an immutable CI/CD deployment for an authorized microservice. Fails if invalid environment is provided.",
  "parameters": {
    "type": "object",
    "properties": {
      "service_name": {
        "type": "string",
        "enum": ["auth-gateway", "billing-worker", "analytics-aggregator"],
        "description": "Exact name of target microservice from the internal service directory."
      },
      "target_environment": {
        "type": "string",
        "enum": ["staging", "production"],
        "description": "Target deployment cluster."
      },
      "release_tag": {
        "type": "string",
        "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+$",
        "description": "Semver release tag, e.g. 'v1.2.2'."
      },
      "requires_rollback_check": {
        "type": "boolean",
        "description": "Must be set to true for production deployments."
      }
    },
    "required": ["service_name", "target_environment", "release_tag", "requires_rollback_check"],
    "additionalProperties": false
  }
}

By enforcing enum bounds, regex pattern validation, mandatory required keys, and additionalProperties: false, you transform a probabilistic guessing game into an airtight contract.

2. The Five Rules of Schema Hardening

Rule 1: Always Enforce additionalProperties: false

Modern models (such as GPT-4o with Structured Outputs and Claude 3.5 Sonnet) respect strict JSON Schema mode. Setting additionalProperties: false at both the root and nested object levels prevents the model from injecting hallucinated configuration parameters.

Rule 2: Discriminated Unions Over Overloaded Schemas

Never create a “Swiss Army Knife” tool that accepts twenty optional flags depending on what mode it’s in (e.g., action: "read" | "write" | "delete").

Instead, split actions into distinct functions or use a Discriminated Union with an explicit discriminator field:

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "action": { "const": "READ_RECORDS" },
        "query": { "type": "string" },
        "limit": { "type": "integer", "maximum": 100 }
      },
      "required": ["action", "query"]
    },
    {
      "type": "object",
      "properties": {
        "action": { "const": "DELETE_RECORD" },
        "record_id": { "type": "string", "pattern": "^rec_[a-zA-Z0-9]+$" },
        "confirmation_token": { "type": "string" }
      },
      "required": ["action", "record_id", "confirmation_token"]
    }
  ]
}

Rule 3: Use Value Bounds (minimum, maximum, pattern)

For numbers and strings, always establish physical bounds:

• If an agent is fetching rows, enforce minimum: 1 and maximum: 50 to prevent an agent from inadvertently requesting 1,000,000 database rows into context.
• If an agent accepts file paths, enforce regex patterns like ^/workspace/[a-zA-Z0-9_./-]+$ to prevent directory traversal attacks (../../etc/passwd).

Rule 4: Docstring Engineering is Parameter Engineering

The description attribute in a JSON Schema is not documentation for human engineers; it is an active instruction for the model’s attention heads.

Always state:

1. What the parameter represents.
2. The exact expected format or unit (e.g., “Timeout in milliseconds, default 5000”).
3. The consequence of an invalid value.

Rule 5: Implement Double-Entry Runtime Validation

Never pass an LLM’s raw tool arguments directly into your database or system shell!

Always pass arguments through a runtime validation engine (such as Pydantic in Python, Zod in TypeScript, or OpenAI’s Structured Outputs with strict schema enforcement) before execution:

from pydantic import BaseModel, Field, field_validator
import re

class DeployServiceInput(BaseModel):
    service_name: str
    target_environment: str
    release_tag: str

    @field_validator("release_tag")
    @classmethod
    def validate_semver(cls, v: str) -> str:
        if not re.match(r"^v\d+\.\d+\.\d+$", v):
            raise ValueError(f"Invalid semver tag format: {v}. Must match 'vX.Y.Z'")
        return v

3. Automated Schema Auditing

To maintain schema quality across large agent ecosystems, implement an Automated Schema Auditor that flags fragile patterns during CI/CD:

[ Developer Defines Tool ]
           │
           ▼
[ CI/CD Schema Auditor ]
   ├── Checks for missing `description` fields
   ├── Checks for unconstrained `type: "string"` without enum/pattern
   ├── Checks for unconstrained `type: "object"` without properties
   └── Verifies `additionalProperties: false` is enforced
           │
     (Passed/Failed)
           │
           ▼
[ Deploy to Production Gateway ]

When your tool schemas are engineered as strict, deterministic types, tool-call hallucinations disappear, and your autonomous agents operate with rock-solid reliability.