Deprecation policy

An agent reads a contract once and then acts on it for months. This page says what Whisper does before changing that contract, and what to build so a change does not break you.

What counts as a breaking change

Only three things break an agent that was working:

1. Removing or renaming a tool. The call fails outright — the loudest and least dangerous case.
2. Removing or renaming a response field. The most dangerous case, because the call still succeeds. An agent that read results[].markdown and now finds it absent usually produces a confident answer built on less than it thinks it has.
3. Narrowing an accepted argument — dropping a value from an enum, or tightening a batch shape.

These are not breaking changes, and they ship without notice:

• A new tool, resource, prompt or response field. Responses are objects; an unknown key is not an error, and a client that treats one as an error is the thing to fix.
• A workflow entering or leaving the gallery. The gallery is curated continuously and moves independently of the connector. list_workflows is the index; a hard-coded slug list is your own cache going stale, not a contract change.
• A figure moving. Node counts, edge counts, feed and category counts change as the graph grows. Read them from whisper://stats.
• A data layer's coverage changing. A layer reporting degraded coverage is the system telling you the truth about itself. whisper://stats carries per-layer coverage for exactly this reason, and a coverage gap is a finding rather than a clean result.

What happens before something is removed

• It is announced on the connector changelog before it is removed, not alongside the removal, so a client that reads the log has warning rather than a post-mortem.
• The old shape keeps working alongside the new one wherever both can coexist — a renamed field is published under both names during the overlap, and a renamed tool answers under both names.
• The overlap is stated in the announcement itself, per change, because how long an old shape can be kept alive depends on what it is. A response field costs almost nothing to keep; a tool whose backing behaviour has been withdrawn cannot be kept honestly, and saying so is better than a blanket promise nothing can honour.
• Security is the exception, and it is announced as one. If a shape has to be withdrawn to close a security problem, it goes without an overlap and the changelog entry says that is what happened.

Build an agent that survives a change

Four habits, in the order they pay off:

• Discover, don't hard-code. Call tools/list and list_workflows at run time. Both are cheap; list_workflows with no argument returns the whole catalogue, uncapped.
• Read fields defensively. Treat every optional field as optional. If markdown is absent, fall back to steps[] and evidence[] rather than reporting a failure — or than reporting success on nothing.
• Never infer absence from a missing field. "The field is gone" and "the answer is no" look identical to a naive reader and mean opposite things. This is the same rule as Coverage: no data is not a clean verdict.
• Re-read the schema instead of remembering it. explain_schema answers in milliseconds and is cached server-side. A label or edge type your agent memorised last quarter may have been joined by others since.

Where changes are announced