How to update ChatGPT tools when your API changes

An API change is not only a backend event. It can change the tool name, the input schema, the output fields or the meaning of a result. Treat the source update as a contract review: compare what was approved, test the new operation and apply only the changes you can defend.

Why an API change is a contract change

A saved tool is a reviewed promise about inputs, outputs and behavior. When the API renames a field, removes a required parameter or changes a success response, the old promise may still render in the editor while failing at execution. The goal is not to mirror every upstream change automatically. The goal is to notice the difference, understand it and decide whether the tool should change.

Start from the saved baseline

For a newly sealed import, DraftYourApp keeps a signed baseline tied to the owner, tool, document and operation. The review compares that baseline with the saved tool and the new proposal. If the baseline is missing, tampered with or signed by a different key, the comparison reports baseline unknown and disables Apply. An editable provenance record is not enough to reconstruct an old unsigned import safely.

Read the three-way comparison

Each changed field can be creatorEdited, sourceChanged or both. A runtime field that the creator edited must use the tested source contract; it is not preserved silently. A conflict, where both sides changed the same field, needs an explicit decision. Name, title, description and statusMessages can keep creator wording, but any field marked as a conflict needs an explicit choice. A name changed by the source always needs manual review, because it can change how the model selects the tool. A field only the source changed can be previewed from the new contract. Apply never overwrites an unexamined conflict silently.

Example: a changed status field

Suppose a fictional status API previously returned status and updated_at, and the new document returns state and observed_at. The proposal changes the output schema even if the human-readable meaning looks similar. The comparison marks the enumerated tool fields that changed, such as the output schema; it does not detect references to old field names inside UI mappings or saved text. Review those descriptions and mappings manually. A creator may keep their wording, but a changed runtime schema must use the tested source contract. After Apply, update the result rendering and test a real response.

Test before you Apply

Review source update accepts the new JSON and shows saved and proposed values. Replacing creator-edited runtime fields requires accepting the source contract explicitly. Before Apply, supply parameters and run Test operation. Changing the document or parameters invalidates the visible result, and the API requires a current signed receipt for the exact document and operation. The receipt expires after fifteen minutes; a stale success is not evidence for this Apply.

Apply with concurrency in mind

Apply rechecks ownership, inspection, the signed baseline, the test receipt and every decision. It validates the tool and the complete collection before one conditional write. If the saved tool changed concurrently, the write returns a conflict rather than overwriting newer edits. Reload the saved version, review the differences again and do not retry blindly. This is optimistic concurrency, not automatic synchronization.

Retest and keep release evidence

After Apply, test the operation again with representative input and check the result in the interface. A passing UI preview does not prove remote execution. When you deploy, keep the tested source hash, operation, expected result and the release identity with the evidence. If the update is wrong, rollback is not universal: it depends on a compatible saved deployment bundle. Older or incompatible bundles may require a rebuild rather than an automatic reversal.

A step-by-step update

1. Save or identify the approved baseline and open Review source update.
2. Supply the new document for the same operation and compare saved, baseline and proposed values.
3. Resolve name and runtime conflicts explicitly; preserve intentional creator wording.
4. Enter representative parameters, run Test operation and inspect the validated result.
5. Apply before the receipt expires and handle a 409 by reloading rather than overwriting.
6. Retest the applied tool, deploy the reviewed release and retain the evidence.

Limits worth stating

This workflow covers supported public GET operations. It does not enable OAuth, writes, remote document fetching or automatic synchronization. A source change does not migrate an existing deployment, and a rollback may not be possible for older bundles. If the baseline is unknown, the safe action is to stop and rebuild the reviewed import rather than guessing.