[Doc Gap] FoundryExtensions tool parameter names outdated after PR #2949 migration to new tool design

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.FoundryExtensions
Triggered by: commit 6bff7de / PR #2949 by @alzimmermsft
Changed files:

• tools/Azure.Mcp.Tools.FoundryExtensions/src/Commands/KnowledgeIndexSchemaCommand.cs
• tools/Azure.Mcp.Tools.FoundryExtensions/src/Commands/OpenAiChatCompletionsCreateCommand.cs
• tools/Azure.Mcp.Tools.FoundryExtensions/src/Commands/OpenAiCompletionsCreateCommand.cs
• tools/Azure.Mcp.Tools.FoundryExtensions/src/Commands/OpenAiEmbeddingsCreateCommand.cs
• tools/Azure.Mcp.Tools.FoundryExtensions/src/Options/FoundryExtensionsOptionDefinitions.cs (deleted)
• tools/Azure.Mcp.Tools.FoundryExtensions/src/Options/Models/*.cs (all modified)

What Changed

PR #2949 migrated the FoundryExtensions toolset from the legacy FoundryExtensionsOptionDefinitions.cs pattern to the new [Option] attribute approach. Under the new design, CLI parameter names are auto-derived from C# property names using kebab-case conversion (e.g. VaultName → --vault-name). The old definitions file used explicit string names like deployment-name and index-name, but the replacement property names are Deployment and Index, which generate --deployment and --index respectively.

Gaps Found

• azmcp foundryextensions openai chat-completions-create: docs show --deployment-name but new code generates --deployment
• azmcp foundryextensions openai create-completion: docs show --deployment-name but new code generates --deployment
• azmcp foundryextensions openai embeddings-create: docs show --deployment-name but new code generates --deployment
• azmcp foundryextensions knowledge index schema: docs show --index-name but new code generates --index

Files to Update

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

Context

Current documentation (lines 2637–2666):

# Get the schema of a knowledge index in Microsoft Foundry
azmcp foundryextensions knowledge index schema \
    --endpoint <project-endpoint> \
    --index-name <index-name>

# Create chat completions using Azure OpenAI in Microsoft Foundry
azmcp foundryextensions openai chat-completions-create \
    --subscription <subscription> \
    --resource-group <resource-group> \
    --resource-name <resource-name> \
    --deployment-name <deployment-name> \
    --message-array <json-message-array>

# Create text completions using Azure OpenAI in Microsoft Foundry
azmcp foundryextensions openai create-completion \
    --subscription <subscription> \
    --resource-group <resource-group> \
    --resource-name <resource-name> \
    --deployment-name <deployment-name> \
    --prompt-text <prompt>

# Create embeddings using Azure OpenAI in Microsoft Foundry
azmcp foundryextensions openai embeddings-create \
    --subscription <subscription> \
    --resource-group <resource-group> \
    --resource-name <resource-name> \
    --deployment-name <deployment-name> \
    --input-text <text>

New options (derived from property names via kebab-case):

// KnowledgeIndexSchemaOptions.cs
public required string Index { get; set; }   // → --index  (was --index-name)

// OpenAiChatCompletionsCreateOptions.cs, OpenAiCompletionsCreateOptions.cs, OpenAiEmbeddingsCreateOptions.cs
public required string Deployment { get; set; }  // → --deployment  (was --deployment-name)

📐 Implementation Guide

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

Step 1: Modify files

File: servers/Azure.Mcp.Server/docs/azmcp-commands.md
Action: Replace the four outdated parameter names in the Microsoft Foundry Extensions section (around lines 2637–2666).

1. In knowledge index schema: change --index-name <index-name> → --index <index-name>
2. In chat-completions-create: change --deployment-name <deployment-name> → --deployment <deployment-name>
3. In create-completion: change --deployment-name <deployment-name> → --deployment <deployment-name>
4. In embeddings-create: change --deployment-name <deployment-name> → --deployment <deployment-name>

The corrected block should read:

# List knowledge indexes in a Microsoft Foundry project
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp foundryextensions knowledge index list \
    --endpoint <project-endpoint>

# Get the schema of a knowledge index in Microsoft Foundry
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp foundryextensions knowledge index schema \
    --endpoint <project-endpoint> \
    --index <index-name>

# Create chat completions using Azure OpenAI in Microsoft Foundry
# ❌ Destructive | ❌ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp foundryextensions openai chat-completions-create \
    --subscription <subscription> \
    --resource-group <resource-group> \
    --resource-name <resource-name> \
    --deployment <deployment-name> \
    --message-array <json-message-array>

# Create text completions using Azure OpenAI in Microsoft Foundry
# ❌ Destructive | ❌ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp foundryextensions openai create-completion \
    --subscription <subscription> \
    --resource-group <resource-group> \
    --resource-name <resource-name> \
    --deployment <deployment-name> \
    --prompt-text <prompt>

# Create embeddings using Azure OpenAI in Microsoft Foundry
# ❌ Destructive | ❌ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp foundryextensions openai embeddings-create \
    --subscription <subscription> \
    --resource-group <resource-group> \
    --resource-name <resource-name> \
    --deployment <deployment-name> \
    --input-text <text>

Step 2: Verify documentation structure

servers/Azure.Mcp.Server/docs/azmcp-commands.md — confirm the Microsoft Foundry Extensions section retains its heading and all commands remain in a single fenced bash block.

Step 3: Validate

Run these commands in order. Each must succeed before proceeding to the next:

1. dotnet build servers/Azure.Mcp.Server/ — confirms the server project compiles cleanly
2. dotnet build tools/Azure.Mcp.Tools.FoundryExtensions/src/ — confirms the affected toolset compiles
3. dotnet test tools/Azure.Mcp.Tools.FoundryExtensions/tests/Azure.Mcp.Tools.FoundryExtensions.Tests/ --filter "TestType!=Live" — runs unit tests for the affected toolset
4. .\eng\common\spelling\Invoke-Cspell.ps1 — checks spelling in new or 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 · ● 8.3M · ◷