From 3e0ceb3f591d30513ce5f9b9fabdfb057be7ea3c Mon Sep 17 00:00:00 2001
From: tommaso-moro <tommaso-moro@github.com>
Date: Tue, 16 Dec 2025 16:26:18 +0000
Subject: [PATCH 1/2] update docs

---
 CONTRIBUTING.md       |  1 +
 docs/tool-renaming.md | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 docs/tool-renaming.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4ad4ece12..9bbf555e1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,6 +39,7 @@ These are one time installations required to be able to test your changes locall
     - Run linter: `script/lint`
     - Update snapshots and run tests: `UPDATE_TOOLSNAPS=true go test ./...`
     - Update readme documentation: `script/generate-docs`
+    - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
 6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
 7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 
diff --git a/docs/tool-renaming.md b/docs/tool-renaming.md
new file mode 100644
index 000000000..dc52706a9
--- /dev/null
+++ b/docs/tool-renaming.md
@@ -0,0 +1,41 @@
+# Tool Renaming Guide
+
+How to safely rename MCP tools without breaking existing user configurations.
+
+## Overview
+
+When tools are renamed, users who have the old tool name in their MCP configuration (e.g., in `X-MCP-Tools` headers for the remote MCP server or `--tools` flags for the local MCP server) would normally get errors. The deprecation alias system allows us to maintain backward compatibility by silently resolving old tool names to their new canonical names.
+
+This allows us to rename tools safely, without introducing breaking changes for users that have a hard reference to those tools in their server configuration.
+
+## Quick Steps
+
+1. **Rename the tool** in your code (as usual, this will imply a range of changes like updating the tool registration, the tests and the toolsnaps).
+2. **Add a deprecation alias** in [pkg/github/deprecated_tool_aliases.go](../pkg/github/deprecated_tool_aliases.go):
+   ```go
+   var DeprecatedToolAliases = map[string]string{
+       "old_tool_name": "new_tool_name",
+   }
+   ```
+3. **Update documentation** (README, etc.) to reference the new canonical name
+
+That's it. The server will silently resolve old names to new ones. This will work across both local and remote MCP servers.
+
+## Example
+
+If renaming `get_issue` to `issue_read`:
+
+```go
+var DeprecatedToolAliases = map[string]string{
+    "get_issue": "issue_read",
+}
+```
+
+A user with this configuration:
+```json
+{
+  "--tools": "get_issue,get_file_contents"
+}
+```
+
+Will get `issue_read` and `get_file_contents` tools registered, with no errors.

From cb3088f3eca49e11fb4d62cb15648433c4582ea1 Mon Sep 17 00:00:00 2001
From: Tommaso Moro <37270480+tommaso-moro@users.noreply.github.com>
Date: Tue, 16 Dec 2025 16:46:54 +0000
Subject: [PATCH 2/2] Update docs/tool-renaming.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/tool-renaming.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/tool-renaming.md b/docs/tool-renaming.md
index dc52706a9..cd1bca5c6 100644
--- a/docs/tool-renaming.md
+++ b/docs/tool-renaming.md
@@ -4,7 +4,8 @@ How to safely rename MCP tools without breaking existing user configurations.
 
 ## Overview
 
-When tools are renamed, users who have the old tool name in their MCP configuration (e.g., in `X-MCP-Tools` headers for the remote MCP server or `--tools` flags for the local MCP server) would normally get errors. The deprecation alias system allows us to maintain backward compatibility by silently resolving old tool names to their new canonical names.
+When tools are renamed, users who have the old tool name in their MCP configuration (for example, in `X-MCP-Tools` headers for the remote MCP server or `--tools` flags for the local MCP server) would normally get errors. 
+The deprecation alias system allows us to maintain backward compatibility by silently resolving old tool names to their new canonical names.
 
 This allows us to rename tools safely, without introducing breaking changes for users that have a hard reference to those tools in their server configuration.