Tool schema contracts: treating AI agent tools like APIs

An agent decides to call a tool. It constructs the arguments from the conversation context, sends the call, and acts on the response. If the arguments are malformed, the tool may fail silently, return unexpected data, or worse — execute a valid but unintended operation. The agent carries on regardless, building its next step on a broken foundation.

This failure mode is the tool-layer equivalent of calling a function with no type checking. And in most production agent systems, it is the default.

Tool schema contracts change the default. They treat every tool interface like an API with an enforced contract — validating inputs before the call and outputs after — so mismatches are caught at the boundary instead of propagating through the agent’s reasoning chain. The concept is one of five governance controls in the agentic technical debt framework (forthcoming in Communications of the ACM, October 2026).

The idea has a long pedigree. In 1992, Bertrand Meyer formalized Design by Contract in IEEE Computer: every interface carries preconditions (what the caller must provide), postconditions (what the callee guarantees in return), and invariants (what must always hold). Tool schema contracts apply exactly this structure to agent-tool boundaries — with one critical addition: the caller is non-deterministic.

Key takeaways

• Most agent-tool interactions are unvalidated by default. The agent constructs arguments from natural-language context; the tool trusts whatever it receives.
• Schema contracts enforce structured validation at the boundary: input schemas (preconditions) before the call, output schemas (postconditions) after, and semantic constraints (invariants) throughout.
• Constraints that can be expressed deterministically — format rules, policy limits, range checks — should live in code, not in the prompt.
• The Model Context Protocol standardizes tool discovery and invocation, but schema enforcement is a layer you add on top.

Why LLMs get tool calls wrong

Understanding why schema contracts matter requires understanding how LLMs construct tool calls — and where they fail.

The ReAct paradigm (Yao et al., ICLR 2023) established the modern pattern: the model interleaves reasoning traces with action steps, deciding which tool to call, what arguments to pass, and how to incorporate results. Toolformer (Schick et al., NeurIPS 2023) showed that language models can even learn to decide when to call tools autonomously — but the accuracy of those calls depends entirely on how well the model interprets the tool’s natural-language description.

Gorilla (Patil et al., NeurIPS 2024) demonstrated the scale of the problem: even a model fine-tuned specifically for API calling makes errors when API versions change or when the documentation is ambiguous. The API-Bank benchmark (Li et al., EMNLP 2023) tested tool-call accuracy across three complexity levels — single call, retrieve-and-call, and plan-and-call — and found that accuracy drops significantly as the number of available APIs and the planning depth increase.

A comprehensive survey on tool learning with foundation models (Qin et al., ACM Computing Surveys 2024) identifies four failure modes in tool invocation:

1. Wrong tool selection. The model picks a plausible but incorrect tool based on surface-level similarity in the description.
2. Malformed arguments. The model generates arguments that are syntactically valid JSON but semantically wrong — wrong field names, wrong types, wrong units.
3. Missing required fields. The conversation context did not mention a required parameter, so the model omits it or hallucinates a value.
4. Misinterpreted responses. The tool returns data the model was not trained to parse, and downstream reasoning builds on a misread.

Schema contracts address all four: input validation catches 2 and 3, output validation catches 4, and tool description standardization (through protocols like MCP) reduces 1. Without contracts, each failure silently propagates.

The problem: untyped boundaries

In traditional software, an API call goes through multiple validation layers. The HTTP client serializes the request. The server validates the payload against a schema. Type systems catch mismatches at compile time. OpenAPI specs document expected formats. If you send a string where an integer is expected, the system tells you.

Agent-tool interactions skip most of these layers. The agent generates tool-call arguments by reasoning over natural-language context. The arguments are structured (typically JSON), but the structure is derived from the prompt’s tool description — a natural-language specification that the model interprets probabilistically.

This means:

• Arguments can be syntactically valid but semantically wrong. The agent sends {"amount": 500} when the tool expects {"amount_cents": 50000}. The JSON parses. The tool executes. The customer gets a $5 refund instead of $500.
• Required fields can be missing. The agent omits a field the tool needs because the conversation context did not mention it. The tool either fails or uses a default that may not be appropriate.
• Types can drift. The agent sends a date as a string in one format; the tool expects another. This works most of the time because the tool is lenient, until the one format the tool cannot parse appears.
• Outputs can change shape. A tool update adds a new field or nests a previously flat response. The agent’s downstream reasoning, trained on the old format, misinterprets the result.

These are the same problems that typed APIs solved decades ago. Meyer’s Design by Contract formalized the solution in 1992. The difference is that agents bypass the typed layer by constructing calls from natural language, and the standard agent frameworks do not enforce validation at the boundary by default.

What a tool schema contract looks like

A tool schema contract has three components — directly mapping to Meyer’s preconditions, postconditions, and invariants.

Input schema (preconditions)

A JSON Schema (or equivalent) that defines exactly what the tool accepts: field names, types, required fields, value ranges, enumerated options, and format constraints.

{
  "name": "process_refund",
  "input_schema": {
    "type": "object",
    "required": ["order_id", "amount_cents", "reason"],
    "properties": {
      "order_id": { "type": "string", "pattern": "^ORD-[0-9]{8}$" },
      "amount_cents": { "type": "integer", "minimum": 1, "maximum": 50000 },
      "reason": { "type": "string", "enum": ["defective", "wrong_item", "not_received", "changed_mind"] }
    },
    "additionalProperties": false
  }
}

Before the tool call executes, the agent’s arguments are validated against this schema. A mismatch is caught immediately — the agent gets an error message it can reason about, rather than a silent failure downstream.

Output schema (postconditions)

A schema defining what the tool returns. This is less common in practice but equally important: it protects the agent’s downstream reasoning from unexpected response formats.

