[MCP] describe_entities tool fixes and refactoring #2900

souvikghosh04 · 2025-10-09T09:30:00Z

Why make this change?

Closes on

[Enh]: Add DML tool: describe_entities #2827

Added fixes and refactored the describe_entities tool to support entity metadata discovery for AI agents and LLM clients before performing CRUD operations.

What is this change?

Expose entity descriptions with proper null handling
Expose field description for entities of type stored-procedure with parameter metadata
Expose permissions for all entities with distinct values
Added nameOnly parameter to return lightweight response (entity names and descriptions only)
Added entities parameter to filter results by specific entity names
Implemented proper error handling using McpResponseBuilder pattern
Added support for relationships, mappings, and primary key information
Improved response structure with metadata section including mode and count

How was this tested?

Functional testing using Insomnia client by running DAB in localhost and local SQL DB database

MCP endpoint: http://localhost:5000/mcp
JSON payload (details below)
Validating the response

Expected (In-progress) format of entity description in response-

{
  "entities": [
    {
      "name": "entity-name",
      "description": "entity description",
      "type": "Table",
      "fields": [
        {
          "name": "field-name",
          "type": "unknown",
          "description": "field description"
        }
      ],
      "permissions": [
        "CREATE",
        "READ",
        "UPDATE",
        "DELETE"
      ],
      "primaryKey": ["id"],
      "relationships": [...],
      "mappings": {...}
    }
  ],
  "count": 1,
  "mode": "full"
}

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
}

Copilot

Pull Request Overview

This PR renames the describe-entities tool to describe_entities and enhances its functionality to provide comprehensive entity metadata including descriptions, fields for stored procedures, and permissions.

Renamed tool from describe-entities to describe_entities across configuration and implementation
Enhanced entity response to include descriptions, fields for stored procedures, and permissions
Added proper documentation and error handling to the tool implementation

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Config/ObjectModel/DmlToolsConfig.cs	Updated comments to reflect the new tool name
src/Config/Converters/DmlToolsConfigConverter.cs	Updated JSON property name and validation logic
src/Cli/ConfigGenerator.cs	Updated logging message to use new tool name
src/Cli/Commands/ConfigureOptions.cs	Updated CLI option name for the tool
src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs	Major refactoring with enhanced functionality and documentation
schemas/dab.draft.schema.json	Updated JSON schema property name and description

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

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

This reverts commit eeac569.

anushakolan

LGTM. I will test this with Claude to see if there are any other errors.

…://github.com/Azure/data-api-builder into dev/anushakolan/mcp/add-field-description-new

…scription-new' into Usr/sogh/describe-entities

souvikghosh04 · 2025-10-24T12:58:30Z

/azp run

azure-pipelines · 2025-10-24T12:58:53Z

Azure Pipelines successfully started running 6 pipeline(s).

RubenCerna2079 · 2025-10-24T17:57:54Z

/azp run

azure-pipelines · 2025-10-24T17:58:20Z

Azure Pipelines successfully started running 6 pipeline(s).

RubenCerna2079 · 2025-10-24T23:29:26Z

/azp run

azure-pipelines · 2025-10-24T23:29:48Z

Azure Pipelines successfully started running 6 pipeline(s).

RubenCerna2079

LGTM!

The changes have been made

Aniruddh25 · 2025-11-03T21:06:35Z

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

+                {
+                    ["entities"] = finalEntityList,
+                    ["count"] = finalEntityList.Count,
+                    ["mode"] = nameOnly ? "basic" : "full"


The mode in the response was not expected as per the spec. Why do we need to add it? Without looking at code, I didnt realize basic meant nameOnly. We should remove this from the response unless we confirm value from adding this.

Aniruddh25 · 2025-11-03T21:08:32Z

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

+                    ["mode"] = nameOnly ? "basic" : "full"
+                };
+
+                if (entityFilter != null && entityFilter.Count > 0)


Why is the entityFilter needed in the response? The spec doesnt ask for it

Aniruddh25 · 2025-11-03T23:20:38Z

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

+                logger?.LogInformation(
+                    "DescribeEntitiesTool returned {EntityCount} entities in {Mode} mode.",
+                    finalEntityList.Count,
+                    nameOnly ? "basic" : "full");


Are the terms basic and full defined anywhere in the spec? We should log nameOnly or not instead of these terms because they are not self explanatory.

Aniruddh25 · 2025-11-03T23:30:45Z

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

                {
-                    Content = [new TextContentBlock { Type = "text", Text = $"Error: {ex.Message}" }]
-                });
+                    foreach (EntityAction action in permission.Actions)


We should limit the actions that are added to the permissions HashSet to be only those actions of the role in which this request was made.

Aniruddh25 · 2025-11-04T14:14:51Z

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

