Tool Rename Deprecation

# 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`):

```typescript
// 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:

```typescript
legacyToolReferenceFullNames: ['oldToolSet/oldToolName'],
```

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

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

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

```typescript
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:**

```jsonc
// 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:

- *