LLM Tool Contract Testing in Production: Reducing Agent Upgrade Risks with Schema Compatibility, Golden Conversations, and Sandbox Replay

Background: Why Tool Upgrades Break Agents

In traditional backend systems, API contracts are enforced by client code, OpenAPI docs, type definitions, and integration tests. As long as fields aren’t deleted, enums aren’t broken, and the response format remains deserializable, many changes are considered compatible.

But the LLM Agent tool calling chain introduces an unstable factor: the model reads tool names, descriptions, parameter schemas, historical messages, and tool return values, then decides whether to call a tool, which tool to call, and how to fill in the parameters. This means the tool contract is not just a machine-parseable JSON Schema; it’s also a part of the prompt that the model uses to understand the task.

OpenAI’s Function Calling documentation explicitly states that function tools are defined by JSON Schema, the model returns tool_calls, and the application must execute the function and return the result to the model. Anthropic’s Tool Use documentation follows a similar pattern: developers pass tools with input_schema, Claude returns a tool_use block, and the application executes and returns a tool_result. Google Gemini’s Function Calling documentation requires submitting function declarations and supports controlling whether the model automatically, forcibly, or prohibits calling functions.

These mechanisms show that tool calling is not a simple HTTP call, but a closed loop consisting of model selection → structured parameters → business execution → result feedback → final answer. Simply testing whether the interface works is far from sufficient.

Core Principle: Decompose Tool Contracts into Five Layers

A production-ready Tool Contract should not be just name + parameters. A more robust decomposition has five layers:

Layer 1: Selection Contract

This determines when the model should and should not call this tool. It includes the tool name, description, namespace, boundary descriptions with other tools, and conditions for prohibiting calls.

Layer 2: Parameter Contract

This includes field types, required, enum, default values, nullable, format constraints, units, time ranges, ID formats, array lengths, etc. OpenAI’s documentation defines function parameters using JSON Schema, and Google’s function declarations are compatible with OpenAPI schema. These structured definitions form the basis of the parameter contract.

Layer 3: Execution Contract

This specifies whether the tool is idempotent, whether it writes data, whether it requires approval, whether retries are allowed, how timeouts are handled, and how error codes are returned. Many agent incidents aren’t caused by wrong parameters, but by the model treating a “query tool” as a “write tool,” or by repeated orders, emails, or charges during retries.

Layer 4: Return Contract

The tool’s return value not only provides programmatically parseable fields but also influences the model’s next reasoning step. The return value must be stable, short, and interpretable, and avoid stuffing internal stack traces, private fields, or irrelevant large objects back into the context.

Layer 5: Behavior Contract

This uses golden conversations and replay tests to describe “in these real scenarios, how should the model select tools, fill in fields, and handle failures.” This part cannot be fully derived from static schemas and must be validated based on real or synthetic trajectories.

Schema Compatibility Matrix: Assess Change Risk First

The first step before going live is not to run the model, but to perform a tool contract diff. Categorize each tool change into four types:

Risk Level	Typical Changes	Strategy
Low Risk	Adding descriptions, adding non-required fields, adding read-only return fields, fixing typos in docs	Static diff is sufficient, but description changes still need attention
Medium Risk	Adding required fields with default values, adding enum values, adjusting field format descriptions, changing tool description boundaries, adding similar tools	Requires golden conversation replay
High Risk	Deleting fields, renaming fields, changing field types, changing units, changing idempotency semantics, changing a read-only tool to a write tool, changing error code structure	Introduce a new tool version (e.g., create_invoice_v2)
Model-Sensitive Changes	Shortening tool names, making descriptions vague, overlapping boundaries of multiple tools, changing parameter names from business semantics to internal abbreviations	API layer may be compatible, but directly affects model selection

Use a simple contract metadata file to codify these rules:

tool: billing.create_invoice
version: 2.1.0
owner: billing-platform
risk_level: high
side_effect: write
idempotency_key: required
compatibility:
  removed_fields: forbidden
  renamed_fields: requires_new_tool_version
  new_optional_fields: allowed_with_replay
  new_required_fields: requires_default_or_new_version
  enum_expansion: requires_golden_replay
release_gate:
  schema_diff: pass
  golden_conversation_replay: pass
  sandbox_execution: pass
rollback_plan: required

This metadata doesn’t need to be complex, but it must be in CI. Otherwise, tool upgrades become “whoever changed it knows,” and problems only surface at agent runtime.

Golden Conversations: Save Full Trajectories, Not Just Prompts

The core asset of Tool Contract Testing is the golden conversation. It’s not a set of static prompts, but a set of complete, replayable trajectories.

A golden trajectory should include at least the following elements:

• User input
• System prompt
• Visible tool list
• Tool schema version
• Model configuration
• Expected tool to call
• Expected parameters
• Mock tool return value
• Expected final answer
• Forbidden behaviors
• Business assertions

Example:

{
  "case_id": "invoice_create_existing_customer_001",
  "user_message": "Generate a June SaaS subscription invoice for customer C1024, amount $299",
  "tool_catalog_version": "2026-07-09",
  "expected_tool": "billing.create_invoice_v2",
  "expected_arguments": {
    "customer_id": "C1024",
    "billing_period": "2026-06",
    "currency": "USD",
    "amount": 299
  },
  "forbidden_tools": [
    "billing.refund_payment",
    "billing.send_invoice_email"
  ],
  "mock_tool_result": {
    "invoice_id": "INV-202606-C1024",
    "status": "draft"
  },
  "assertions": [
    "must_not_send_email",
    "must_create_draft_invoice_only",
    "must_include_invoice_id_in_final_answer"
  ]
}

