Azure / Azure/data-api-builder
`describe_entities` should merge config fields with DB columns for tables/views
- 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
Assessment
This issue has not been assessed yet.