[BUG] search_knowledge_base_retrieve tool does not offer certain API options

[jcbartle]

Describe the bug

(This may be an enhancement request and not a bug...)

When running a query of the search_knowledge_base_retrieve tool, you get back this response:

{
    "result": {
        "tools": [
            {
                "name": "search_knowledge_base_retrieve",
                "description": "Execute a retrieval operation using a specific Azure AI Search knowledge base, effectively searching and querying the underlying\ndata sources as needed to find relevant information. Provide either a --query for single-turn retrieval or one or more\nconversational --messages in role:content form (e.g. user:What policies apply?). Specifying both --query and --messages is not\nallowed.\n\nRequired arguments:\n- service\n- knowledge-base",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "tenant": {
                            "type": "string",
                            "description": "The Microsoft Entra ID tenant ID or name. This can be either the GUID identifier or the display name of your Entra ID tenant."
                        },
                        "auth-method": {
                            "type": "integer",
                            "description": "Authentication method to use. Options: 'credential' (Azure CLI/managed identity), 'key' (access key), or 'connectionString'."
                        },
                        "retry-delay": {
                            "type": "number",
                            "description": "Initial delay in seconds between retry attempts. For exponential backoff, this value is used as the base."
                        },
                        "retry-max-delay": {
                            "type": "number",
                            "description": "Maximum delay in seconds between retries, regardless of the retry strategy."
                        },
                        "retry-max-retries": {
                            "type": "integer",
                            "description": "Maximum number of retry attempts for failed operations before giving up."
                        },
                        "retry-mode": {
                            "type": "integer",
                            "description": "Retry strategy to use. 'fixed' uses consistent delays, 'exponential' increases delay between attempts."
                        },
                        "retry-network-timeout": {
                            "type": "number",
                            "description": "Network operation timeout in seconds. Operations taking longer than this will be cancelled."
                        },
                        "service": {
                            "type": "string",
                            "description": "The name of the Azure AI Search service (e.g., my-search-service)."
                        },
                        "knowledge-base": {
                            "type": "string",
                            "description": "The name of the knowledge base within the Azure AI Search service."
                        },
                        "query": {
                            "type": "string",
                            "description": "Natural language query for retrieval when a conversational message history isn't provided."
                        },
                        "messages": {
                            "type": "array",
                            "description": "Conversation history messages passed to the knowledge base. Able to specify multiple --messages entries. Each entry formatted as role:content, where role is `user` or `assistant` (e.g., user:How many docs?).",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "required": [
                        "service",
                        "knowledge-base"
                    ]
                },
                "annotations": {
                    "title": "Execute retrieval using a knowledge base in Azure AI Search",
                    "destructiveHint": false,
                    "idempotentHint": true,
                    "openWorldHint": true,
                    "readOnlyHint": true
                }
            }
        ]
    },
    "id": 1,
    "jsonrpc": "2.0"
}

This schema structure doesn't offer any options for getting back citation / reference information, which is fairly critical functionality for any type of RAG implementation.

In order to get back citation / references, you must pass along these attributes to the knowledge base retrieval API endpoint (API reference, Agentic Retrieval Example):

"knowledgeSourceParams": [
    {
      "knowledgeSourceName": "knowledgesource-name",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "alwaysQuerySource": false,
      "kind": "searchIndex"
    }
  ]

Can this tool be updated to support these parameters?

Thanks!

J.C.

Expected behavior

When running a query of the search_knowledge_base_retrieve tool, you should get back knowledgeSourceParams in the inputSchema property.

Actual behavior

knowledgeSourceParams is not present in the inputSchema property.

Reproduction Steps

(the below does not include the Entra ID or Azure resource configuration)

Using Docker, you can fire up a local MCP server as such (customize as required):

