tool-rename-deprecation

SKILL.md

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:

Entity
Registration
Name field to rename
Legacy array
Stable ID (NEVER change)

Tool (IToolData)
TypeScript
toolReferenceName
legacyToolReferenceFullNames
id

Tool (extension)
package.json languageModelTools
toolReferenceName
legacyToolReferenceFullNames
name (becomes id)

Tool set (IToolSet)
TypeScript
referenceName
legacyFullNames
id

Tool set (extension)
package.json languageModelToolSets
name or referenceName
legacyFullNames
—

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

Auto-approval config — isToolEligibleForAutoApproval() checks legacyToolReferenceFullNames (including the segment after / for namespaced legacy names) against chat.tools.eligibleForAutoApproval settings

RunInTerminalTool — has its own local auto-approval check that also iterates LEGACY_TOOL_REFERENCE_FULL_NAMES

After renaming, confirm:

#oldName in a .prompt.md file still resolves (shows no validation error)

Tool configurations referencing the old name still activate the tool

A user who had "chat.tools.eligibleForAutoApproval": { "oldName": false } still has that restriction honored

Step 4 — Update References (Optional)

While legacy names ensure backward compatibility, update first-party references to use the new name:

System prompts and built-in .prompt.md files

Documentation and model descriptions that mention the tool by reference name

Test files that reference the old name directly

Key Files

File
What it contains

src/vs/workbench/contrib/chat/common/tools/languageModelToolsService.ts
IToolData and IToolSet interfaces with legacy name fields

src/vs/workbench/contrib/chat/browser/tools/languageModelToolsService.ts
Resolution logic: getToolAliases, getToolSetAliases, getDeprecatedFullReferenceNames, isToolEligibleForAutoApproval

src/vs/workbench/contrib/chat/common/tools/languageModelToolsContribution.ts
Extension point schema, validation, and the critical id: rawTool.name mapping (line ~274)

src/vs/workbench/contrib/terminalContrib/chatAgentTools/browser/tools/runInTerminalTool.ts
Example of a tool with its own local auto-approval check against legacy names

Real Examples

runInTerminal tool: renamed from runCommands/runInTerminal → legacyToolReferenceFullNames: ['runCommands/runInTerminal']

todo tool: renamed from todos → legacyToolReferenceFullNames: ['todos']

getTaskOutput tool: renamed from runTasks/getTaskOutput → legacyToolReferenceFullNames: ['runTasks/getTaskOutput']

Reference PRs

#277047 — Design PR: Introduced legacyToolReferenceFullNames and legacyFullNames, built the resolution infrastructure, and performed the first batch of tool renames. Use as a template for how to properly rename with legacy names.

#278506 — Consumer-side fix: After the renames in #277047, the eligibleForAutoApproval setting wasn't checking legacy names — users who had restricted the old name lost that restriction. Shows why all consumers of tool reference names must account for legacy names.

vscode-copilot-chat#3810 — Example of a miss: Renamed openSimpleBrowser → openIntegratedBrowser but also changed the name field (stable id) from copilot_openSimpleBrowser → copilot_openIntegratedBrowser. The toolReferenceName backward compat only worked by coincidence (the old name happened to already be in the legacy array from a prior change — it was not intentionally added as part of this rename).

Regression Check

Run this check on any PR that touches tool registration (TypeScript IToolData, createToolSet, or package.json languageModelTools/languageModelToolSets):

Search the diff for changed toolReferenceName or referenceName values. For each change, confirm the previous value now appears in legacyToolReferenceFullNames or legacyFullNames. Don't assume it was already there — read the actual array.

Search the diff for changed name fields on extension-contributed tools. The name field is the tool's stable id — it must never change. If it changed, flag it as a bug. (This breaks activation events, tool invocations by id, and any code referencing the tool by its name.)

Verify no entries were removed from existing legacy arrays.

If a tool moved between tool sets, confirm the old toolSet/toolName full path is in the legacy array.

Check tool set membership lists (the tools array in languageModelToolSets contributions). If a tool's toolReferenceName changed, any tool set tools array referencing the old name should be updated — but the legacy resolution system handles this, so the old name still works.

Anti-patterns

Changing the name field on extension-contributed tools — the name in package.json becomes the id on IToolData (via id: rawTool.name in languageModelToolsContribution.ts). Changing it breaks activation events (onLanguageModelTool:<name>), any code referencing the tool by id, and tool invocations. Only rename toolReferenceName, never name. (See vscode-copilot-chat#3810 where both name and toolReferenceName were changed.)

Changing the id field on TypeScript-registered tools — same principle as above. The id is a stable internal identifier and must never change.

Assuming the old name is already in the legacy array — always verify by reading the actual legacyToolReferenceFullNames contents, not just checking that the field exists. A legacy array might list names from an even older rename but not the current one being changed.

Removing an old name from the legacy array — breaks existing saved prompts and user configurations.

Forgetting to add the legacy name entirely — prompt files and tool configs silently stop resolving.

Only updating prompt resolution but not other consumers — auto-approval settings, tool enablement maps, and individual tool checks (like RunInTerminalTool) all need to respect legacy names (see #278506).