[Enh]: Add DML tool: `update_record`

[JerryNixon]

What?

update_record

A tool to allow an agent to update a single record.

Behavior

1. Behaves most like the GraphQL flow

2. Entity permissions are enforced

   • Never bypass permissions.
   • On violation, return a standard DAB response payload with an error message (e.g. "You do not have permission to update this entity").
   • Do not signal errors via HTTP status codes.

3. Supports partial field lists

   • Requests may specify only a subset of fields to update.
   • Fields not included in the request remain unchanged in the database.
   • If supplied fields violate constraints (nulls, types, etc.), allow the database to fail and return the resulting error in a standard DAB response payload.

4. Returns the updated entity

   • The response includes only the combination of keys and fields supplied in the request.
   • Example: a table with 100 columns, request with 3 fields → response contains only those 3 fields plus the key(s).

5. Key handling

   • Keys use the entity’s mapped aliases.
   • Keys are required in the request.
   • Keys uniquely identify the record to update.
   • If no record matches the supplied keys, return a DAB error payload (e.g. "No entity found with the given key").

6. Field handling

   • Fields use the entity’s mapped aliases.

How

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

Tool method

/// <summary>
/// Updates a single record in the specified entity. 
/// Keys must uniquely identify the record. 
/// Returns only the requested keys and fields or an error. 
/// </summary>
Task<DabResponse> UpdateEntityAsync(
    [Description("The entity name of the record to update. "
               + "Must match an entity returned by list_entities with update=true. Required.")]
    string entity,

    [Description("A dictionary of key/value pairs that uniquely identify the record to update. "
               + "Keys must match those defined in entity metadata. Required.")]
    IDictionary<string, object?> keys,

    [Description("A dictionary of field/value pairs to update. "
               + "Fields must match those defined in entity metadata. Required.")]
    IDictionary<string, object?> fields);

Parameters

• entity (string, required)

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

• keys (IDictionary<string, object?>, required)

if (keys == null || keys.Count == 0)
    throw new ArgumentException("Keys are required to update an entity", nameof(keys));

foreach (var key in keys.Keys)
{
    if (!entityMetadata.Keys.Contains(key))
        throw new ArgumentException($"Invalid key: {key}", nameof(keys));
}

• fields (IDictionary<string, object?>, required)

if (fields == null || fields.Count == 0)
    throw new ArgumentException("At least one field must be provided to update an entity", nameof(fields));

foreach (var field in fields.Keys)
{
    if (!entityMetadata.Fields.Contains(field))
        throw new ArgumentException($"Invalid field: {field}", nameof(fields));
}

Example call

await UpdateEntityAsync(
    entity: "User",
    keys: new Dictionary<string, object?> {
        { "Id", 123 }
    },
    fields: new Dictionary<string, object?> {
        { "email", "new@email.com" },
        { "name", "Updated Jerry" }
    });

Output payload

This is a standard Data API builder (DAB) payload which includes errors.

Why?

This allows agents to update existing records.

Configuration

Command line

Add dab --configure runtime.mcp.dml-tools.update-record.enabled true