## TL;DR

Clients hard-code tool names; removing one without warning breaks them silently.
A deprecation window with a named replacement is the professional path.
Applies to MCP servers with existing client usage.

## The query

```text
how to deprecate an MCP tool gracefully
```

## Use this when

- A tool clients use needs replacing or removal.
- You can offer a named replacement.
- You want zero-surprise migration.

## Not for

- The tool is pre-release with no users (just remove it).
- Nobody uses the tool (check telemetry first; unused tools can go quietly).
- You are renaming for style reasons only (add an alias instead of deprecating).

## Steps

1. Announce the deprecation: name the tool, the replacement, and the removal date.
   Expected output: A dated notice clients can plan around.
2. Keep the old tool working during the window, returning a deprecation note in its output.
   Expected output: Clients keep working while being nudged to migrate.
3. Track old-tool usage and personally nudge the heaviest users before the deadline.
   Expected output: Usage trending to zero with no surprised stragglers.
4. Remove the tool on the announced date and monitor client error rates.
   Expected output: A clean removal with no error spike.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2aWIcB1T1DdWnGcnHb1r7w