Honoring incoming request role in determining allowed permissions for describe-entities MCP tool (#2956)

## Why make this change?

- Addresses follow ups to PR #2900
The `describe_entities` tool response format needed improvements to
better align with MCP specifications and provide more accurate,
user-scoped information. Key issues included non-specification compliant
response fields, overly broad permission reporting across all roles, and
inconsistent entity/field naming conventions that didn't prioritize
user-friendly aliases.


## What is this change?

- **Removed non-spec fields from response**: Eliminated `mode` and
`filter` fields that were not part of the MCP specification
- **Scoped permissions to current user's role**: Modified permissions
logic to only return permissions available to the requesting user's role
instead of all permissions across all roles
- **Implemented entity alias support**: Updated entity name resolution
to prefer GraphQL singular names (aliases) over configuration names,
falling back to entity name only when alias is absent
- **Fixed parameter metadata format**: Changed parameter default value
key from `@default` to `default` in JSON response
- **Enhanced field name resolution**: Updated field metadata to use
field aliases when available, falling back to field names when aliases
are absent
- **Added proper authorization context**: Integrated HTTP context and
authorization resolver to determine current user's role for permission
filtering

## How was this tested?

- [x] Manual Tests

## Sample Request(s)

```
POST http://localhost:5000/mcp

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "describe_entities"
  },
  "id": 1
}
```

```
POST http://localhost:5000/mcp

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "nameOnly": true
    }
  },
  "id": 2
}
```

```
POST http://localhost:5000/mcp

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Book", "Publisher"]
    }
  },
  "id": 1
}
```

Author: souvikghosh04

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs

@@ -2,11 +2,14 @@
 // Licensed under the MIT License.
 
 using System.Text.Json;
+using Azure.DataApiBuilder.Auth;
 using Azure.DataApiBuilder.Config.ObjectModel;
+using Azure.DataApiBuilder.Core.Authorization;
 using Azure.DataApiBuilder.Core.Configurations;
 using Azure.DataApiBuilder.Mcp.Model;
 using Azure.DataApiBuilder.Mcp.Utils;
 using Azure.DataApiBuilder.Service.Exceptions;
+using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using ModelContextProtocol.Protocol;
@@ -80,8 +83,45 @@ public Task<CallToolResult> ExecuteAsync(
                         logger));
                 }
 
+                // Get authorization services to determine current user's role
+                IAuthorizationResolver authResolver = serviceProvider.GetRequiredService<IAuthorizationResolver>();
+                IHttpContextAccessor httpContextAccessor = serviceProvider.GetRequiredService<IHttpContextAccessor>();
+                HttpContext? httpContext = httpContextAccessor.HttpContext;
+
+                // Get current user's role for permission filtering
+                // For discovery tools like describe_entities, we use the first valid role from the header
+                // This differs from operation-specific tools that check permissions per entity per operation
+                string? currentUserRole = null;
+                if (httpContext != null && authResolver.IsValidRoleContext(httpContext))
+                {
+                    string roleHeader = httpContext.Request.Headers[AuthorizationResolver.CLIENT_ROLE_HEADER].ToString();
+                    if (!string.IsNullOrWhiteSpace(roleHeader))
+                    {
+                        string[] roles = roleHeader
+                            .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
+                        if (roles.Length > 1)
+                        {
+                            logger?.LogWarning("Multiple roles detected in request header: [{Roles}]. Using first role '{FirstRole}' for entity discovery. " +
+                                "Consider using a single role for consistent permission reporting.",
+                                string.Join(", ", roles), roles[0]);
+                        }
+
+                        // For discovery operations, take the first role from comma-separated list
+                        // This provides a consistent view of available entities for the primary role
+                        currentUserRole = roles.FirstOrDefault();
+                    }
+                }
+
                 (bool nameOnly, HashSet<string>? entityFilter) = ParseArguments(arguments, logger);
 
