Roam Research

roam_process_batch_actions

Destructive

Execute multiple block create, update, move, and delete actions in one ordered batch to reduce API calls and enable nested block creation via UID placeholders.

Instructions

RATE LIMIT EFFICIENT: This is the most API-efficient tool for multiple block operations. Combine all create/update/delete operations into a single call whenever possible. For intensive page updates or revisions, prefer this tool over multiple sequential calls.

Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order.

UID Placeholders for Nested Blocks: Use {{uid:name}} syntax for parent-child references within the same batch. The server generates proper random UIDs and returns a uid_map showing placeholder→UID mappings. Example: { uid: "{{uid:parent1}}", string: "Parent" } then { location: { "parent-uid": "{{uid:parent1}}" }, string: "Child" }. Response includes { success: true, uid_map: { "parent1": "Xk7mN2pQ9" } }.

For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with ((UID)) syntax, is supported within the string property for create-block and update-block actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like roam_fetch_page_by_title or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, roam_create_outline is often more suitable.

IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.

Input Schema

Name	Required	Description
`graph`	No	Target graph key from ROAM_GRAPHS config. Defaults to ROAM_DEFAULT_GRAPH. Only needed in multi-graph mode.
`actions`	Yes	An array of action objects to execute in order.
`write_key`	No	Write confirmation key. Required for write operations on non-default graphs when write_key is configured.

Output Schema

Name	Required	Description
`error`	No	Present only when success is false.
`success`	Yes
`uid_map`	No	Placeholder name → generated UID. Present only on success.
`committed`	No	Confirmed successful actions from a failed batch; other actions may have an unknown outcome.
`actions_attempted`	No
`validation_passed`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.1.0Oct 25, 2026

addedOutput schema / properties / committed

Added value: +{
+  "additionalProperties": true,
+  "description": "Confirmed successful actions from a failed batch; other actions may have an unknown outcome.",
+  "properties": {
+    "action_indices": {
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    "uids": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedv3.0.0Aug 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "actions_attempted": {
+      "type": "number"
+    },
+    "error": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "additionalProperties": true,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "details": {
+              "additionalProperties": true,
+              "properties": {
+                "action_index": {
+                  "type": "number"
+                },
+                "expected": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "received": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "message": {
+              "type": "string"
+            },
+            "recovery": {
+              "additionalProperties": true,
+              "properties": {
+                "retry_after_ms": {
+                  "type": "number"
+                },
+                "suggestion": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            }
+          },
+          "type": "object"
+        }
+      ],
+      "description": "Present only when success is false."
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "uid_map": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Placeholder name → generated UID. Present only on success.",
+      "type": "object"
+    },
+    "validation_passed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "success"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv2.17.0May 1, 2026

changedInput schema / properties / actions / items / properties / string / description

Previous value: -"The content for the block, used in \"create-block\" and \"update-block\" actions."New value: +"The content for the block, used in \"create-block\" and \"update-block\" actions. Supports all Roam syntax: [[page refs]], ((block refs)), {{[[embed]]: ((uid))}}, {{[[embed-children]]: ((uid))}}, {{[[embed-path]]: ((uid))}}, {{[[TODO]]}}, {{[[table]]}}, {{[[mermaid]]}}, {{word-count}}, :hiccup, etc."

First observedv2.13.0Jan 31, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already mark this as destructive, non-idempotent, and non-read-only, and the description adds critical behavior: actions run in order, the batch is non-transactional, and nested blocks use UID placeholders returned in a uid_map. It also notes Roam-flavored markdown support and the need to load guidelines before use.

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 description is front-loaded with the rate-limit and batch-use rationale, then moves through placeholders, UIDs, and alternatives in a logical order. It is long but mostly earns its length given the complexity, with only minor redundancy around API efficiency.

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 destructive, non-transactional batch mutation tool with an output schema, the description covers the essential gaps: ordering, failure semantics implied by non-transactional execution, UID placeholders, markdown support, and prerequisites. An agent has enough context to choose and invoke it correctly.

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

Parameters5/5

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

Although schema coverage is already 100%, the description adds essential semantics not captured by the schema alone: the {{uid:name}} placeholder syntax with a concrete parent-child example, the returned uid_map, and markdown support inside the string property. This meaningfully reduces invocation errors for nested batch actions.

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

Purpose5/5

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

The description states a specific verb and resource: executes a sequence of low-level block actions (create, update, move, delete) in a single non-transactional batch. It clearly distinguishes this from sequential calls and points to roam_create_outline for simpler outlines.

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?

It explicitly says when to use this tool: multiple block operations, intensive page updates, or revisions. It names the alternative roam_create_outline for simpler sequential outlines and explains that UIDs often must first be retrieved via roam_fetch_page_by_title or search tools.

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