Versioning and Deprecating Agent Tools Without Breaking Agents
Tool calls are a published contract consumed by models, prompts, evals, and saved agent graphs.
A silent schema change looks like a model regression. Use this cheatsheet when you rename fields, tighten validation, or retire a tool.
How to Use This Cheatsheet
- Treat tool name + parameter schema + result shape as a semver-like surface.
- Prefer additive changes; use a new tool name for breaking changes.
- Dual-run old and new tools during migration windows.
- Re-run agent eval suites before removing the old path.
- Record owners and sunset dates in the tool registry.
A - What Counts as Breaking
| Change | Break risk | Safe pattern |
|---|---|---|
| Add optional parameter | Low | Document default; keep old callers valid |
| Add required parameter | High | New tool name or long dual-support with default |
| Remove / rename parameter | High | Accept both names, then new tool |
| Tighten types (string → enum) | Medium-high | Expand enums carefully; dual-parse |
| Rename tool | High | Alias old name to handler; deprecate |
| Change result field names | High | Return both shapes or version results |
| Change side-effect semantics | High | New tool (create_ticket_v2) |
| Narrow auth / permissions | Medium | Expect more AUTH errors; update prompts |
| Raise stricter validation | Medium | Better errors; watch failure rate |
B - Versioning Strategies
| Strategy | How | When |
|---|---|---|
| Name suffix | get_order → get_order_v2 | Clear breaks; multi-agent fleets |
| Date stamp | search_docs_202603 | Infrequent freezes |
| Namespace | billing.create_invoice vs billing.create_invoice.v2 | Large catalogs |
| Schema version field | schema_version: 2 inside args | Only if runtime routes carefully |
| Facade stability | External name stable; internal rewrite | Best for minor evolutions |
Rule of thumb: models key off the tool name string. Renaming is a hard break even if the handler is identical.
C - Additive Evolution Checklist
- 1. Optional fields only for in-place upgrades when possible.
- 2. Defaults in the host if the model omits new optionals.
- 3. Descriptions updated the same release as schema changes.
- 4. Result additive fields (
currencyadded next tototal_cents) without removing old keys. - 5. Feature flags to expose new tools to canary agents first.
- 6. Contract tests asserting JSON Schema fixtures still validate.
- 7. Eval subset that exercises the changed tool paths.
- 8. Changelog entry in the tool registry with owner + date.
D - Deprecation Timeline
| Phase | Actions | Agents see |
|---|---|---|
| Announce | Mark deprecated in description; registry + Slack/docs | Old + new tools |
| Dual serve | Both names call compatible handlers | Prefer new in prompts |
| Steer | Prompts/system instructions mention new tool only | Old still works |
| Monitor | Metrics: call counts of old vs new | Traffic should shift |
| Remove | Drop old tool from catalog after idle threshold | New only |
| Clean | Delete dead aliases; archive schema fixtures | - |
Minimum dual-serve window: long enough to cover your slowest deployed agent config (often weeks, not hours).
E - Description and Prompt Hygiene During Migration
DEPRECATED: prefer get_order_v2. get_order remains until 2026-09-01.
Returns legacy shape without line_items.- Put deprecation first in the description so models notice.
- Do not leave two tools with identical descriptions; models pick arbitrarily.
- Update few-shot examples and saved graphs in the same PR as the schema.
F - Runtime Compatibility Snippets
Accept old and new argument names temporarily:
def get_order_args(raw: dict) -> int:
# Compatibility shim during deprecation
if "order_id" in raw:
return int(raw["order_id"])
if "id" in raw: # legacy
return int(raw["id"])
raise ValueError("order_id required")Alias registration:
HANDLERS = {
"get_order": get_order_v2_handler, # legacy name
"get_order_v2": get_order_v2_handler, # current
}Return dual result keys only briefly; long dual shapes bloat tokens.
G - Removal Gates
Do not delete a tool until:
| Gate | Signal |
|---|---|
| Traffic | Old tool calls ≈ 0 for N days (per env) |
| Evals | Full suite green with new tool only |
| Config | No prod prompt/graph references old name (search repo + prompt store) |
| External | MCP clients / partner agents notified |
| Rollback | Re-add path documented if you must hot-fix |
H - Anti-Patterns
- Editing a required field in place on Friday with no dual-run.
- Recycling a tool name for unrelated behavior ("search" now writes).
- Deprecating in code comments only (models never read those).
- Shipping v2 without migrating eval fixtures.
- Different environments on different major tool versions without routing.
FAQs
Should tool versions match API semver?
Not necessarily. Version the agent contract. A backend v3 can still back get_order_v2 if the tool shape is stable.
Is adding an enum value breaking?
Usually non-breaking for callers. Removing or renaming an enum value is breaking for models that still emit the old token.
How do MCP servers version tools?
Publish clear names and changelogs; clients cache catalogs. Bump names or use explicit version metadata your clients understand; verify client refresh behavior at build.
Can I keep one tool and branch on a version argument?
Possible but models often omit it. Prefer explicit names for majors; use version only for negotiated advanced clients.
What if a silent break already shipped?
Reintroduce the old schema under the old name, dual-serve, and hot-fix prompts. Add contract tests so it cannot recur.
Do result-only changes need versioning?
Yes if agents parse fields or later tools depend on keys. Additive keys are safer than renames.
How should multi-agent platforms coordinate?
Central tool registry with owners, schemas, deprecation dates, and consumers. No ad-hoc edits on shared tools.
Are prompt-only tools (text protocols) versioned the same way?
Yes. Text protocols break just as hard; pin protocol version strings in the system prompt and parsers.
Related
Related: What Makes an Internal API a Good Agent Tool
Related: Wrapping a REST API as an Agent Tool
Related: Custom Tools Basics
Related: Custom Tools Best Practices
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.