---
title: Versioning
description: How GPS changes its connector's tools, results and error codes without breaking your prompts, skills or integrations.
product: gps
section: mcp
order: 8
---

# Versioning

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](how-it-works.md#refusals) and the [widget result contracts](prompts-resources-widgets.md#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](changelog.md).

## 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.