{
  "output_schema": {
    "type": "object",
    "required": ["status", "refund_id"],
    "properties": {
      "status": { "type": "string", "enum": ["approved", "denied", "pending_review"] },
      "refund_id": { "type": "string" },
      "denial_reason": { "type": "string" }
    }
  }
}

If a tool update changes the response shape, the output validation catches it before the agent builds on stale assumptions.

Semantic constraints (invariants)

Some constraints are business rules that do not fit neatly into JSON Schema. A refund amount must not exceed the original order total. A scheduling tool must not book appointments in the past. A database write must not target a production table during a maintenance window. A tool that reads persistent memory must validate that the retrieved state is current before acting on it.

These constraints are expressed as deterministic checks — code that runs between the schema validation and the tool execution. They are the “harness” layer: hard limits that the agent cannot reason its way around, regardless of what the prompt says.

As we argued in Harvard Business Review, agents need defined roles, bounded authority, and clear escalation rules — the same governance structure you apply to any team member. Tool schema contracts are the mechanism that bounds the agent’s authority at the tool layer: the agent can request any action, but the contract determines whether the action is allowed to execute.

Moving constraints out of prompts

This is the highest-leverage application of tool schema contracts: taking constraints that are currently expressed as natural-language instructions in the prompt and reimplementing them as deterministic code.

A prompt that says: “When processing refunds, never exceed $500. Always require a reason. Valid reasons are: defective, wrong item, not received, or changed mind.”

This works most of the time. But “most of the time” is exactly the problem with agentic systems — the exceptions generate stochastic tax in the form of retries, escalations, and post-hoc corrections.

The same constraints in a schema contract work every time. The validation is deterministic. It does not depend on the model, the context window, or whether the instruction was in the system prompt or the conversation history. It cannot be jailbroken, forgotten, or overridden by a convincing user message. This is what makes schema contracts a foundational layer of enterprise AI guardrails — they enforce rules at the execution boundary, not at the interpretation layer.

Rule of thumb: if a constraint can be expressed as a Boolean check on the tool-call arguments, it belongs in code, not in the prompt. Reserve the prompt for constraints that require judgment — “use the most appropriate reason category” rather than “only use these four categories.”

Schema contracts and the Model Context Protocol

The Model Context Protocol (MCP) standardizes how agents discover and invoke tools. It defines a tool listing format that includes inputSchema — a JSON Schema describing the tool’s expected arguments. This is a significant step toward schema contracts because it gives the agent and the runtime a shared, machine-readable definition of the tool interface.

But MCP’s inputSchema is descriptive, not prescriptive by default. The schema tells the model what the tool expects; whether the runtime validates the call against that schema before executing depends on the implementation. A schema contract adds the enforcement layer: validate before calling, validate after returning, and reject anything that does not conform.

If you are building on MCP, adding validation at the agent communication layer is the natural place to enforce contracts. If you are using a framework like LangChain or the OpenAI Agents SDK, you can wrap tool functions with validation middleware that checks arguments against a schema before invoking the underlying function.

Preventing tool schema drift

Schema contracts are useful only if they stay in sync with the tools they describe. Schema drift — where the contract says one thing and the tool does another — is a form of agentic technical debt that produces especially confusing failures: the validation passes, but the tool behaves unexpectedly because the schema is outdated.

Three practices prevent drift:

1. Generate schemas from the tool, not by hand

If the tool is an API, derive the schema from the API’s own specification (OpenAPI, GraphQL schema, gRPC protobuf). If the tool is a function, use the function’s type annotations. Hand-written schemas diverge from the implementation the moment someone updates the tool without updating the schema.

2. Version schemas alongside tools

When a tool changes, its schema changes in the same commit. The schema is not documentation — it is part of the contract. Treat it with the same rigor you would treat a database migration.

3. Run contract tests

A contract test calls the tool with known inputs and verifies the output matches the output schema. Run these in CI. If the tool’s response no longer conforms to the contract, the test fails before the agent encounters the mismatch in production. This is consumer-driven contract testing — a practice borrowed from microservice architecture — applied to agent-tool boundaries.

What schema contracts cost — and what they save

Adding schema validation adds latency — typically 1–5 milliseconds per tool call, negligible compared to the LLM inference time that surrounds it. The real cost is engineering time: defining schemas, writing semantic constraints, and maintaining them as tools evolve.

What you save is stochastic tax. Every malformed tool call that schema validation catches is a retry you do not pay for. Every policy violation caught at the boundary is an escalation that does not happen. Every output format mismatch caught before downstream reasoning is a cascade of errors that does not propagate through your orchestration graph.

Schema contracts also reduce the cost of change. When prompt drift shifts the agent’s behavior, the contract catches the behavioral deviation at the tool boundary before it reaches the customer. When a model update changes how the LLM interprets tool descriptions, the schema validation catches the format mismatch at the call site. The contract is the safety net that makes frequent deployments economically viable.

For workflows where tool calls are frequent and consequences are real — financial operations, customer-facing actions, database writes — the return on schema contracts is immediate. For low-stakes, internal-only workflows, the investment may not be justified until the orchestration complexity reaches a point where unvalidated handoffs become the primary source of failures.

Where schema contracts fit in the governance framework

Tool schema contracts are one of five governance controls in the agentic technical debt framework, alongside golden-set evaluation, model gateways, graduated autonomy, and workflow graph redesign. They specifically target the semantic ambiguity and tool schema drift accumulation mechanisms — the ways natural-language interfaces and changing tool behaviors create hidden coupling.

The question to ask today: for each tool your agent calls, can you point to a schema that defines what the tool accepts and what it returns — and is that schema enforced at runtime, or just documented in a prompt? If the answer is “just in the prompt,” schema contracts are where to start.

For the full framework, see Agentic technical debt: a governance framework for AI agents.