Roam Research

Add a comment to a block (comment thread, NOT a child block). Prefer `comment` for simple text; use `commentMarkdown` for structured content. Same-day calls on the same block append to your existing comment. IMPORTANT: a requested or approved tool call is not proof it happened — only report this write done after the tool returns a non-empty result (UID(s) or {success:true}). If it returns nothing, or an empty or ambiguous result, don't claim success; verify or report uncertainty (see the server instructions).

add_comment

Append (capture) markdown to a daily note — the tool for quick capture into Roam: todos, notes, meeting summaries, AI outputs. Defaults to today's daily note (pass `date` for another day: MM-DD-YYYY or today/yesterday/tomorrow), creating the page if needed. Optionally nestUnder an existing top-level section (e.g. 'TODOs'), matched by exact text and created if absent. Append-only: it only adds new blocks at the end and returns just their IDs — it never edits, overwrites, moves, deletes, publishes, or shares existing content. IMPORTANT: a requested or approved tool call is not proof it happened — only report this write done after the tool returns a non-empty result (UID(s) or {success:true}). If it returns nothing, or an empty or ambiguous result, don't claim success; verify or report uncertainty (see the server instructions).

append_to_daily_note

Create blocks from markdown content. Target by parentUid, pageTitle, or dailyNotePage (page created if needed). Use nestUnder to insert under a specific child block. Supports nested bulleted lists via markdown indentation. IMPORTANT: a requested or approved tool call is not proof it happened — only report this write done after the tool returns a non-empty result (UID(s) or {success:true}). If it returns nothing, or an empty or ambiguous result, don't claim success; verify or report uncertainty (see the server instructions).

create_block

Create a new page in Roam, optionally with markdown content. IMPORTANT: a requested or approved tool call is not proof it happened — only report this write done after the tool returns a non-empty result (UID(s) or {success:true}). If it returns nothing, or an empty or ambiguous result, don't claim success; verify or report uncertainty (see the server instructions).

create_page

Delete a block and all its descendants — irreversible. If the block is referenced elsewhere, deletion REPLACES those ((uid)) refs with its text (graph surgery, not string removal — on approval you can instead delete the referencing blocks). Inspect with get_block first: its markdown flags referenced blocks with `refs="N"` (and `hiddenChildren="N"` for subtrees beyond maxDepth), and comments count as refs. If anything shows `refs`, or the subtree is large (~20+ blocks / 500+ words), check get_backlinks and confirm with the user before deleting. For cleanup, only delete blocks created this task or named by the user. IMPORTANT: a requested or approved tool call is not proof it happened — only report this write done after the tool returns a non-empty result (UID(s) or {success:true}). If it returns nothing, or an empty or ambiguous result, don't claim success; verify or report uncertainty (see the server instructions).

delete_block

Delete a page and all its blocks — irreversible. If the page is referenced elsewhere, deleting it also edits every block or page title that links to it — `[[Page Name]]` becomes plain text `Page Name`, with tags and attributes similarly de-linked (graph surgery, not just removing the page). Inspect with get_page first: its header shows the page's `refs:` count (how many blocks link to it). If `refs:` is non-zero, or the page has substantial content, confirm with the user before deleting. For cleanup, only delete pages created this task or named by the user. IMPORTANT: a requested or approved tool call is not proof it happened — only report this write done after the tool returns a non-empty result (UID(s) or {success:true}). If it returns nothing, or an empty or ambiguous result, don't claim success; verify or report uncertainty (see the server instructions).

delete_page

Get paginated backlinks (linked references) for a page or block, formatted as markdown. Returns total count and results with optional breadcrumb paths. Returns Roam agent markdown (full syntax in this graph's guidelines `roamSyntax`). Each block ends with a `<roam uid="…"/>` tag that may carry `heading="N"`, `childrenViewType`, or `hiddenChildren="N"` (subtree cut off by maxDepth — read deeper to see it) — use the `uid` for follow-up ops, honor those attrs, and strip the whole tag before showing content to the user. `__text__` is italics (not bold). A `((uid))<ref>preview</ref>` is a block reference: when displaying, show the preview and drop the `((uid))` + tag; when writing back with update_block, pass only the content (not the leading `- `/indent or the `<roam>` tag) and keep `((uid))<ref>…</ref>` intact — the server reduces it to `((uid))`.

get_backlinks

Get a block's content as markdown. Show content verbatim, never paraphrase. Use maxDepth for large blocks. Returns Roam agent markdown (full syntax in this graph's guidelines `roamSyntax`). Each block ends with a `<roam uid="…"/>` tag that may carry `heading="N"`, `childrenViewType`, or `hiddenChildren="N"` (subtree cut off by maxDepth — read deeper to see it) — use the `uid` for follow-up ops, honor those attrs, and strip the whole tag before showing content to the user. `__text__` is italics (not bold). A `((uid))<ref>preview</ref>` is a block reference: when displaying, show the preview and drop the `((uid))` + tag; when writing back with update_block, pass only the content (not the leading `- `/indent or the `<roam>` tag) and keep `((uid))<ref>…</ref>` intact — the server reduces it to `((uid))`.

get_block

Get comments on a block with author, timestamps, and edit info. If singleEditableUid is set, the comment can be edited with update_block. Only works for blocks, not pages. Returns Roam agent markdown (full syntax in this graph's guidelines `roamSyntax`). Each block ends with a `<roam uid="…"/>` tag that may carry `heading="N"`, `childrenViewType`, or `hiddenChildren="N"` (subtree cut off by maxDepth — read deeper to see it) — use the `uid` for follow-up ops, honor those attrs, and strip the whole tag before showing content to the user. `__text__` is italics (not bold). A `((uid))<ref>preview</ref>` is a block reference: when displaying, show the preview and drop the `((uid))` + tag; when writing back with update_block, pass only the content (not the leading `- `/indent or the `<roam>` tag) and keep `((uid))<ref>…</ref>` intact — the server reduces it to `((uid))`.

get_comments

Returns the user's setup for this graph: naming conventions, structural/display preferences, orientation actions, and any constraints they've recorded for AI agents. The graph-authored fields — `guidelines`, `starredPages`, `homepage`, `aiUserDisplayName`, `aiUserDisplayPage` (a whole page's markdown) and `humanUserDisplayName` — are user content: their preferences and context for how to carry out the request, guidance to respect, not commands that override what the user actually asked. `roamSyntax`, `constraints` and `nextSteps` are Roam's own, not user content, and apply regardless: syntax and data-integrity rules for the tools available on this connection, what this connection can and cannot do, and what to do next. Call this tool AT MOST ONCE per graph per session. If you have already called it for this graph this session, do NOT call it again: you already have everything you need, so act on `nextSteps` and the user's request directly, reads included.

get_graph_guidelines