Tool Rename Deprecation

When a tool or tool set reference name is changed, the old name must always be added to the deprecated/legacy array so that existing prompt files, tool configurations, and saved references continue to resolve correctly.

When to Use

Run this skill on any change to built-in tool or tool set registration code to catch regressions:

• Renaming a tool's toolReferenceName
• Renaming a tool set's referenceName
• Moving a tool from one tool set to another (the old toolSet/toolName path becomes a legacy name)
• Reviewing a PR that modifies tool registration — verify no legacy names were dropped

Procedure

Step 1 — Identify What Changed

Determine whether you are renaming a tool or a tool set, and where it is registered:

Critical: For extension-contributed tools, the name field in package.json is mapped to id on IToolData (see languageModelToolsContribution.ts line id: rawTool.name). It is also used for activation events (onLanguageModelTool:<name>). Never rename the name field — only rename toolReferenceName.

Step 2 — Add the Old Name to the Legacy Array

Verify the old toolReferenceName value appears in legacyToolReferenceFullNames. Don't assume it's already there — check the actual array contents. If the old name is already listed (e.g., from a previous rename), confirm it wasn't removed. If it's not there, add it.

For internal/built-in tools (TypeScript IToolData):

// Before rename
export const MyToolData: IToolData = {
	id: 'myExtension.myTool',
	toolReferenceName: 'oldName',
	// ...
};

// After rename — old name preserved
export const MyToolData: IToolData = {
	id: 'myExtension.myTool',
	toolReferenceName: 'newName',
	legacyToolReferenceFullNames: ['oldName'],
	// ...
};

If the tool previously lived inside a tool set, use the full toolSet/toolName form:

legacyToolReferenceFullNames: ['oldToolSet/oldToolName'],

If renaming multiple times, accumulate all prior names — never remove existing entries:

legacyToolReferenceFullNames: ['firstOldName', 'secondOldName'],

For tool sets, add the old name to the legacyFullNames option when calling createToolSet:

toolsService.createToolSet(source, id, 'newSetName', {
	legacyFullNames: ['oldSetName'],
});

For extension-contributed tools (package.json), rename only toolReferenceName and add the old value to legacyToolReferenceFullNames. Do NOT rename the name field:

// CORRECT — only toolReferenceName changes, name stays stable
{
	"name": "copilot_myTool",           // ← KEEP this unchanged
	"toolReferenceName": "newName",     // ← renamed
	"legacyToolReferenceFullNames": [
		"oldName"                       // ← old toolReferenceName preserved
	]
}

Step 3 — Check All Consumers of Tool Names

Legacy names must be respected everywhere a tool is looked up by reference name, not just in prompt resolution. Key consumers:

• Prompt files — getDeprecatedFullReferenceNames() maps old → current names for .prompt.md validation and code actions
• Tool enablement — getToolAliases() / getToolSetAliases() yield legacy names so tool picker and enablement maps resolve them

…