AI uses for records
Tool-use dataset API schema changes: what to keep when a field is renamed
By SourceX Editorial · Updated
9 sections
Short answer
Store each tool call exactly as sent, tie it to an immutable, hashed snapshot of the contract it ran against, and record the rename as a dated mapping between two contracts. Never rewrite old arguments to the new name. Validate each call against its own contract, prove the business change with a read-back, and add adaptation tasks that start on the old contract and must succeed on the new one.
System export
Tool use dataset API schema
Key takeaways
- A field rename is a breaking change: the old name is removed and a new one added, even when the meaning is identical.
- Keep arguments exactly as sent and link each call to a hashed snapshot of the contract it ran against.
- Record each rename as a dated mapping that says whether the old name was translated or rejected afterwards.
- MCP tool definitions have no per-tool version field, so hash the definition captured before each call.
- Prove write calls with a read-back from the system of record, not a status code or an echoed response.
- Adaptation tasks that start on the old contract test what production agents actually face after a change.
How should a tool-use dataset preserve the API contract version after a field rename?
Keep every recorded call exactly as it was sent, attach it to an immutable snapshot of the contract it ran against, and record the rename as its own dated mapping between the two snapshots. Never rewrite old arguments into the new field name. Then add adaptation tasks that start from the old contract and require the agent to succeed against the new one, graded on the business state each call was meant to change.
That answer has three parts because a rename damages a dataset in three different ways. It corrupts history when someone normalizes old calls to the new name. It corrupts training when a model sees both names with no signal about which one is valid when. And it corrupts evaluation when a grader checks the new schema against calls that were correct on the day they ran.
The packet described below is meant for teams licensing or building tool-use records from real integrations: API call logs, integration run histories, MCP server traces and agent transcripts. It treats the contract as part of the record, not as documentation that lives somewhere else.
Why is a renamed field a breaking change and not a cosmetic one?
A rename removes one name and adds another, so any caller still using the old name breaks. Google's API design guidance says this outright: renaming a component is semantically equivalent to removing it and adding a new one, and existing components must not be removed within the same major version. Semantic Versioning reaches the same place from the other side, reserving a major version increment for incompatible API changes.
Real APIs do rename fields, and the old name does not always fail at once. Stripe's changelog for its 2026-07-29 Dahlia release renames the taxes parameter in industry metadata payment details to tax_items. Older API versions still convert the old name automatically; from the new version on, sending taxes returns a parameter_unknown error. A dataset that spans that release holds calls where taxes was correct, calls where it was silently translated, and calls where it was rejected.
Serialization adds a quieter version of the same problem. Protocol Buffers maps field names to lowerCamelCase JSON keys unless a json_name option overrides it, and conforming parsers accept both the JSON name and the original proto field name. Logs of the same field can therefore show two spellings that are not a rename at all. A dataset needs to tell a real contract change from an encoding difference, and only the contract snapshot can settle that.
Where does the contract version actually live for each kind of tool?
It depends on the interface, and in several common cases there is no single version field to copy. The table lists what to capture so the version a call ran against can be reconstructed later.
| Interface | What carries the version | The trap | What the record must store |
|---|---|---|---|
| REST API described by OpenAPI | The info.version field of the OpenAPI document | The 3.1.1 specification defines info.version as the version of the document, distinct from the version of the API it describes | The full OpenAPI document as served, its hash, info.version and any separate API version the provider publishes |
| Date-versioned REST API such as Stripe | A version header on the request, or the account default when no header is sent | Calls without the header take whatever default the account had at that moment, which logs rarely show | The header value if present, otherwise the account default in force at call time and where that value came from |
| gRPC or Protocol Buffers | The .proto files at a given commit; field numbers identify fields on the wire | JSON logs may use the proto name or the lowerCamelCase name for the same field | The .proto set at the deployed commit, plus a field-number map so names can be resolved |
| MCP server tools | The tool definition returned by tools/list, plus the protocol version on each request | Tool definitions carry name, description, inputSchema and outputSchema but no per-tool version field, and the list may change over time | A hash of the exact tool definition returned before the call, and the protocol version declared on the request |
| Vendor SDK wrapping an API | The SDK release, which may pin an API version | The SDK can translate field names before the request leaves the client | SDK name and version, the pinned API version, and the wire request as sent rather than the SDK call |
| Internal service with no published spec | Usually a deploy or commit identifier | Nothing outside the code says when a field changed | Deploy identifier, the request and response schemas extracted at that deploy, and an owner who can confirm them |
What should the tool schema version and adaptation task packet include?
The packet has two record types. A contract record is written once per distinct contract and never edited. A call record points to exactly one contract record and stores the call as it happened. A rename is a third, small record that links two contracts and says what moved where.
| Field | Record type | Purpose | Validation rule |
|---|---|---|---|
| contract_id and contract_hash | Contract | Identifies one immutable snapshot of the schema a tool exposed | Hash recomputes from the stored snapshot; any edit produces a new contract_id |
| version_label and version_source | Contract | Human label (for example 2026-07-29.dahlia or 3.4.0) and where it came from: header, account default, SDK pin, tools/list or deploy | version_source is one of the allowed values; inferred labels are flagged as inferred |
| effective_from and effective_to | Contract | The window in which calls used this contract | Windows for one tool do not overlap unless a migration window is declared |
| field_map | Rename | Old path, new path, change type (rename, rename with shape change, split, merge) and whether meaning is unchanged | Every old path in the map exists in the old contract and every new path in the new one |
| accepted_aliases | Rename | Whether the old name is still accepted, translated or rejected after the change, and from which version | Must cite a changelog entry or a recorded rejection response |
| contract_ref | Call | Points the call at the contract it actually ran against | Arguments validate against that contract's input schema, not the latest one |
| arguments_as_sent and response_as_received | Call | The literal request and response after redaction | No field names differ from the wire capture; normalized copies live in a separate derived field |
| state_check | Call | A read-back or system-of-record lookup proving the intended business change happened | Present for every write call; status code alone does not pass |
| adaptation_task_ref | Call | Links calls used as demonstrations or test items in an adaptation task | Task's start contract and target contract both exist and are linked by a rename record |
Worked record: customer_ref becomes account_id (illustrative)
The following example is invented for illustration. It is not customer data and the tool is hypothetical. A fulfillment team exposes an MCP tool called update_shipping_address. In contract C-17 the input schema has customer_ref, order_id and address. On a given date the server replaces it with contract C-18, where customer_ref becomes account_id with the same meaning; the server translates the old name for a declared migration window and rejects it afterwards.
At a glance
Worked record: customer_ref becomes account_id (illustrative)
The dataset then holds three kinds of calls, and each one validates against its own contract. The list below is one valid record set for that change.
- Contract C-17: tool definition snapshot with hash, version_source tools/list, effective_from the first captured call, effective_to the switch date.
- Contract C-18: new snapshot and hash, version_source tools/list, effective_from the switch date, no end date.
- Rename R-4: old path customer_ref, new path account_id, change type rename, meaning unchanged, accepted_aliases translated during the migration window and rejected after it, with the rejection response stored as evidence.
- Call before the switch: arguments_as_sent use customer_ref, contract_ref C-17, state_check reads the order back and finds the new address.
- Call during the window: arguments_as_sent still use customer_ref, contract_ref C-18, accepted_aliases records the translation, state_check passes.
- Call after the window: an agent sends customer_ref, receives a validation error, retries with account_id, and the state_check confirms one address change, not two.
- Adaptation task T-9: a demonstration under C-17 plus the C-18 definition; the agent must update an address under C-18 and is graded on the order's stored address.
Does a successful response prove the address actually changed?
A follow-up read from the system of record proves it; a success code, a confident final message or a valid-looking response body does not. For a write call the state_check field should name the record read back, the field compared and the expected value, so a reviewer can repeat the comparison.
Structured outputs help but are not the same thing. The MCP specification says that when a tool declares an outputSchema, servers must return structured results that conform to it and clients should validate them. That validation proves the response had the declared shape under that contract. It says nothing about whether the shipping address in the order system changed, which is why the read-back is a separate field.
Renames make the gap wider. A server that translates an old field name may accept a call and return a well-formed result while writing to a default or ignoring the value, depending on how the translation was built. Only the state check catches that, and only if it compares the business field rather than the echo in the response.
Which validator checks catch a broken record, and what does one look like?
Run these checks on every call record before a dataset is accepted. Each is mechanical, so they can sit in the delivery pipeline rather than in a reviewer's head.
- Contract integrity: recompute contract_hash from the stored snapshot; mismatch fails the contract and every call that points to it.
- Own-contract validation: validate arguments_as_sent against the referenced contract's input schema and response_as_received against its output schema where one exists.
- Window check: the call timestamp falls inside the referenced contract's effective window, or inside a declared migration window.
- Name drift: any field name in arguments_as_sent that is absent from the referenced contract must appear as an old path in a rename record with accepted_aliases evidence.
- No retroactive edits: compare arguments_as_sent with the raw capture; any difference fails the record.
- State evidence: every write call has a state_check with a read-back target, a compared field and a result.
| Failing record (illustrative) | What the record shows | Check that fails | Correct repair |
|---|---|---|---|
| Normalized history | A call from before the switch shows account_id, with contract_ref C-17 | Own-contract validation and no retroactive edits | Restore the raw arguments; keep any normalized copy in a derived field |
| Floating contract | contract_ref points to latest rather than C-17 or C-18 | Contract integrity, since latest has no fixed hash | Resolve the contract from the call timestamp and tools/list capture |
| Silent default | A header-less call has no version, and the account default at that time is unknown | Window check cannot run | Mark the version as inferred, or exclude the call from training splits |
| Echo as proof | state_check compares the response body to the request | State evidence, because no system-of-record read exists | Add a read-back of the order record or drop the call from write-task sets |
How do adaptation tasks test whether an agent copes with the rename?
They put the agent where production agents end up: holding examples or memories from the old contract while the live tool exposes the new one. Each task fixes a start contract, a target contract, a sandboxed system state and an expected end state.
Keep tasks from one rename in the same split. If a demonstration from C-17 lands in training and the matching C-18 task lands in the test set, the score measures recall of that rename rather than adaptation to an unseen one.
| Task type | Setup | Pass condition | Common failure |
|---|---|---|---|
| Stale demonstration | Demonstration uses the old name; live tool definition uses the new one | Agent reads the current definition and sends the new name once | Agent copies the old name from the example |
| Rejection recovery | Old name is rejected with a validation error | One corrected retry and a single state change | Repeated retries or a duplicate write |
| Translated alias | Old name still accepted during a migration window | Business state correct; agent prefers the new name when both are documented | Agent treats the deprecation notice as an error and stops |
| Rename with shape change | Field renamed and changed from a list to a single object | Arguments match the new shape and the state check passes | Agent renames the key but keeps the old shape |
| Look-alike non-rename | Same field logged in proto name and JSON name | Agent does not treat the spelling difference as a contract change | Agent invents a migration that was never needed |
Where does this leave a buyer sourcing real tool-call records?
Ask for contracts before volume. A sample of call logs is only usable for tool-use training if the supplier can produce the schema snapshots, changelog evidence or deploy history that dates each call to a contract; logs alone usually cannot be repaired later. The OpenAPI deprecated flag, which marks a parameter that should be transitioned out of usage, and published changelogs are the cheapest evidence to request.
Where usable tool-call logs do not yet exist in a buyer's hands, SourceX can look for them at U.S. businesses on request, since it holds no datasets in stock. The request form is where a buyer sets out scope, volume, format, timing and licensing needs, including the contract history each call must carry, and a supplying company approves scope and terms in a signed agreement before delivery.
Frequently asked questions
Should I rewrite old tool calls to use the new field name?
No. Keep the arguments exactly as sent and point each call at the contract it ran against. If a training pipeline needs one spelling, add a derived, normalized copy alongside the raw call and label it as derived, so validation and audit still use the original.
Is an MCP tool definition versioned?
Not with a dedicated field. The MCP specification defines a tool by name, title, description, input and output schemas and annotations, and the set returned by tools/list may change over time. Hash the definition captured before each call and store the protocol version declared on the request.
Is info.version in an OpenAPI document the API version?
Not necessarily. The OpenAPI 3.1.1 specification describes info.version as the version of the OpenAPI document, distinct from the version of the API being described. Store it, but also store any API version the provider publishes separately.
How do I tell a real rename from a serialization difference?
Compare the two contract snapshots. In Protocol Buffers JSON, the same field can appear under its proto name or its lowerCamelCase JSON name and parsers accept both, so a spelling change in logs is not proof of a rename unless the schema itself changed.
What if the supplier cannot say which API version a call used?
Mark the version as inferred and record the evidence used, such as the SDK release or deploy date. Keep inferred calls out of evaluation sets and consider excluding them from training splits that teach schema handling.
Sources
- Google's API design guidance treats renaming a component as removing it and adding a new one, and forbids removing components within a major version. Source
- Semantic Versioning increments the major version for incompatible API changes and forbids modifying a released version's contents. Source
- Stripe's 2026-07-29 changelog renames taxes to tax_items; older API versions convert the old name and newer ones reject it with parameter_unknown. Source
- Stripe applies the Stripe-Version header when sent and otherwise the account's default API version. Source
- Protocol Buffers JSON uses lowerCamelCase or json_name keys, and parsers accept both that name and the original field name. Source
- Protocol Buffers guidance says to reserve deleted field numbers and names so JSON and TextFormat encodings keep parsing. Source
- OpenAPI 3.1.1 defines info.version as the document version, distinct from the API version, and marks deprecated parameters for transition out of use. Source
- The MCP tools specification defines tool definitions, the list-changed notification, and output schema conformance and validation. Source
- MCP requests declare the protocol version they use, and servers reject unsupported versions. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.