+                {
+                    result.Add(new
+                    {
+                        name = field.Name,


This should be sending back the alias not the name. Onlyu if alias is absent, should it send back the name.

Aniruddh25 · 2025-11-04T14:16:16Z

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

+                    {
+                        name = param.Name,
+                        required = param.Default == null, // required if no default
+                        @default = param.Default,


Is the expected response key @default? why not simply default?

… 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 } ```

souvikghosh04 added 2 commits October 9, 2025 14:49

Added description and other fixes to describe-entities

3354db0

updated the describe-entties to describe_entities

eeac569

souvikghosh04 changed the title ~~[MCP] describe_entities tool~~ [MCP] Refactoring and additional fixes to describe_entities tool Oct 9, 2025

souvikghosh04 changed the title ~~[MCP] Refactoring and additional fixes to describe_entities tool~~ [MCP] describe_entities tool fixes and refactoring Oct 9, 2025

souvikghosh04 marked this pull request as ready for review October 9, 2025 11:15

souvikghosh04 requested a review from Aniruddh25 as a code owner October 9, 2025 11:15

Copilot AI review requested due to automatic review settings October 9, 2025 11:15

souvikghosh04 requested review from Alekhya-Polavarapu, RubenCerna2079, aaronburtle, anushakolan, neeraj-sharma2592, rusamant, sourabh1007 and vadeveka as code owners October 9, 2025 11:15

Copilot AI reviewed Oct 9, 2025

View reviewed changes

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs Outdated Show resolved Hide resolved

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs Outdated Show resolved Hide resolved

souvikghosh04 self-assigned this Oct 9, 2025

souvikghosh04 added this to the Oct 2025 milestone Oct 9, 2025

souvikghosh04 added this to Data API builder Oct 9, 2025

github-project-automation bot moved this to Todo in Data API builder Oct 9, 2025

souvikghosh04 added mssql an issue thats specific to mssql mcp-server labels Oct 9, 2025

souvikghosh04 moved this from Todo to In Progress in Data API builder Oct 9, 2025

souvikghosh04 moved this from In Progress to Review In Progress in Data API builder Oct 9, 2025

souvikghosh04 linked an issue Oct 9, 2025 that may be closed by this pull request

[Enh]: Add DML tool: describe_entities #2827

Closed

11 tasks

Revert "updated the describe-entties to describe_entities"

3a9a83b

This reverts commit eeac569.

souvikghosh04 changed the title ~~[MCP] describe_entities tool fixes and refactoring~~ [MCP] describe-entities tool fixes and refactoring Oct 9, 2025

anushakolan approved these changes Oct 13, 2025

View reviewed changes

Changed tool name to describe_entities

ad41a41

souvikghosh04 changed the title ~~[MCP] describe-entities tool fixes and refactoring~~ [MCP] describe_entities tool fixes and refactoring Oct 13, 2025

souvikghosh04 added 3 commits October 24, 2025 14:48

Merge branch 'dev/anushakolan/mcp/add-field-description-new' of https…

c9d52e4

…://github.com/Azure/data-api-builder into dev/anushakolan/mcp/add-field-description-new

Merge remote-tracking branch 'origin/dev/anushakolan/mcp/add-field-de…

2159f66

…scription-new' into Usr/sogh/describe-entities

Added field and parameter metadata

7ce9f2e

Add permissions info metadata

23d19d7

RubenCerna2079 enabled auto-merge (squash) October 24, 2025 22:25

Merge branch 'main' into Usr/sogh/describe-entities

08ee4f9

RubenCerna2079 approved these changes Oct 24, 2025

View reviewed changes

anushakolan approved these changes Oct 24, 2025

View reviewed changes

RubenCerna2079 merged commit 5ba8682 into main Oct 25, 2025
11 checks passed

RubenCerna2079 deleted the Usr/sogh/describe-entities branch October 25, 2025 00:34

github-project-automation bot moved this from Review In Progress to Done in Data API builder Oct 25, 2025

Aniruddh25 reviewed Nov 3, 2025

View reviewed changes

Aniruddh25 reviewed Nov 4, 2025

View reviewed changes

souvikghosh04 mentioned this pull request Nov 6, 2025

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

Merged

1 task

[MCP] describe_entities tool fixes and refactoring #2900

[MCP] describe_entities tool fixes and refactoring #2900

Uh oh!

Conversation

souvikghosh04 commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why make this change?

Closes on

What is this change?

How was this tested?

Sample Request(s)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

anushakolan left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 commented Oct 24, 2025

Uh oh!

azure-pipelines bot commented Oct 24, 2025

Uh oh!

RubenCerna2079 commented Oct 24, 2025

Uh oh!

azure-pipelines bot commented Oct 24, 2025

Uh oh!

RubenCerna2079 commented Oct 24, 2025

Uh oh!

azure-pipelines bot commented Oct 24, 2025

Uh oh!

RubenCerna2079 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Aniruddh25 Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Aniruddh25 Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

souvikghosh04 commented Oct 9, 2025 •

edited

Loading

anushakolan left a comment •

edited

Loading