A tool schema change can break an older agent even when the backend deployment succeeds. Treat the schema, response meanings, and running conversation versions as one compatibility contract.
Compatibility includes meaning as well as shape
Tool-schema compatibility means that an agent and execution service agree about accepted arguments and returned outcomes. Renaming a required field is an obvious break. Changing a timestamp’s timezone meaning or returning “accepted” where “completed” was expected can be equally damaging.
For a proposed release process, version the contract independently from the prompt. Record which agent releases use each version. Validate incoming arguments against the selected contract, then adapt them into an internal domain model. Keep response semantics stable for the life of that version.
Adding an optional field may be compatible, but only if defaults preserve existing behaviour. An optional cancellation reason that silently changes refund eligibility is a behavioural change, even if an old payload still parses.
Exercise a fictional booking migration
Version one accepts a local date and an explicitly configured business timezone. Version two accepts an offset-aware timestamp. During a rolling deployment, an old conversation may still send the original fields after the new backend is live.
The service can retain a version-one adapter temporarily or reject the unsupported version safely. It must not reinterpret the old local date as UTC. Maintain fixtures that demonstrate the intended appointment instant for both versions.
| Change | Compatibility question |
|---|---|
| New optional field | Does omission preserve the old outcome? |
| Renamed required identifier | Is an adapter available for older agents? |
| New response status | Can old agents handle it safely? |
| Narrower accepted enum | Which existing conversations will now fail? |
| Removed contract version | Have all dependent sessions ended? |
Test old-agent/new-service and new-agent/old-service combinations when the deployment strategy permits both. A test covering only matching latest versions misses the transition risk.
Deprecation needs an observable endpoint
Track requests by contract version without placing unnecessary caller data in telemetry. Announce an internal retirement condition, such as no supported active sessions using the older version. Long-running jobs and retries may outlive the voice connection, so include them in the decision.
Adapters add maintenance burden and can hide incompatible assumptions if kept indefinitely. Set a removal plan and test the adapter’s domain behaviour, rather than merely checking that it produces valid JSON.
This migration method is proposed. The voice integration case study provides related context. For response-side detail, review reliable tool response design.
Tool compatibility FAQ
Is adding a field always safe?
No. Defaults, validation behaviour, and downstream meaning determine whether the change preserves the contract.
Should the prompt version identify the tool schema?
Record the relationship explicitly. A prompt release and a tool-contract release need not have identical lifecycles.
What should happen to an unsupported payload?
Reject it with a safe, recognisable error or use an intentional tested adapter. Do not guess its meaning.