Versioning

How GPS changes its connector's tools, results and error codes without breaking your prompts, skills or integrations.

Claude and ChatGPT cache tool lists, and people write prompts and skills against tool names. GPS's versioning rules keep those working.

What the contract is#

Each tool's contract is its:

• name;
• input schema;
• output shape (its structured content);
• annotations (the hints that say whether it reads, adds or replaces).

The refusal codes and the widget result contracts are part of the contract too.

Names are stable#

A published tool name is never renamed, and never reused for something else. Names are snake_case and at most 64 characters.

Additive changes#

These can happen at any time, without notice:

• a new tool;
• a new optional input;
• a new output field;
• a new value in an output's list of possible values;
• a wider accepted input range;
• better titles, descriptions or hints.

Clients must ignore output fields they don't know.

Breaking changes#

A breaking change is any of these:

• a tool or field removed or renamed;
• an input that becomes required;
• an input whose accepted values narrow;
• a field whose type or meaning changes;
• an annotation that loosens safety, for example a tool that stops being marked read-only;
• a changed default.

For a breaking change, GPS:

1. ships the new tool (for example get_x_v2) or the new field beside the old one;
2. marks the old one deprecated, starting its description with "Deprecated: use … (removed after YYYY-MM-DD)", and keeps its behavior unchanged;
3. keeps both for at least 90 days, then removes the old one;
4. records every step in the changelog.

Safety fixes#

A change that closes a security or privacy hole, such as reach into another organization, a stored file's address, or a permission on a write, ships at once, even if it breaks the contract. It still gets a changelog entry.

Widget results#

The results the in-chat views render carry a versioned contract, such as gps.scorecard/1: the shape's name and a number. A breaking change to the shape bumps the number, and GPS sends the old version for 90 days to hosts that have cached it.