[Doc Gap] azmcp compute vm/vmss delete — breaking behavior change (not-found outcome) not documented in Command Behavior

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.Compute
Triggered by: commit 9519f9b (PR #2687) by @g2vinay
Changed files:

• tools/Azure.Mcp.Tools.Compute/src/Commands/Vm/VmDeleteCommand.cs
• tools/Azure.Mcp.Tools.Compute/src/Commands/Vmss/VmssDeleteCommand.cs
• servers/Azure.Mcp.Server/docs/azmcp-commands.md
• servers/Azure.Mcp.Server/changelog-entries/1779264486206.yaml

What Changed

PR #2687 introduced a breaking change to compute vm delete and compute vmss delete: these commands now return a not-found outcome (Success: false) when the target resource does not exist, instead of reporting a successful deletion. The changelog entry marks this as a Breaking Change that "may affect automation that previously treated non-existent VM/VMSS deletions as success."

While the parameter descriptions in azmcp-commands.md were updated in the same PR, the Command Behavior sections for both azmcp compute vm delete and azmcp compute vmss delete do not describe this not-found behavior — despite both commands already carrying the ✅ Idempotent annotation in their examples.

Gaps Found

• azmcp-commands.md — ## azmcp compute vm delete Command Behavior section does not document that the command returns Success: false (with a descriptive message) when the VM does not exist, rather than throwing an error
• azmcp-commands.md — ## azmcp compute vmss delete Command Behavior section has the same omission
• e2eTestPrompts.md — no test prompt exists for the "delete non-existent resource" (idempotent/not-found) scenario for either compute_vm_delete or compute_vmss_delete

Files to Update

• servers/Azure.Mcp.Server/docs/azmcp-commands.md
• servers/Azure.Mcp.Server/docs/e2eTestPrompts.md

Context

Changelog entry from the PR:

changes:
  - section: "Breaking Changes"
    description: |
      `vm delete` and `vmss delete` now return a not-found outcome (`Success: false`) when the target resource does not exist, instead of reporting a successful deletion.
      This may affect automation that previously treated non-existent VM/VMSS deletions as success.

Current (incomplete) Command Behavior section for vm delete:

**Command Behavior:**
- Deletes the VM. Associated resources (disks, NICs, public IPs) are NOT automatically deleted.
- **With `--force-deletion`**: Passes `forceDeletion=true` to the Azure API, which force-deletes the VM even if it is in a running or failed state.

Missing: a bullet point explaining the not-found behavior (analogous to how disk delete documents this: "returns Deleted = false if the disk was not found").

📐 Implementation Guide

This section contains step-by-step instructions for a coding agent to implement the changes described above.

Step 1: Modify servers/Azure.Mcp.Server/docs/azmcp-commands.md

For ## azmcp compute vm delete — add a bullet to the Command Behavior section:

**Command Behavior:**
- Deletes the VM. Associated resources (disks, NICs, public IPs) are NOT automatically deleted.
- **With `--force-deletion`**: Passes `forceDeletion=true` to the Azure API, which force-deletes the VM even if it is in a running or failed state.
- **Not-found handling**: If the specified VM does not exist, the command returns `Success: false` with a descriptive message rather than throwing an error. This makes the operation idempotent.

For ## azmcp compute vmss delete — add a bullet to the Command Behavior section:

**Command Behavior:**
- Deletes the VMSS and all its VM instances. This operation is irreversible.
- **With `--force-deletion`**: Passes `forceDeletion=true` to the Azure API, which force-deletes the VMSS even if it is in a running or failed state.
- **Not-found handling**: If the specified VMSS does not exist, the command returns `Success: false` with a descriptive message rather than throwing an error. This makes the operation idempotent.

Step 2: Modify servers/Azure.Mcp.Server/docs/e2eTestPrompts.md

In the ## Azure Compute section, add test prompts covering the idempotent/not-found scenario:

| compute_vm_delete | Delete VM <vm-name> that does not exist in resource group <resource-group-name> |

| compute_vmss_delete | Delete scale set <vmss-name> that does not exist in resource group <resource-group-name> |

Insert these after the existing compute_vm_delete and compute_vmss_delete rows, respectively.

Step 3: Verify documentation structure

servers/Azure.Mcp.Server/docs/azmcp-commands.md — confirm the two Command Behavior sections include the not-found bullet and match the idiomatic pattern used elsewhere (e.g., the disk delete section at line 1946: "returns Deleted = true if the disk was successfully removed, or Deleted = false if the disk was not found").

servers/Azure.Mcp.Server/docs/e2eTestPrompts.md — confirm new rows are placed alphabetically within their tool group.

Step 4: Validate

Run these commands in order:

1. dotnet build servers/Azure.Mcp.Server/ — confirms the server project compiles cleanly
2. dotnet build tools/Azure.Mcp.Tools.Compute/src/ — confirms the Compute toolset compiles
3. .\eng\common\spelling\Invoke-Cspell.ps1 — checks spelling in modified documentation

Next Steps

Tip

Ready for automated implementation? Assign this issue to @copilot to have Copilot coding agent implement the changes described in the Implementation Guide above

Generated by Documentation Updater · ● 7.4M · ◷