Versioning

How Signal's connector changes tools, change actions, prompts and widgets without breaking the prompts and habits built on them.

View as Markdown Open in Claude Open in ChatGPT

Assistants cache what Signal's connector offers. Claude and ChatGPT keep a connection's tool list, and people write prompts, skills and habits against tool names. These rules keep those working from one release to the next.

What the contract covers#

Item	The contract
Tool	Its name, its input schema, its output (structured content and text, field by field), its annotations, its area, whether it reads or writes, and whether View only connections are shown it
Change action	Its name, its fields, what its card says it will do, what it needs (role permission, plan, module) and its undo rule
Prompt	Its name, its arguments, and the tools and change actions it names
Widget	Its id and resource (`ui://signal/<id>.html`), the tools that link it, the fields it reads, and the MCP Apps protocol version. Each widget's payload is versioned `signal.<id>/<N>`.
Refusal codes	The `code` a refused or failed call answers with
Resources	Their URIs and what they hold

The connector's address (https://crm.empiraa.app/mcp), its OAuth endpoints and its scopes (signal:read, signal:write, offline_access) are part of the contract too.

The rules#

Names never change. A published tool, change action, prompt, widget id or refusal code is never renamed, and never reused for something else, even after it's removed.
Additive changes ship at any time, with a changelog entry:
- a new tool, change action, prompt or widget
- a new optional input or argument
- a new output field (clients must ignore fields they don't know)
- a new value in an output's list of values
- a wider accepted input, such as a longer limit or a new accepted value
- a clearer title or description, or a card or widget that reads better
Breaking changes get a new name and 90 days' overlap. A change is breaking when someone who relied on the old behavior could be hurt by it:
- removing or renaming an item or a field
- a newly required input
- a narrower accepted input
- a field whose type or meaning changes
- a changed default
- an annotation that loosens safety
- a change action that changes more than its card used to say, or whose undo rule gets narrower
- a widget payload a version-1 widget can't draw
The new item ships beside the old one (for example list_deals_v2, or a widget's signal.<id>/2). The old one's description starts "Deprecated: use … (removed after YYYY-MM-DD)" and its behavior stays exactly as it was. Both stay for at least 90 days, and each step is in the changelog.
Change actions follow the same rules, because clients cache them too.
Safety and privacy fixes are the exception. A fix that closes a security or privacy hole ships at once, even when it breaks the contract. Its changelog entry says what changed, without the details of the hole.
Signal's own rules still win. A role, plan, module or workspace switch that refuses a call isn't a contract change. The refusal codes are the contract, not whether a particular person gets a yes.

Version numbers#

The connector has no version number of its own. Its version is the release, and each changelog entry is one release. The server name and version a client sees in initialize are informational.
Widgets are versioned per payload (signal.<id>/<N>). Every widget at launch is version 1.
The tool reference always matches the code. It's generated from the connector's registries.