THE CORE AIM OF VOCABULARY MASTERY · AI TOOL CONTRACT VERSIONING · DEFINE → CHANGE → TEST → MIGRATE → RETIRE
Imagine a vocabulary teaching assistant that worked perfectly yesterday. It looks up a science glossary, receives a list of words and creates practice questions. Today, the external glossary tool has changed one field from word to term. The assistant still calls the right tool, yet its next step receives a result it cannot understand. Nobody changed the student’s question. The problem is a broken tool contract.
AI tool contract versioning vocabulary explains how software teams manage these changes without silently disrupting the applications, agents and learners that depend on them. Terms such as interface contract, input schema, output schema, breaking change, backward compatibility, deprecation, migration, adapter, version pinning, contract test and change log are useful because a small-looking change to an API can break an entire educational workflow.
The core aim of vocabulary mastery for AI tool contract versioning is continuity of meaning across software changes. A learner should be able to identify what a client expected, what a provider changed, whether existing clients can still operate, how the change should be tested and when an old interface can safely be withdrawn. The goal is not to preserve outdated software forever. It is to improve systems without surprising the people and programs relying on them.
This guide extends AI Tool Discovery Vocabulary and AI Tool Calling Vocabulary in the eduKateSG Vocabulary Hub. Discovery tells an assistant which operations exist. Calling explains how an operation is requested. This article owns a different question: what happens when the operation’s meaning or structure changes over time?
Central proposition: An interface is trustworthy when its consumers can understand and validate what it promises—and when changes to those promises are made visible, tested and migrated deliberately.
A one-minute router for understanding versioned tools
- Identify the contract: tool name, arguments, types, results, errors and side-effect behavior.
- Classify the change: documentation change, compatible extension, behavioral change or breaking revision.
- Map dependants: agents, prompts, validators, workflows and documentation using the contract.
- Test compatibility: old client with new tool, new client with old tool and representative failure cases.
- Migrate safely: adapter, staged rollout, updated schemas and controlled fallback.
- Retire with evidence: confirm no unsupported clients or obsolete permissions remain.
The essential glossary of tool contract versioning
| Word | Meaning | What it helps you decide |
|---|---|---|
| Interface contract | The agreed inputs, outputs and behavior of an operation. | What was the tool supposed to do? |
| Input schema | The permitted argument names, types and constraints. | Can the request be accepted? |
| Output schema | The structure a receiving application expects from the result. | Can the response be interpreted? |
| Required field | A value that must be supplied or returned. | Which omissions must fail validation? |
| Optional field | A value that may be absent under the contract. | Can older clients ignore this addition? |
| Enum | A field limited to specified named values. | What happens if a new status appears? |
| Semantic contract | The intended meaning of an operation and its fields. | Does ‘confirmed’ still mean confirmed? |
| Breaking change | A revision that prevents a previously valid consumer from working as intended. | Must existing clients migrate? |
| Backward compatibility | New software still supports older valid consumers within its documented scope. | Will yesterday’s client continue? |
| Forward compatibility | An older consumer can tolerate certain later extensions. | Can unknown optional fields be ignored? |
| Deprecation | A notice that a feature should be replaced and may be removed. | When should new work stop using it? |
| Sunset | A planned endpoint for support or availability. | When does migration become necessary? |
| Version pinning | Selecting a specific supported version of a dependency. | Which behavior did we actually test? |
| Semantic versioning | A conventional way of communicating version changes in some packages. | What does a major revision signal under this project’s policy? |
| Adapter | A component that translates between two interfaces. | Can old and new formats coexist temporarily? |
| Contract test | A test that checks the implementation against its defined interface. | Does the provider still meet its promise? |
| Consumer-driven contract | Expectations described from the perspective of software using the service. | Which fields do clients truly depend on? |
| Canary rollout | Releasing a change first to a limited portion of traffic. | Can problems be detected before wider adoption? |
| Feature flag | A controlled switch for selecting behavior or availability. | Can a rollout be paused? |
| Change log | A record of what changed and why. | How can future operators understand this revision? |
| Migration guide | Instructions for switching dependent systems safely. | How should consumers adapt? |
| Rollback | Returning an operation or deployment to an earlier supported state. | Can the change be reversed safely? |
| Compatibility window | A period during which old and new versions coexist. | How long do clients have to move? |
The deeper idea: a contract is more than a JSON shape
A schema may say that a returned field called status is a string. That is structural information. But users also need to know which values mean proposed, confirmed, cancelled or failed. If a provider silently changes confirmed to include bookings that are still awaiting staff review, a client might show a successful reservation too early. The JSON can remain perfectly valid while the meaning has broken.
This is why semantic compatibility matters. A contract encompasses documented meaning, error behavior, authorization expectations and side effects where relevant. A tool that used to read an article but now edits the article has changed its risk profile even if its arguments still parse. A mature team reviews what the operation does, not just what its fields look like.
Four changes that look similar but are very different
| Change | Typical compatibility effect | What to check |
|---|---|---|
| Clarify a misleading description without changing behavior | Often compatible, but agents may choose the tool differently. | Tool-selection evaluations and documentation. |
| Add an optional result field | Often compatible for consumers that ignore unknown fields. | Whether strict parsers reject additional keys. |
| Rename a required parameter | Usually breaking unless an alias is supported. | All callers, stored prompts and validators. |
| Change the meaning of an existing status | Potentially breaking despite unchanged schema. | Downstream decisions and external consequences. |
| Add a new enum value | May break consumers that assume a closed set. | Exhaustive switches and failure handling. |
| Require stronger authorization | Can intentionally reject formerly permitted calls. | Updated scopes, user expectations and migration. |
| Make a read-only operation write data | High-risk behavior change. | Separate operation name, permissions and approval gates. |
Worked example: the eduKate glossary connector changes
Suppose an education assistant requests vocabulary for a Secondary 1 student. The old tool returns an object with word, definition and level. A new release returns term, meaning and curriculum_level. The new names might be clearer to developers, but an older teaching packet generator may still look for word. A blank worksheet could appear even though the search was successful.
An adapter can map the new fields into the old consumer format during a transition. But the team should also check the intended meaning: does curriculum_level refer to Singapore school year, an international grade, a language-proficiency scale or something else? Field translation without meaning translation may silently route the wrong vocabulary to a child.
| Stage | Practical question | Safe result |
|---|---|---|
| Inventory | Which articles, lessons or agents call the old glossary tool? | Dependency list with owners. |
| Schema comparison | Which fields and types changed? | Documented input and output differences. |
| Meaning check | Has the interpretation of ‘level’ changed? | Explicit education-level mapping. |
| Consumer test | Does the old worksheet generator still work? | Passing regression examples or a known failure. |
| Transition | Can old consumers use an adapter? | Bounded compatibility path. |
| Release | Which version is enabled for which agent? | Versioned deployment and records. |
| Retirement | Are any clients still using the old endpoint? | Verified discontinuation, not an assumption. |
A second example: a publishing tool changes its default status
A content-management tool previously created drafts when no publication status was specified. Imagine an update starts publishing immediately by default. Existing agents that only supplied a title and content could now place unreviewed text on a public site. The new interface may still accept every old request. But the changed default has broken a consequential behavioral contract.
A robust publishing workflow should specify the intended status explicitly, enforce authorization and inspect the actual returned post status. Contract versioning alone is not a substitute for safe external permissions. What makes this example important is the interaction between an interface change and a real-world side effect: a default value can be more consequential than a renamed field.
Backward compatibility does not mean preserving every historical mistake
Teams sometimes preserve an interface indefinitely because breaking consumers feels risky. But an old endpoint may expose data too broadly, lack provenance or use a misleading error format. Maintaining it can also create operational risk. Compatibility should be evaluated against current requirements, not treated as a perpetual entitlement.
If an unsafe behavior must be withdrawn immediately, the application may need to restrict access before the whole migration is finished. The change notice should distinguish an urgent security restriction from a planned feature retirement. Users need a correct explanation and a supported replacement, not an assurance that nothing ever changes.
How MCP fits this topic without being confused with a tool version
The Model Context Protocol defines conventions for clients and servers that exchange tools, resources and other context. A protocol specification revision is not identical to the version of a particular WordPress or curriculum tool. A server’s tool schema may evolve independently of the protocol under which that schema is advertised.
In 2026, MCP’s July specification revision included changes relevant to how implementations discover and cache tool lists. Clients and servers need to follow the compatible specification they actually support. Separately, a specific tool might add an optional field or deprecate an operation. A good operator can distinguish protocol version, SDK version, tool contract version and source document version instead of calling all four ‘the API version’.
The four versions an educational assistant may encounter
| Version type | Example | Failure if mixed up |
|---|---|---|
| Protocol version | MCP implementation revision. | Client and server disagree about transport or discovery conventions. |
| SDK version | Application’s installed agent library release. | Runtime behavior or supported options differ. |
| Tool version | Curriculum lookup interface revision. | Arguments or results do not match the consumer. |
| Content version | Current syllabus or vocabulary reference edition. | Correct tool returns outdated educational facts. |
Contract tests should cover more than the happy path
A simple test that checks whether a tool returns something after a query is not enough. Representative contract tests should cover valid inputs, missing required fields, unknown enum values, authorization failures, empty results, timeouts and meaningful side effects. A change that passes a single well-formed query may still fail the actual parent’s request.
- Test a current client against the proposed new tool implementation.
- Where practical, test supported old clients against the new interface.
- Check rejected and invalid inputs—not only successful examples.
- Check authorization behavior and read/write classification.
- Verify that status and date fields retain their documented meaning.
- Test the consuming workflow’s final output, not just the raw JSON.
- Record test versions and the expected result for repeatable analysis.
- Include an educational-level mapping test when curriculum terms change.
The contract migration ladder
A practical transition begins by announcing the change and identifying affected consumers. Next, add compatibility support where safe, update and test the clients, deploy gradually, monitor errors, and close the old path only when supported dependencies have moved. A migration can be staged rather than simultaneous. The precise overlap period depends on risk, users and operating constraints.
Documentation should say what changed, which former assumptions are no longer valid, what new field or operation replaces them, and what consumers should do if they cannot upgrade immediately. A useful migration guide includes specific before-and-after examples rather than simply saying ‘use the new API’.
Common contract-change mistakes
- Changing a required field name without a migration: existing clients may break.
- Assuming every added field is harmless: strict parsers may reject unknown keys.
- Confusing format compatibility with meaning compatibility: unchanged JSON can express changed policy.
- Ignoring default behavior: an omitted status might become a public write.
- Removing a tool from discovery without dependency mapping: hidden clients can fail later.
- Pinning a version without security review: stability alone does not prove suitability.
- Publishing a change log but no migration guidance: operators cannot act on the notice.
- Assuming a passing unit test proves the whole workflow: run end-to-end checks.
- Leaving retired credentials active: complete the operational exit, not only the visible API change.
Frequently asked questions
What is AI tool contract versioning?
It is the practice of describing, testing and managing changes to a tool’s inputs, outputs, behavior and compatibility over time.
Is a schema change always a breaking change?
No. Some optional extensions are compatible, depending on the consumer. Renaming required fields or changing semantics can break existing workflows.
What is the difference between a tool version and an MCP protocol version?
The protocol governs how participating applications communicate; a tool contract describes one exposed capability and can evolve independently.
Why should an education platform care about API versions?
Because a small interface change can break teaching packets, misroute school levels or cause an authorised operation to be reported incorrectly.
Can an adapter avoid every migration?
No. An adapter can translate formats but may not safely reproduce a changed meaning, permission policy or side effect.
When should an old tool be retired?
When a supported migration or justified restriction has been completed and relevant dependencies, permissions and residual risks are addressed.
Standards, documentation and connected learning
- Model Context Protocol — Tools specification (current discovery and tool-definition context).
- MCP — July 2026 specification update (documented protocol evolution).
- Semantic Versioning specification (one established version-signalling convention, not a universal API guarantee).
- AI Tool Discovery Vocabulary (finding and understanding available tools).
- AI Tool Output Validation Vocabulary (checking returned values).
- AI Change Management Vocabulary (operational transitions).
- AI Model Retirement Vocabulary (the related but distinct model-lifecycle problem).
- Immutable eduKateSG teaching reference (clarity-first explanation and diagnosis).
The AI tool contract versioning vocabulary standard
Mastery is demonstrated when a learner can compare an old and new contract, identify the specific kind of breakage, test a realistic consumer, explain an adapter’s limits, state the required migration steps and distinguish a tool-version change from a change in the underlying educational source. The practical reward is simple: learners keep receiving correct, usable help even as the systems behind it improve.