From 01e74d7bd0267b1b39438d2cd31933bd7154ce15 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Wed, 20 May 2026 01:17:45 +0000
Subject: [PATCH] fix: remove extraneous `source.description` schema property;
 clarify `entity.description` covers MCP (#3552)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Why make this change?

`entities.*.source.description` existed in the JSON schema with
documentation claiming it drove MCP tool discovery — but it was never
wired to any C# model (`EntitySource` has no `Description` field) and
was silently ignored at runtime. Meanwhile, `entities.*.description` —
the field that *actually* surfaces in MCP — made no mention of MCP.
Users following the schema would configure the wrong field and get no
MCP output with no error.

## What is this change?

- **Removed** `entities.*.source.description` from
`schemas/dab.draft.schema.json`. The property never had a backing field
in `EntitySource` and was dead schema surface area.
- **Updated** the description of `entities.*.description` to explicitly
mention MCP:

```diff
- "Optional description for the entity. Will be surfaced in generated API documentation and GraphQL schema as comments."
+ "Optional description for the entity. Will be surfaced in MCP tool discovery, generated API documentation, and GraphQL schema as comments."
```

The correct config pattern for MCP-visible descriptions is:

```json
"Todo": {
  "description": "Manages to-do items — surfaced in MCP, REST docs, and GraphQL schema.",
  "source": {
    "object": "dbo.Todos",
    "type": "table"
  }
}
```

## How was this tested?

- [ ] Integration Tests
- [ ] Unit Tests

Schema-only change; no runtime behavior altered. The removed property
had no backing model field and was never deserialized.

## Sample Request(s)

N/A — schema documentation fix only.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Aniruddh25 <3513779+Aniruddh25@users.noreply.github.com>
Co-authored-by: Aniruddh Munde <anmunde@microsoft.com>
---
 schemas/dab.draft.schema.json | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/schemas/dab.draft.schema.json b/schemas/dab.draft.schema.json
index 663cc519bd..7394ff7268 100644
--- a/schemas/dab.draft.schema.json
+++ b/schemas/dab.draft.schema.json
@@ -997,7 +997,7 @@
           "properties": {
             "description": {
               "type": "string",
-              "description": "Optional description for the entity. Will be surfaced in generated API documentation and GraphQL schema as comments."
+              "description": "Optional description for the entity. Will be surfaced in MCP tool discovery, generated API documentation, and GraphQL schema as comments."
             },
             "health": {
               "description": "Health check configuration for entity",
@@ -1088,10 +1088,6 @@
                         "type": "string"
                       },
                       "description": "DEPRECATED. Use the 'fields' array and set 'primary-key: true' on each key field instead. List of fields to be used as primary keys."
-                    },
-                    "description": {
-                      "type": "string",
-                      "description": "Human-readable description of the database object, used for MCP tool discovery and documentation."
                     }
                   },
                   "required": ["type", "object"]