roam-research-mcp 1.4.0 → 2.4.0

package/README.md

@@ -1,13 +1,13 @@
-![](./roam-research-mcp-image.jpeg)
+![Roam Research MCP + CLI](./roam-research-mcp-header.png)
 
-# Roam Research MCP Server
+# Roam Research MCP + CLI
 
 [![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)
-[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)
 
-A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. It supports standard input/output (stdio) and HTTP Stream communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
+A Model Context Protocol (MCP) server and standalone CLI that provides comprehensive access to Roam Research's API functionality. The MCP server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface, while the CLI (`roam`) lets you fetch, search, and import content directly from the command line. Supports multi-graph configurations, write protection, standard input/output (stdio) and HTTP Stream communication. (Personal project, not officially endorsed by Roam Research)
 
 <a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>
 <a href="https://mseep.ai/app/2b3pro-roam-research-mcp"><img width="380" height="200" src="https://mseep.net/pr/2b3pro-roam-research-mcp-badge.png" alt="MseeP.ai Security Assessment Badge" /></a>
@@ -83,56 +83,323 @@ Alternatively, if you have a `.env` file in the project root (which is copied in
 docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp
 ```
 
-## Standalone CLI: roam-import
+## Standalone CLI: `roam`
 
-A standalone command-line tool for importing markdown content directly into Roam Research, without running the MCP server.
+A standalone command-line tool for interacting with Roam Research directly, without running the MCP server. Provides eight subcommands: `get`, `search`, `save`, `refs`, `update`, `batch`, `rename`, and `status`.
 
-### Usage
+### Installation
+
+After building the project, make the command globally available:
+
+```bash
+npm link
+```
+
+Or run directly without linking:
+
+```bash
+node build/cli/roam.js <command> [options]
+```
+
+### Requirements
+
+Same environment variables as the MCP server:
+- `ROAM_API_TOKEN`: Your Roam Research API token
+- `ROAM_GRAPH_NAME`: Your Roam graph name
+
+Configure via `.env` file in the project root or set as environment variables.
+
+---
+
+### `roam get` - Fetch pages, blocks, or TODOs
+
+Fetch content from Roam and output as markdown or JSON.
+
+```bash
+# Fetch a page by title
+roam get "Daily Notes"
+
+# Fetch a block by UID
+roam get "((AbCdEfGhI))"
+roam get AbCdEfGhI
+
+# Output as JSON
+roam get "Daily Notes" --json
+
+# Control child depth (default: 4)
+roam get "Daily Notes" --depth 2
+
+# Flatten hierarchy
+roam get "Daily Notes" --flat
+
+# Fetch TODO items
+roam get --todo
+
+# Fetch DONE items
+roam get --done
+
+# Filter TODOs by page
+roam get --todo -p "January 2nd, 2026"
+
+# Include/exclude filter
+roam get --todo -i "urgent,important" -e "someday"
+
+# Debug mode
+roam get "Daily Notes" --debug
+```
+
+**Options:**
+- `--json` - Output as JSON instead of markdown
+- `--depth <n>` - Child levels to fetch (default: 4)
+- `--refs <n>` - Block ref expansion depth (default: 1)
+- `--flat` - Flatten hierarchy to single-level list
+- `--todo` - Fetch TODO items
+- `--done` - Fetch DONE items
+- `-p, --page <title>` - Filter TODOs/DONEs by page title
+- `-i, --include <terms>` - Include only items containing these terms (comma-separated)
+- `-e, --exclude <terms>` - Exclude items containing these terms (comma-separated)
+- `--debug` - Show query metadata
+
+---
+
+### `roam search` - Search content
+
+Search for blocks containing text or tags.
 
 ```bash
-# From a file
-cat document.md | roam-import "Meeting Notes"
+# Full-text search
+roam search "keyword"
+
+# Multiple terms (AND logic)
+roam search "term1" "term2"
+
+# Tag-only search
+roam search --tag "[[Project]]"
+roam search --tag "#TODO"
+
+# Text + tag filter
+roam search "meeting" --tag "[[Work]]"
+
+# Scope to a specific page
+roam search "task" --page "Daily Notes"
+
+# Case-insensitive search
+roam search "keyword" -i
+
+# Limit results (default: 20)
+roam search "keyword" -n 50
+
+# Output as JSON
+roam search "keyword" --json
+```
+
+**Options:**
+- `--tag <tag>` - Filter by tag (e.g., `#TODO` or `[[Project]]`)
+- `--page <title>` - Scope search to a specific page
+- `-i, --case-insensitive` - Case-insensitive search
+- `-n, --limit <n>` - Limit number of results (default: 20)
+- `--json` - Output as JSON
+- `--debug` - Show query metadata
+
+---
+
+### `roam save` - Import markdown or create TODOs
 
-# From clipboard (macOS)
-pbpaste | roam-import "Ideas"
+Import markdown content to Roam, creating or updating pages, or add TODO items.
+
+```bash
+# From a file (title derived from filename)
+roam save document.md
+
+# With explicit title
+roam save document.md --title "Meeting Notes"
+
+# Update existing page with smart diff (preserves block UIDs)
+roam save document.md --update
+
+# From stdin (requires --title)
+cat notes.md | roam save --title "Quick Notes"
+pbpaste | roam save --title "Clipboard Content"
 
 # From here-doc
-roam-import "Quick Note" << EOF
+roam save --title "Quick Note" << EOF
 # Heading
 - Item 1
 - Item 2
   - Nested item
 EOF
+
+# Create a TODO item on today's daily page
+roam save --todo "Buy groceries"
+
+# Create multiple TODOs from stdin (newline-separated)
+echo -e "Task 1\nTask 2\nTask 3" | roam save --todo
+
+# Pipe TODO list from file
+cat todos.txt | roam save --todo
 ```
 
-### Features
+**Options:**
+- `--title <title>` - Page title (defaults to filename without `.md`)
+- `--update` - Update existing page using smart diff (preserves block UIDs)
+- `-t, --todo [text]` - Add a TODO item to today's daily page (text or stdin)
+- `--debug` - Show debug information
 
-- Reads markdown from stdin
+**Features:**
 - Creates a new page with the specified title (or appends to existing page)
 - Automatically links the new page from today's daily page
-- Converts standard markdown to Roam-flavored markdown (bold, italic, highlights, tasks, code blocks)
+- Converts standard markdown to Roam-flavored markdown
+- Smart diff mode (`--update`) preserves block UIDs for existing content
+- TODO mode creates `{{[[TODO]]}}` items on the daily page
 
-### Installation
+---
 
-After building the project, make the command globally available:
+### `roam refs` - Find references
+
+Find blocks that reference a page or block (backlinks).
 
 ```bash
-npm link
+# Find references to a page
+roam refs "Project Alpha"
+roam refs "December 30th, 2025"
+
+# Find references to a tag
+roam refs "#TODO"
+roam refs "[[Meeting Notes]]"
+
+# Find references to a block
+roam refs "((AbCdEfGhI))"
+
+# Limit results
+roam refs "My Page" -n 100
+
+# Output as JSON (for LLM/programmatic use)
+roam refs "My Page" --json
+
+# Raw output (for piping)
+roam refs "My Page" --raw
 ```
 
-Or run directly without linking:
+**Options:**
+- `-n, --limit <n>` - Limit number of results (default: 50)
+- `--json` - Output as JSON array
+- `--raw` - Output raw UID + content lines (no grouping)
+- `--debug` - Show query metadata
+
+**Output Formats:**
+
+Default output groups results by page:
+```
+[[Reading List: Inbox]]
+  tiTqNBvYA   Date Captured:: [[December 30th, 2025]]
+
+[[Week 53, 2025]]
+  g0ur1z7Bs   [Sun 28]([[December 28th, 2025]]) | [Mon 29](...
+```
+
+JSON output for programmatic use:
+```json
+[
+  {"uid": "tiTqNBvYA", "content": "Date Captured:: [[December 30th, 2025]]", "page": "Reading List: Inbox"}
+]
+```
+
+---
+
+### `roam batch` - Execute multiple operations in one API call
+
+Execute multiple operations in a single batch API call to reduce rate limiting issues.
 
 ```bash
-cat document.md | node build/cli/import-markdown.js "Page Title"
+# From a JSON file
+roam batch commands.json
+
+# From stdin
+cat commands.json | roam batch
+
+# Dry run (validate without executing)
+roam batch --dry-run commands.json
+
+# With debug output
+roam batch --debug commands.json
 ```
 
-### Requirements
+**Command Format:**
 
-Same environment variables as the MCP server:
-- `ROAM_API_TOKEN`: Your Roam Research API token
-- `ROAM_GRAPH_NAME`: Your Roam graph name
+Input is a JSON array of command objects:
 
-Configure via `.env` file in the project root or set as environment variables.
+```json
+[
+  { "command": "create", "params": { "text": "Parent block", "parent": "pageUid", "as": "p1" } },
+  { "command": "create", "params": { "text": "Child block", "parent": "{{p1}}" } },
+  { "command": "todo", "params": { "text": "Task item" } },
+  { "command": "codeblock", "params": { "parent": "{{p1}}", "language": "ts", "code": "const x = 1;" } }
+]
+```
+
+**Supported Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `create` | Create a block |
+| `update` | Update block content |
+| `delete` | Delete a block |
+| `move` | Move block to new location |
+| `todo` | Create TODO item |
+| `table` | Create table structure |
+| `outline` | Create nested outline |
+| `remember` | Create tagged memory |
+| `page` | Create page with content |
+| `codeblock` | Create code block |
+
+**Features:**
+
+- Placeholder references (`{{name}}`) for cross-command dependencies
+- Automatic page title → UID resolution
+- Daily page auto-resolution for `todo` and `remember`
+- Level-based hierarchy for `outline` command
+- `--dry-run` mode for validation
+
+**Options:**
+- `--dry-run` - Validate and show planned actions without executing
+- `--debug` - Show debug information
+- `-g, --graph <name>` - Target graph (multi-graph mode)
+- `--write-key <key>` - Write confirmation key
+
+See [docs/batch-cli-spec.md](docs/batch-cli-spec.md) for full specification.
+
+---
+
+### `roam status` - Show available graphs
+
+Display configured graphs and their connection status.
+
+```bash
+# Show available graphs
+roam status
+
+# Test connectivity to all graphs
+roam status --ping
+
+# Output as JSON
+roam status --json
+```
+
+**Example Output:**
+
+```
+Roam Research MCP v2.4.0
+
+Graphs:
+  • personal (default)  ✓ connected
+  • work [protected]    ✓ connected
+
+Write-protected graphs require --write-key flag for modifications.
+```
+
+**Options:**
+- `--ping` - Test connection to each graph
+- `--json` - Output as JSON for scripting
 
 ---
 
@@ -162,24 +429,25 @@ The server provides powerful tools for interacting with Roam Research:
 
 1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.
 2. `roam_fetch_block_with_children`: Fetch a block by its UID along with its hierarchical children down to a specified depth. Automatically handles `((UID))` formatting.
-3. `roam_create_page`: Create new pages with optional content and headings. **Now supports mixed content types** - content array can include both text blocks and tables in a single call using `{type: "table", headers, rows}` format. Creates a block on the daily page linking to the newly created page.
+3. `roam_create_page`: Create new pages with optional content and headings. **Now supports mixed content types** - content array can include both text blocks and tables in a single call using `{type: "table", headers, rows}` format. Automatically adds a "Processed: [[date]]" block at the end of the page linking to today's daily page.
 4. `roam_create_table`: Create a properly formatted Roam table with specified headers and rows. Abstracts Roam's complex nested table structure, validates row/column consistency, and handles empty cells automatically.
 5. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
 6. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
 7. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. Best for simpler, sequential outlines. For complex nesting (e.g., tables), consider `roam_process_batch_actions`. If `page_title_uid` and `block_text_uid` are both blank, content defaults to the daily page. (Internally uses `roam_process_batch_actions`.)
-8. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
+8. `roam_search_block_refs`: Search for block references within a page or across the entire graph. Now supports `title` parameter to find blocks referencing a page title using `:block/refs` (captures `[[page]]` and `#tag` links semantically).
 9. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
 10. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight), with pagination and sorting options.
 11. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page. This tool supports pagination via the `limit` and `offset` parameters.
 12. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
 13. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
 14. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag. This tool supports pagination via the `limit` and `offset` parameters.
-15. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
+15. `roam_remember`: Add a memory or piece of information to remember. Supports optional `heading` parameter to nest under a specific heading on the daily page (created if missing), or `parent_uid` to nest under a specific block. (Internally uses `roam_process_batch_actions`.)
 16. `roam_recall`: Retrieve all stored memories.
 17. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. Now supports client-side regex filtering for enhanced post-query processing. Optimal for complex filtering (including regex), highly complex boolean logic, arbitrary sorting criteria, and proximity search.
 18. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.
 19. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. **Now includes pre-validation** that catches errors before API execution, with structured error responses and automatic rate limit retry with exponential backoff. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
 20. `roam_update_page_markdown`: Update an existing page with new markdown content using smart diff. **Preserves block UIDs** where possible, keeping references intact across the graph. Uses three-phase matching (exact text → normalized → position fallback) to generate minimal operations. Supports `dry_run` mode to preview changes. Ideal for syncing external markdown files, AI-assisted content updates, and batch modifications without losing block references.
+21. `roam_move_block`: Move a block to a new location (different parent or position). Convenience wrapper around `roam_process_batch_actions` for single block moves. Parameters: `block_uid` (required), `parent_uid` (required), `order` (optional, defaults to "last").
 
 **Deprecated Tools**:
 The following tools have been deprecated as of `v0.36.2` in favor of the more powerful and flexible `roam_process_batch_actions`:
@@ -320,9 +588,13 @@ The tool will match existing blocks by content, update changed text, add new blo
    - Create a new token
 
 2. Configure the environment variables:
-   You have two options for configuring the required environment variables:
 
-   Option 1: Using a .env file (Recommended for development)
+   ### Single Graph Mode (Default)
+
+   For most users with one Roam graph, use the simple configuration:
+
+   **Option 1: Using a .env file (Recommended for development)**
+
    Create a `.env` file in the roam-research directory:
 
    ```
@@ -333,7 +605,8 @@ The tool will match existing blocks by content, update changed text, add new blo
    HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
    ```
 
-   Option 2: Using MCP settings (Alternative method)
+   **Option 2: Using MCP settings (Alternative method)**
+
    Add the configuration to your MCP settings file. Note that you may need to update the `args` to `["/path/to/roam-research-mcp/build/index.js"]` if you are running the server directly.
 
    - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
@@ -359,6 +632,62 @@ The tool will match existing blocks by content, update changed text, add new blo
 
    Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
 
+   ---
+
+   ### Multi-Graph Mode (v2.0.0+)
+
+   For users with multiple Roam graphs, you can configure a single MCP server instance to connect to all of them. This is more token-efficient than running multiple server instances.
+
+   **Configuration:**
+
+   ```json
+   ROAM_GRAPHS="{\"personal\":{\"token\":\"roam-graph-token-xxx\",\"graph\":\"my-personal-graph\"},\"work\":{\"token\":\"roam-graph-token-yyy\",\"graph\":\"company-graph\",\"write_key\":\"confirm-work-write\"}}"
+   ROAM_DEFAULT_GRAPH=personal
+   ```
+
+   | Field | Required | Description |
+   |-------|----------|-------------|
+   | `token` | Yes | Roam API token for this graph |
+   | `graph` | Yes | Roam graph name |
+   | `write_key` | No | Required confirmation string for writes to non-default graphs |
+
+   **Usage in Tools:**
+
+   All tools accept optional `graph` and `write_key` parameters:
+
+   ```json
+   {
+     "title": "My Page",
+     "graph": "work",
+     "write_key": "confirm-work-write"
+   }
+   ```
+
+   - **Read operations**: Can target any graph using the `graph` parameter
+   - **Write operations on default graph**: Work without additional parameters
+   - **Write operations on non-default graphs**: Require the `write_key` if configured
+
+   **CLI Usage:**
+
+   All CLI commands support the `-g, --graph` flag:
+
+   ```bash
+   # Read from work graph
+   roam get "Meeting Notes" -g work
+
+   # Write to work graph (requires --write-key if configured)
+   roam save notes.md -g work --write-key "confirm-work-write"
+   ```
+
+   **Safety Model:**
+
+   The `write_key` serves as a confirmation gate (not a secret) to prevent accidental writes to non-default graphs. When a write is attempted without the required key, the error message reveals the expected key:
+
+   ```
+   Write to "work" graph requires write_key confirmation.
+   Provide write_key: "confirm-work-write" to proceed.
+   ```
+
 3. Build the server (make sure you're in the root directory of the MCP):
 
    Note: Customize 'Roam_Markdown_Cheatsheet.md' with any notes and preferences specific to your graph BEFORE building.

package/build/Roam_Markdown_Cheatsheet.md

@@ -1,4 +1,4 @@
-# Roam Markdown Cheatsheet — Generic Foundation v2.0.0
+# Roam Markdown Cheatsheet — Generic Foundation v2.0.1
 
 > ⚠️ **MODEL DIRECTIVE**: Always consult this cheatsheet BEFORE making any Roam tool calls. Syntax errors in Roam are unforgiving.
 
@@ -36,6 +36,8 @@
 
 ⚠️ **CRITICAL**: Never concatenate multi-word tags. `#knowledgemanagement` ≠ `#[[knowledge management]]`
 
+⚠️ **CRITICAL**: Never use `#` to mean "number" (e.g., `#1`, `#2`). In Roam, `#` **always** creates a hashtag. Write `Step 1`, `No. 1`, or just spell out the number instead.
+
 ### Dates
 - **Always use ordinal format**: `[[January 1st, 2025]]`, `[[December 23rd, 2024]]`
 - Ordinals: 1st, 2nd, 3rd, 4th–20th, 21st, 22nd, 23rd, 24th–30th, 31st
@@ -72,7 +74,7 @@ Source:: https://example.com
 | `Note:: Some observation` | Just write the text, or use `#note` | One-off labels don't need attribute syntax |
 | `Summary:: The main point` | `**Summary:** The main point` | Section headers are formatting, not metadata |
 | `Definition:: Some text` | `Term:: Definition` | Only use for actual definitions you want to query |
-| `Implementation Tier 3 (Societal Restructuring):: Some text` | `** Implementation Tier 3 (Societal Restructuring)**: Some text` | Label is specific to current concept |
+| `Implementation Tier 3 (Societal Restructuring):: Some text` | `**Implementation Tier 3 (Societal Restructuring):** Some text` | Label is specific to current concept |
 
 ⚠️ **The Test**: Ask yourself: "Will I ever query for all blocks with this attribute across my graph?" If no, use **bold formatting** (`**Label:**`) instead of `::` syntax.
 
@@ -174,6 +176,7 @@ Tables use nested indentation. Each column header/cell nests ONE LEVEL DEEPER th
 |----------|-----------|-----|
 | `Step 1:: Do this` | `**Step 1:** Do this` | `::` creates queryable attributes; use bold for page-specific labels |
 | `#multiplewords` | `#[[multiple words]]` | Concatenated tags create dead references |
+| `#1`, `#2`, `#3` | `Step 1`, `No. 1`, or spell out | `#` always creates hashtags, never means "number" |
 | `[[january 1, 2025]]` | `[[January 1st, 2025]]` | Must use ordinal format with proper capitalization |
 | `[text](((block-uid)))` | `[text](<((block-uid))>)` | Block ref links need angle bracket wrapper |
 | `{{embed: ((uid))}}` | `{{[[embed]]: ((uid))}}` | Embed requires double brackets around keyword |
@@ -198,9 +201,17 @@ CREATING CONTENT IN ROAM:
 │   └─ Complex/nested markdown → roam_import_markdown
 │       (for deeply nested content, tables, etc.)
 │
+├─ Replacing/revising ENTIRE page content?
+│   └─ roam_update_page_markdown
+│       (fetches page internally, computes smart diff, preserves UIDs)
+│
 ├─ Need to CREATE, UPDATE, MOVE, or DELETE individual blocks?
 │   └─ roam_process_batch_actions
-│       (fine-grained control, temporary UIDs for parent refs)
+│       (fine-grained control, UID placeholders for parent refs)
+│
+├─ Creating a TABLE?
+│   └─ roam_create_table
+│       (handles complex nested structure automatically)
 │
 ├─ Adding a memory/note to remember?
 │   └─ roam_remember (auto-tags with MEMORIES_TAG)
@@ -210,9 +221,11 @@ CREATING CONTENT IN ROAM:
 │
 └─ SEARCHING/READING:
     ├─ Find by tag → roam_search_for_tag
-    ├─ Find by text → roam_search_by_text  
+    ├─ Find by text → roam_search_by_text
     ├─ Find by date range → roam_search_by_date
     ├─ Find by status → roam_search_by_status
+    ├─ Find block/page references → roam_search_block_refs
+    ├─ Find pages modified today → roam_find_pages_modified_today
     ├─ Get page content → roam_fetch_page_by_title
     ├─ Get block + children → roam_fetch_block_with_children
     ├─ Recall memories → roam_recall
@@ -226,18 +239,18 @@ CREATING CONTENT IN ROAM:
 The Roam API has rate limits. Follow these guidelines to minimize API calls:
 
 ### Tool Efficiency Ranking (Best to Worst)
-1. **`roam_process_batch_actions`** - Single API call for multiple operations (MOST EFFICIENT)
-2. **`roam_create_page`** - Batches content with page creation
-3. **`roam_create_outline` / `roam_import_markdown`** - Include verification queries (use for smaller operations)
-4. **Multiple sequential tool calls** - Each call = multiple API requests (AVOID)
+1. **`roam_update_page_markdown`** - Single call: fetches, diffs, and updates (MOST EFFICIENT for revisions)
+2. **`roam_process_batch_actions`** - Single API call for multiple operations
+3. **`roam_create_page`** - Batches content with page creation
+4. **`roam_create_outline` / `roam_import_markdown`** - Include verification queries (use for smaller operations)
+5. **Multiple sequential tool calls** - Each call = multiple API requests (AVOID)
 
 ### Best Practices for Intensive Operations
 
 #### When Updating/Revising a Page:
-1. Fetch the page content ONCE at the start
-2. Plan ALL changes needed (creates, updates, deletes)
-3. Execute ALL changes in a SINGLE `roam_process_batch_actions` call
-4. Do NOT fetch-modify-fetch-modify in a loop
+1. **Preferred**: Use `roam_update_page_markdown` — it fetches, diffs, and updates in one call
+2. **Alternative** (for fine-grained control): Fetch once with `roam_fetch_page_by_title`, then execute ALL changes in a SINGLE `roam_process_batch_actions` call
+3. Do NOT fetch-modify-fetch-modify in a loop
 
 #### When Creating Large Content:
 - For 10+ blocks: Use `roam_process_batch_actions` with nested structure
@@ -285,6 +298,11 @@ When using `roam_process_batch_actions` to create nested blocks, use **placehold
 
 **Do this:**
 ```
+1. roam_update_page_markdown → single call handles fetch, diff, and updates
+```
+
+**Alternative** (when you need fine-grained control):
+```
 1. roam_fetch_page_by_title → get page UID and content
 2. roam_process_batch_actions → ALL creates/updates in one call
 ```