Azure / Azure/data-api-builder

`describe_entities` should merge config fields with DB columns for tables/views

Open
#3,590 0 comments 1 reaction 1 assignee Assigned to @Aniruddh25 View on GitHub
2.x mcp-server
Dominant language
C#
Stars
1.5k
Forks
370
Avg merge
3d 17h
Merged PRs (30d)
8

Description

## Summary

For stored-procedure entities, `describe_entities` now uses the database as the source of truth for parameters and treats config as an overlay (#3400). The same merge does **not** yet happen for tables and views: the `fields` array surfaced to MCP agents comes from `entity.Fields` in config alone, and the database columns are ignored.

## Why this matters

Most users do not list every column under `entities..fields` in config — that block is typically used only when a column needs an alias, a description, or a `primaryKey` override. As a result, today:

- A table or view entity with no `fields:` block in config emits an **empty `fields` array** to MCP agents. The agent has no way to see what columns the entity actually has.
- A table or view entity with a partial `fields:` block (e.g. only one column described for an alias) emits **only that column** — the rest of the table is hidden from the agent.

This is the same class of agent-can't-see-required-inputs bug that #3400 fixed for stored-procedure parameters.

## Where the gap lives

[`DescribeEntitiesTool.BuildFieldMetadataInfo`](../../src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs):

```csharp
private static List BuildFieldMetadataInfo(List? fields)
{
List result = new();
if (fields != null)
{
foreach (FieldMetadata field in fields)
{
result.Add(new
{
name = field.Alias ?? field.Name,
description = field.Description ?? string.Empty
});
}
}
return result;
}
```

The DB-side equivalent lives at `SourceDefinition.Columns` (a `Dictionary`) on the resolved `DatabaseObject` — same access pattern the SP parameter merge uses.

## Proposed merge rules (mirroring #3400)

For table and view entities:

- **`name`**: from DB (`Columns.Keys`); config `Alias` overrides for the surfaced name.
- **`description`**: config-only (no reliable DB-side column description in MSSQL/PostgreSQL/MySQL metadata).
- **`primaryKey`**: from DB (`SourceDefinition.PrimaryKey`); config `PrimaryKey` overrides if present.
- **(Optional) type info**: surface `ColumnDefinition.SystemType` / `DbType` so agents know the column shape.
- DB columns not listed in config are still surfaced (with no alias/description) so agents see the full schema.
- Fall back to emitting config fields as-is when DB metadata is unavailable (same degraded path as the SP parameter merge).

## Acceptance criteria

- [ ] Tables and views with no `fields:` config block surface all DB columns to `describe_entities`.
- [ ] Config `Alias`, `Description`, and `PrimaryKey` overlay correctly when present.
- [ ] DB columns not listed in config are still surfaced.
- [ ] Degraded fallback: when DB metadata is unavailable, config-declared fields are emitted as-is.
- [ ] Unit tests mirror the SP parameter merge tests in `DescribeEntitiesStoredProcedureParametersTests`.

## Related

- #3400 — original SP parameter merge issue
- PR #_____ — SP parameter merge implementation (introduced `McpMetadataHelper.TryResolveDatabaseObject`, which this work can reuse)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.