Skip to main content
Glama

Propose a change to an existing record (update / delete / restore)

record_change_request

Propose a change to an existing record (update / delete / restore)

If this job may already have a playbook, call playbooks search first. Review is permission-aware for all three operations, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's materialized field to see which happened. Pass requireReview (or explicit autoMerge: false) when the user asks to only propose and wait for a person — a write-capable key would otherwise publish immediately. delete ARCHIVES the record — it is reversible with restore, not an erase. For update, fields is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "recordId": "<recordId>",
      "operation": "<operation>"
    },
    "name": "record_change_request"
  }
}

Input Schema

NameRequiredDescriptionDefault
fieldsNoNew values keyed by field slug, e.g. {"status":"published"} (update only).
messageNoExplanation for the reviewer — imperative verb + what + why, e.g. "Update deal stage to qualified — demo booked".
playbookNoOptional. The playbook you are following, as `kind:nodeId[:key]` from playbooks_search (e.g. `prompt:nod_123:log-visit`). Recorded on the change request so the person can see which playbook produced it.
recordIdYesRecord to change.
autoMergeNoSkip review and apply the change immediately if you have write access. Not a permission override — a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose.
operationYesWhat to propose. Choose this before the other arguments.
submittedByNoProducer label recorded on the change.
requireReviewNoAlways propose a pending ChangeRequest instead of applying the change, even with write access.
targetSpaceIdNoBusabase space id. Call auth_verify first and ask the user which space to use when more than one is returned.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / playbook
      Added value: +{
      +  "description": "Optional. The playbook you are following, as `kind:nodeId[:key]` from playbooks_search (e.g. `prompt:nod_123:log-visit`). Recorded on the change request so the person can see which playbook produced it.",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that review is decided server-side, that the outcome is visible in the response's `materialized` field, and that `delete` archives rather than erases. The archive semantics are consistent with destructiveHint=false, so nothing contradicts. It stops short of stating rate limits or what a pending ChangeRequest response contains beyond `materialized`.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical constraint (permission-aware merge vs pending review) and the reversible-delete warning are front-loaded in a single dense paragraph with zero filler. The opening line merely restates the title, which is mild redundancy, and the run-on density makes it slightly harder to scan than a bulleted form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter mutation tool with no output schema, the description covers the things an agent cannot infer: server-side permission logic, the `materialized` result field, review opt-in flags, and the archive-not-erase semantics of delete. Remaining parameter details are fully covered by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `fields` is keyed by field slug and only needs changed fields, the primary field should stay a short human-readable title, and `requireReview`/`autoMerge: false` are framed as the 'propose only' path. It does not discuss `targetSpaceId` or `submittedBy`, though the schema already documents those.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first line states a specific verb and resource ('propose a change to an existing record') and enumerates the three operations (update/delete/restore), so an agent knows exactly what the tool does. It does not explicitly contrast with the many sibling change-request tools (e.g. record_bulk_update_change_request), so differentiation is inferred from the singular 'record' wording rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditional routing: check for an existing playbook via playbooks search first, and pass `requireReview` (or `autoMerge: false`) when the user wants a proposal that waits for a person. It also explains the default permission-aware behavior so the agent knows when no flag is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.