Add aggregate_records MCP tool with query-timeout support

[Copilot]

Adds a new aggregate_records built-in MCP tool that enables models to answer aggregation questions (count, avg, sum, min, max) over entity data, with optional groupby/having/pagination. Adds configurable query-timeout for all MCP tool executions.

Why make this change?

• Models frequently need to answer questions like "How many products?" or "What's the average price by category?" — previously unsupported without custom tooling.
• MCP tool calls had no timeout, leaving models hung indefinitely on large datasets.

What is this change?

aggregate_records tool (AggregateRecordsTool.cs)

• Supports count, avg, sum, min, max with optional filter (OData WHERE), distinct, groupby, having (post-aggregation), orderby, and cursor-based first/after pagination
• Response alias: {function}_{field} (e.g. avg_unitPrice); count for count(*)
• Enabled/disabled via DmlToolsConfig.AggregateRecords; CLI: --runtime.mcp.dml-tools.aggregate-records.enabled

Validation (deterministic, model-facing errors)

• field='*' with non-count function → InvalidArguments
• count(*) + distinct=true → InvalidArguments (was silently returning 0)

query-timeout (default 30s)

• McpRuntimeOptions.QueryTimeout serialized as query-timeout in JSON config
• McpTelemetryHelper.ExecuteWithTelemetryAsync wraps every tool call with a linked CancellationTokenSource.CancelAfter; timeout fires TimeoutException with model-facing guidance, distinct from client cancellation (OperationCanceledException)
• Hot-reload safe: reads timeout from RuntimeConfigProvider per call, no restart needed
• CLI: --runtime.mcp.query-timeout

Schema/config

• dab.draft.schema.json updated with query-timeout (integer, min 1, default 30) and aggregate-records
• RuntimeConfigValidator rejects query-timeout < 1
• McpRuntimeOptionsConverterFactory reads/writes query-timeout in both Read and Write paths

How was this tested?

• Integration Tests
• Unit Tests
  • Mcp/AggregateRecordsToolTests.cs — 63 tests covering all 13 documented spec examples, groupby/having/orderby, cursor pagination, edge cases
  • Mcp/McpQueryTimeoutTests.cs — 21 tests: timeout firing, client cancellation, error message content, hot-reload behavior
  • UnitTests/AggregateRecordsToolTests.cs — 31 tests: validation paths (invalid field/function combos, count(*)+distinct, pagination cursor semantics)
  • UnitTests/McpTelemetryTests.cs — expanded with timeout and aggregate_records → "aggregate" operation-mapping tests

Sample Request(s)

Config: enable aggregate-records with custom timeout

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "query-timeout": 60,
      "dml-tools": { "aggregate-records": true }
    }
  }
}

CLI

dab configure --runtime.mcp.query-timeout 60
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

Tool call: count all products

{ "entity": "Product", "function": "count", "field": "*" }

Response: { "count": 77 }

Tool call: top categories by avg price (grouped, paginated)

{
  "entity": "Product", "function": "avg", "field": "unitPrice",
  "groupby": ["categoryName"], "having": { "gt": 25 },
  "orderby": "desc", "first": 5
}

Response: { "items": [...], "endCursor": "<opaque>", "hasNextPage": true }

Original prompt

Update PR #3179 in Azure/data-api-builder by implementing the previously identified review fixes directly in code.

Context:

• PR URL: Add aggregate_records DML tool and query-timeout to MCP server #3179
• Branch: Use the PR branch (copilot/add-aggregate-records-tool) and push commits to update the existing PR.
• Do not post PR comments; make code changes.

Required changes:

1. Fix AggregateRecordsTool distinct-count star behavior:

   • In AggregateRecordsTool.ComputeAggregateValue, current behavior returns 0 when function=count, field=*, distinct=true.
   • Replace with correct deterministic behavior: either reject this argument combination with InvalidArguments or treat it as count(*) ignoring distinct.
   • Prefer explicit validation in ExecuteAsync returning InvalidArguments with clear message.

2. Add explicit validation for function/field compatibility:

   • Enforce that field="*" is only valid when function is "count".
   • Enforce numeric field requirements for avg/sum/min/max with clear InvalidArguments errors.
   • Ensure validation is deterministic and model-facing errors are explicit.

3. Pagination contract clarity:

   • Keep behavior consistent with current intended contract for after usage (do NOT force after to require first or groupby).
   • Ensure pagination behavior and terminal endCursor semantics are explicitly documented and tested.
   • Add/adjust tests to codify intended behavior and avoid ambiguity.

4. Tests:

   • Update/add unit tests in AggregateRecordsToolTests (and others if needed) to cover:
     • count(*) + distinct handling path (per chosen behavior)
     • invalid * usage with non-count functions
     • numeric field validation for avg/sum/min/max
     • pagination terminal cursor semantics according to intended contract
   • Ensure all tests pass.

5. Keep existing successful timeout/query-timeout behavior unchanged unless required by refactors.

Acceptance criteria:

• Existing PR Add aggregate_records DML tool and query-timeout to MCP server #3179 is updated with commits implementing the above.
• No regression in MCP query-timeout and telemetry behavior.
• New/updated tests verify the corrected behavior.
• Maintain code style and project conventions.

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.