Note: This checks not only whether the fields match, but also which tools should NOT be called. In production agents, wrong tool selection is often more dangerous than incorrect parameter formatting.

Sandbox Replay: Execute Tools Without Touching Real Business

Golden conversations only validate model output; sandbox replay validates the tool execution chain. It’s recommended to split tool execution into three environments:

Environment Type	Purpose	Use Case
Mock Executor	Only validates parameter structure, returns fixed results	Fast CI
Stateful Sandbox	Uses isolated databases, fake email, fake payments, fake ticketing systems; validates write side effects and state changes	Daily regression and pre-release validation
Shadow Replay	Uses anonymized copies of real production requests; replays model selection and parameter generation without executing real side effects	Detects behavioral drift from description changes, tool list changes, or model upgrades

Don’t just record pass/fail for sandbox results. It’s more useful to track these metrics:

• Tool Selection Accuracy: Was the correct tool selected?
• Argument Exact Match: Do key parameters match exactly?
• Semantic Argument Match: Are time, amount, ID, and units semantically consistent?
• Forbidden Call Rate: Were forbidden tools called?
• Clarification Rate: Did the model ask for clarification when information was insufficient?
• Execution Success Rate: Could the tool complete in the sandbox?
• Side Effect Violation: Were any disallowed write operations performed?

These metrics are closer to production risk than “the model’s answer looks correct.”

Engineering Implementation: Integrate Tool Contract Testing into the Release Pipeline

A practical implementation flow can be broken down into six steps:

1. Tool Registry

Every tool must have a unique ID, version, owner, side effect level, schema, description, return structure, permission scope, and deprecation status. Don’t let agent code maintain tool definitions in a scattered way.

Use stable naming for tool IDs:

crm.search_customer.v1
billing.create_invoice.v2
calendar.create_event.v1
support.open_ticket.v1

Don’t rename tools frequently. For the model, the tool name is a semantic anchor.

2. Schema Diff Check

Every time a tool schema is modified, automatically compare the old and new versions. Flag changes that delete fields, change types, change required status, change enums, or change side effects with a risk level.

3. Golden Conversation Selection

Don’t replay all test cases in full. A better approach is to select by risk: prioritize high-frequency tools, write tools, similar tools, tools that have recently caused incidents, and tools with description changes.

4. Sandbox Execution

After the model outputs a tool call, don’t hit the real system directly. First, enter the sandbox executor to validate parameters, permissions, idempotency keys, and business state. Write tools must be checked for duplicate execution risk.

5. Release Gates

Risk Level	Minimum Gate Requirements
High Risk	Schema diff + golden conversation replay + sandbox execution + owner approval
Medium Risk	Schema diff + golden conversation replay
Low Risk	Static schema diff

6. Canary and Rollback

Tool upgrades should support canary deployment by tenant, traffic percentage, or tool version. When the forbidden call rate or argument mismatch rate increases, prioritize rolling back the tool catalog instead of waiting for a model-side fix.

Applicable Scenarios

Tool Contract Testing is suitable for: internal enterprise agent platforms, customer service agents, CRM/ERP operation assistants, code agents, data analysis agents, payment/order/scheduling automation, and any LLM application that calls external systems.

If your tools are read-only, few in number, and have low call consequences, you can start with a lightweight schema diff and a dozen golden conversations. If your tools write data, send emails, modify orders, change permissions, or trigger financial actions, you should make tool contract testing a hard release gate.

Common Misconceptions

Misconception 1: Valid JSON Schema Means the Tool is Usable

JSON Schema only validates structural legality. It doesn’t guarantee the model will select the correct tool or that field semantics are correct. customer_id and account_id are both string, but their business meanings are completely different.

Misconception 2: Only Testing Happy Paths

Real agent incidents often occur in scenarios with insufficient information, vague user expressions, insufficient permissions, tool timeouts, or empty results. Golden conversations must cover failure paths and clarification paths.

Misconception 3: More Tools is Always Better

OpenAI’s documentation reminds that function definitions enter the model context and consume input tokens. Too many tools not only increase costs but also increase the probability of model selection errors. The tool catalog should be tailored to the scenario, not expose all backend capabilities at once.

Misconception 4: Description is Just Documentation

For LLMs, the description is behavioral guidance. Modifying a description can change model selection, even if the schema hasn’t changed. This should trigger a replay test.

Misconception 5: Replay Results Equal Production Safety

Replay only covers known scenarios. In production, you still need to monitor tool call distribution, error rates, forbidden tool calls, anomalous parameters, user revocation rates, and human takeover rates.

Pre-Release Checklist

• Does the tool have a unique ID, owner, version, and side effect level?
• Has a schema diff been completed, and are breaking changes flagged?
• Do new required fields have default values or a new tool version name?
• Does the tool description specify applicable boundaries and forbidden scenarios?
• Are there similar tools that could cause selection confusion?
• Do golden conversations cover success, failure, clarification, insufficient permissions, and tool timeouts?
• Do write tools have idempotency keys, approval strategies, and duplicate execution protection?
• Is the sandbox isolated from real email, payments, orders, CRM, and databases?
• Are tool calls, arguments, tool results, final answers, and assertion results recorded?
• Is there a capability to roll back the tool catalog by version?

References

• OpenAI Function Calling
• Anthropic Tool Use
• Google Gemini Function Calling
• OpenAPI Specification v3.2.0
• ToolSpec: Accelerating Tool Calling via Schema-Aware and Retrieval-Augmented Speculative Decoding
• TSCG: Deterministic Tool-Schema Compilation for Agentic LLM Deployments