+                if (currentUserRole == null)
+                {
+                    logger?.LogWarning("Current user role could not be determined from HTTP context or role header. " +
+                        "Entity permissions will be empty (no permissions shown) rather than using anonymous permissions. " +
+                        "Ensure the '{RoleHeader}' header is properly set.", AuthorizationResolver.CLIENT_ROLE_HEADER);
+                }
+
                 List<Dictionary<string, object?>> entityList = new();
 
                 if (runtimeConfig.Entities != null)
@@ -102,7 +142,7 @@ public Task<CallToolResult> ExecuteAsync(
                         {
                             Dictionary<string, object?> entityInfo = nameOnly
                                 ? BuildBasicEntityInfo(entityName, entity)
-                                : BuildFullEntityInfo(entityName, entity);
+                                : BuildFullEntityInfo(entityName, entity, currentUserRole);
 
                             entityList.Add(entityInfo);
                         }
@@ -140,19 +180,14 @@ public Task<CallToolResult> ExecuteAsync(
                 Dictionary<string, object?> responseData = new()
                 {
                     ["entities"] = finalEntityList,
-                    ["count"] = finalEntityList.Count,
-                    ["mode"] = nameOnly ? "basic" : "full"
+                    ["count"] = finalEntityList.Count
                 };
 
-                if (entityFilter != null && entityFilter.Count > 0)
-                {
-                    responseData["filter"] = entityFilter.ToArray();
-                }
-
                 logger?.LogInformation(
-                    "DescribeEntitiesTool returned {EntityCount} entities in {Mode} mode.",
+                    "DescribeEntitiesTool returned {EntityCount} entities. Response type: {ResponseType} (nameOnly={NameOnly}).",
                     finalEntityList.Count,
-                    nameOnly ? "basic" : "full");
+                    nameOnly ? "lightweight summary (names and descriptions only)" : "full metadata with fields, parameters, and permissions",
+                    nameOnly);
 
                 return Task.FromResult(McpResponseBuilder.BuildSuccessResult(
                     responseData,
@@ -276,25 +311,41 @@ private static bool ShouldIncludeEntity(string entityName, HashSet<string>? enti
         /// </summary>
         /// <param name="entityName">The name of the entity to include in the dictionary.</param>
         /// <param name="entity">The entity object from which to extract additional information.</param>
-        /// <returns>A dictionary with two keys: "name", containing the entity name, and "description", containing the entity's
+        /// <returns>A dictionary with two keys: "name", containing the entity alias (or name if no alias), and "description", containing the entity's
         /// description or an empty string if the description is null.</returns>
         private static Dictionary<string, object?> BuildBasicEntityInfo(string entityName, Entity entity)
         {
+            // Use GraphQL singular name as alias if available, otherwise use entity name
+            string displayName = !string.IsNullOrWhiteSpace(entity.GraphQL?.Singular)
+                ? entity.GraphQL.Singular
+                : entityName;
+
             return new Dictionary<string, object?>
             {
-                ["name"] = entityName,
+                ["name"] = displayName,
                 ["description"] = entity.Description ?? string.Empty
             };
         }
 
         /// <summary>
         /// Builds full entity info: name, description, fields, parameters (for stored procs), permissions.
         /// </summary>
-        private static Dictionary<string, object?> BuildFullEntityInfo(string entityName, Entity entity)
+        /// <param name="entityName">The name of the entity to include in the dictionary.</param>
+        /// <param name="entity">The entity object from which to extract additional information.</param>
+        /// <param name="currentUserRole">The role of the current user, used to determine permissions.</param>
+        /// <returns>
+        /// A dictionary containing the entity's name, description, fields, parameters (if applicable), and permissions.
+        /// </returns>
+        private static Dictionary<string, object?> BuildFullEntityInfo(string entityName, Entity entity, string? currentUserRole)
         {
+            // Use GraphQL singular name as alias if available, otherwise use entity name
+            string displayName = !string.IsNullOrWhiteSpace(entity.GraphQL?.Singular)
+                ? entity.GraphQL.Singular
+                : entityName;
+
             Dictionary<string, object?> info = new()
             {
-                ["name"] = entityName,
+                ["name"] = displayName,
                 ["description"] = entity.Description ?? string.Empty,
                 ["fields"] = BuildFieldMetadataInfo(entity.Fields),
             };
@@ -304,7 +355,7 @@ private static bool ShouldIncludeEntity(string entityName, HashSet<string>? enti
                 info["parameters"] = BuildParameterMetadataInfo(entity.Source.Parameters);
             }
 
-            info["permissions"] = BuildPermissionsInfo(entity);
+            info["permissions"] = BuildPermissionsInfo(entity, currentUserRole);
 
             return info;
         }
@@ -325,7 +376,7 @@ private static List<object> BuildFieldMetadataInfo(List<FieldMetadata>? fields)
                 {
                     result.Add(new
                     {
-                        name = field.Name,
+                        name = field.Alias ?? field.Name,
                         description = field.Description ?? string.Empty
                     });
                 }
@@ -338,7 +389,7 @@ private static List<object> BuildFieldMetadataInfo(List<FieldMetadata>? fields)
         /// Builds a list of parameter metadata objects containing information about each parameter.
         /// </summary>
         /// <param name="parameters">A list of <see cref="ParameterMetadata"/> objects representing the parameters to process. Can be null.</param>
-        /// <returns>A list of anonymous objects, each containing the parameter's name, whether it is required, its default
+        /// <returns>A list of dictionaries, each containing the parameter's name, whether it is required, its default
         /// value, and its description. Returns an empty list if <paramref name="parameters"/> is null.</returns>
         private static List<object> BuildParameterMetadataInfo(List<ParameterMetadata>? parameters)
         {
@@ -348,27 +399,29 @@ private static List<object> BuildParameterMetadataInfo(List<ParameterMetadata>?
             {
                 foreach (ParameterMetadata param in parameters)
                 {
-                    result.Add(new
+                    Dictionary<string, object?> paramInfo = new()
                     {
-                        name = param.Name,
-                        required = param.Default == null, // required if no default
-                        @default = param.Default,
-                        description = param.Description ?? string.Empty
-                    });
+                        ["name"] = param.Name,
+                        ["required"] = param.Required,
+                        ["default"] = param.Default,
+                        ["description"] = param.Description ?? string.Empty
+                    };
+                    result.Add(paramInfo);
                 }
             }
 
             return result;
         }
 
         /// <summary>
-        /// Build a list of permission metadata info
+        /// Build a list of permission metadata info for the current user's role
         /// </summary>
         /// <param name="entity">The entity object</param>
-        /// <returns>A list of permissions available to the entity</returns>
-        private static string[] BuildPermissionsInfo(Entity entity)
+        /// <param name="currentUserRole">The current user's role - if null, returns empty permissions</param>
+        /// <returns>A list of permissions available to the current user's role for this entity</returns>
+        private static string[] BuildPermissionsInfo(Entity entity, string? currentUserRole)
         {
-            if (entity.Permissions == null)
+            if (entity.Permissions == null || string.IsNullOrWhiteSpace(currentUserRole))
             {
                 return Array.Empty<string>();
             }
@@ -380,8 +433,15 @@ private static string[] BuildPermissionsInfo(Entity entity)
 
             HashSet<string> permissions = new(StringComparer.OrdinalIgnoreCase);
 
+            // Only include permissions for the current user's role
             foreach (EntityPermission permission in entity.Permissions)
             {
+                // Check if this permission applies to the current user's role
+                if (!string.Equals(permission.Role, currentUserRole, StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
                 foreach (EntityAction action in permission.Actions)
                 {
                     if (action.Action == EntityActionOperation.All)