docker run --rm -it -p 8080:8080 -e ASPNETCORE_ENVIRONMENT=Dev -e ASPNETCORE_URLS=http://+:8080 -e AZURE_MCP_DANGEROUSLY_DISABLE_HTTPS_REDIRECTION=true -e AZURE_MCP_COLLECT_TELEMETRY=false -e AzureAd__Instance=https://login.microsoftonline.com/ -e AzureAd__TenantId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -e AzureAd__ClientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -e AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -e AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -e AZURE_CLIENT_SECRET=secret_value mcr.microsoft.com/azure-sdk/azure-mcp:2.0.0-beta.19-amd64 --transport http --outgoing-auth-strategy UseHostingEnvironmentIdentity --mode single --read-only --tool search_knowledge_base_retrieve

You can then call it via PowerShell like this:

$Token = 'token_value'  
$Headers = @{ 'Authorization' = ('Bearer {0}' -f $Token); 'Content-Type' = 'application/json'; 'Accept' = 'application/json, text/event-stream' }  
$BodyListTools = @{ 'jsonrpc' = '2.0'; 'id' = 1; 'method' = 'tools/list'; 'params' = @{} } | ConvertTo-Json  
$McpResponseListTools = Invoke-WebRequest -Method Post -Uri 'http://localhost:8080/' -Headers $Headers -Body $BodyListTools

This will result in a response similar to:

{
    "result": {
        "tools": [
            {
                "name": "search_knowledge_base_retrieve",
                "description": "Execute a retrieval operation using a specific Azure AI Search knowledge base, effectively searching and querying the underlying\ndata sources as needed to find relevant information. Provide either a --query for single-turn retrieval or one or more\nconversational --messages in role:content form (e.g. user:What policies apply?). Specifying both --query and --messages is not\nallowed.\n\nRequired arguments:\n- service\n- knowledge-base",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "tenant": {
                            "type": "string",
                            "description": "The Microsoft Entra ID tenant ID or name. This can be either the GUID identifier or the display name of your Entra ID tenant."
                        },
                        "auth-method": {
                            "type": "integer",
                            "description": "Authentication method to use. Options: 'credential' (Azure CLI/managed identity), 'key' (access key), or 'connectionString'."
                        },
                        "retry-delay": {
                            "type": "number",
                            "description": "Initial delay in seconds between retry attempts. For exponential backoff, this value is used as the base."
                        },
                        "retry-max-delay": {
                            "type": "number",
                            "description": "Maximum delay in seconds between retries, regardless of the retry strategy."
                        },
                        "retry-max-retries": {
                            "type": "integer",
                            "description": "Maximum number of retry attempts for failed operations before giving up."
                        },
                        "retry-mode": {
                            "type": "integer",
                            "description": "Retry strategy to use. 'fixed' uses consistent delays, 'exponential' increases delay between attempts."
                        },
                        "retry-network-timeout": {
                            "type": "number",
                            "description": "Network operation timeout in seconds. Operations taking longer than this will be cancelled."
                        },
                        "service": {
                            "type": "string",
                            "description": "The name of the Azure AI Search service (e.g., my-search-service)."
                        },
                        "knowledge-base": {
                            "type": "string",
                            "description": "The name of the knowledge base within the Azure AI Search service."
                        },
                        "query": {
                            "type": "string",
                            "description": "Natural language query for retrieval when a conversational message history isn't provided."
                        },
                        "messages": {
                            "type": "array",
                            "description": "Conversation history messages passed to the knowledge base. Able to specify multiple --messages entries. Each entry formatted as role:content, where role is `user` or `assistant` (e.g., user:How many docs?).",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "required": [
                        "service",
                        "knowledge-base"
                    ]
                },
                "annotations": {
                    "title": "Execute retrieval using a knowledge base in Azure AI Search",
                    "destructiveHint": false,
                    "idempotentHint": true,
                    "openWorldHint": true,
                    "readOnlyHint": true
                }
            }
        ]
    },
    "id": 1,
    "jsonrpc": "2.0"
}

You can then further call the actual tool with a real question. You will get back an answer, but it will not include the citation / reference information.

Environment

Cloud: Azure Commercial
Resource: Azure AI Search
Running locally via Docker Desktop.
Image: mcr.microsoft.com/azure-sdk/azure-mcp:2.0.0-beta.19-amd64

[github-actions]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @microsoft/azure-mcp @pablocastro.