What?

read_records

A tool to allow an agent to read records from a single entity.

Behavior

1. Behaves most like the GraphQL flow

2. Entity permissions are enforced

   • Never bypass permissions.
   • On violation, return a standard response payload with an error message.
   • Do not signal errors via HTTP status codes.

3. Projection

   • select is a CSV of field names to include in the response.
   • If select is null or empty, return all accessible fields.

   e.g.: Id,Name,Email

4. Filtering

   • filter is an expression string to reduce results.
   • Invalid filters should be passed through and return as an error payload.
   • ⚠️ Specific syntax needs team discussion!

5. Paging

   • first sets page size. It may be smaller or larger than the default, but never greater than the configured maximum.
   • after is a cursor token returned by a prior call. Paging is cursor-based.
   • If the anchor record for after was deleted between calls, the next page may be unavailable. Return a standard error payload.

6. Sorting

   • orderby is a list of fields with direction (asc or desc).
   • Sorting is recommended when paging to ensure stable page boundaries.

7. Result shape

   • Returns an array of projected entities. Projection follows select. If select is null, returns all accessible fields.

8. Operation scope

   • The result of this tool is ultimately a basic SELECT statement against the database.
   • Aggregate functions and advanced operations are supported by other tools that use the persisted document feature.

How

• Add read_records MCP tool through graphql flow
• Add config property (runtime.mcp.dml-tools.read-records.enabled=true)
• Update JSON Schema with runtime.mcp.dml-tools.read-records.enabled
• Obey configuration (runtime.mcp.dml-tools.read-records.enabled=true)
• Add CLI dab configure --runtime.mcp.dml-tools.read-records.enabled true
• Update dab validate (warn when read-records.enabled and not mcp.enabled)

Tool method

/// <summary>
/// Reads records from the specified entity using projection, filtering, sorting, and paging. 
/// Returns an array of entities projected according to the request. 
/// </summary>
Task<DabResponse> ReadEntityAsync(
    [Description("The entity name to read from. Required.")]
    string entity,

    [Description("A CSV of field names to include in the response. If not provided, all fields are returned. Optional.")]
    string? select = null,

    [Description("A filter expression string to restrict results. Optional.")]
    string? filter = null,

    [Description("The maximum number of records to return in this page. Optional.")]
    int? first = null,

    [Description("A list of field names and directions for sorting (e.g., \"name asc\"). Optional.")]
    IEnumerable<string>? orderby = null,

    [Description("A cursor token for retrieving the next page of results. Optional.")]
    string? after = null);

Parameters

• entity (string, required)

  if (string.IsNullOrWhiteSpace(entity))
      throw new ArgumentException("Entity is required", nameof(entity));
  if (!entityMetadata.Read)
      throw new UnauthorizedAccessException($"Entity {entity} cannot be read.");

Output payload

Standard DAB response containing an array of entities and a paging cursor for the next call when applicable. Errors are returned in the standard error payload.

Why?

This allows agents to execute stored procedures or functions configured as entities in DAB.

Configuration

Command line

Add dab --configure runtime.mcp.dml-tools.read-records.enabled true