Roam Research

roam_create_table

Create properly formatted Roam tables from specified headers and row data, automatically handling nested block structure and validating row/column consistency.

Instructions

Create a table in Roam with specified headers and rows. This tool abstracts the complex nested structure that Roam tables require, making it much easier to create properly formatted tables.

Why use this tool:

Roam tables require precise nested block structures that are error-prone to create manually
Automatically handles the {{[[table]]}} container and nested column structure
Validates row/column consistency before execution
Converts empty cells to spaces (required by Roam)

Example: A table with headers ["", "Column A", "Column B"] and rows [{label: "Row 1", cells: ["A1", "B1"]}] creates a 2x3 table.

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	Default
`rows`	Yes	Data rows for the table. Each row has a label (first column) and cells (remaining columns).
`graph`	No	Target graph key from ROAM_GRAPHS config. Defaults to ROAM_DEFAULT_GRAPH. Only needed in multi-graph mode.
`order`	No	Optional: Position under the parent. Can be a number (0-based) or "first"/"last". Defaults to "last".	last
`headers`	Yes	Column headers for the table. The first header is typically empty (for the row label column). Example: ["", "Option A", "Option B"]
`write_key`	No	Write confirmation key. Required for write operations on non-default graphs when write_key is configured.
`parent_uid`	Yes	The UID of the parent block or page where the table should be created.

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.
`table_uid`	No
`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"
+    },
+    "table_uid": {
+      "type": "string"
+    },
+    "uid_map": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Placeholder name → generated UID. Present only on success.",
+      "type": "object"
+    },
+    "validation_passed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "success"
+  ],
+  "type": "object"
+}

First observedv2.13.0Jan 31, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world behavior; the description adds real value beyond them by disclosing validation of row/column consistency, automatic conversion of empty cells to spaces, and the {{[[table]]}} container handling. It does not describe failure behavior when validation fails or how the graph/write_key gating interacts with non-default graphs.

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

Conciseness3/5

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

Purpose is front-loaded and the bullets are scannable, but 'abstracts the complex nested structure... making it much easier to create properly formatted tables' is redundant with the bullet list that follows. The critical session prerequisite is buried at the end rather than front-loaded.

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

Completeness4/5

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

With an output schema present and annotations covering the safety profile, the description needn't explain return values; it covers prerequisites, validation, and the empty-cell edge case, which is what an agent needs to call this correctly. Remaining gap is error/failure signaling when row lengths mismatch.

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; the description goes further with a worked example (headers ["", "Column A", "Column B"] plus one labeled row yields a 2x3 table) that makes the header-count-to-cell-count relationship for `headers`/`rows` concrete. It says nothing about `graph`, `order`, or `write_key`, but those are fully documented in the schema.

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?

States a specific verb and resource: "Create a table in Roam with specified headers and rows." The 'Why use this tool' bullets clarify the value versus hand-building nested {{[[table]]}} blocks, though it never names a sibling (e.g., roam_create_outline or roam_import_markdown) as the alternative for tabular content.

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

Usage Guidelines4/5

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

The 'Why use this tool' list effectively describes when this tool is the right choice over manual block construction, and the IMPORTANT line gives an explicit prerequisite (call roam_get_guidelines and load the cheatsheet once per session). No explicit 'do not use this for X, use Y instead' exclusion is provided.

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