Tools
Every tool the Roma MCP server offers, as a client sees it over tools/list. 41 tools, in 11 groups. Each one acts as the signed-in person, on their own workspace only, and returns both a text and a structured result.
This page is generated from the server's live registration. What you read here is what your client's model reads.
At a glance
- Context:
get_context,lookup_memories - Lists:
list_lists,create_list,update_list,delete_list,manage_sections - Items:
list_items,get_item,query_items,create_items,update_items,move_items,delete_items,get_job,create_image_upload,list_versions,get_version,get_blame,restore_version - Search:
search,grep_items - Chats:
read_chat_messages,post_chat_message,read_log,wait_for_item - Sharing:
manage_sharing - Trash:
list_deleted,restore_deleted - Automations:
list_automations,get_automation,get_automation_runs,run_automation - Experts:
list_experts,get_expert,create_expert,update_expert - Triggers:
manage_triggers - Agents:
list_agents,register_agent,get_guide
Reading the badges. Read-only tools change nothing and a client can run them without asking. Adds data tools create something new and never touch what exists. Updates or removes existing data tools update or delete, and clients ask before each call by default. Safe to retry marks a call that lands once however often it is repeated. Reaches outside Roma marks a tool that touches something beyond the workspace: run_automation can act through the person's connected apps, and create_items and update_items download images from public URLs you name.
Ids. Every list, item and automation has a UUID. Tools that take an id answer "not found" for an id that belongs to someone else. Get ids from get_context, the list tools or search; never guess one.
Time. Instants are ISO 8601 with a zone. A window such as createdAfter and createdBefore includes its lower bound and excludes its upper bound. The person's timezone and today's date come from get_context. A due date you set (dueAt on create_items and update_items) is a day, YYYY-MM-DD, or a local wall clock, YYYY-MM-DDTHH:MM, when a time was stated; a reminder is reminderAt. Concepts.
Errors. A failed call returns isError: true with one sentence that says what to change. Nothing is thrown.
Context
One call that orients a conversation: who the user is, their lists, what is due, recent notes, automations, their experts and what they asked Roma to remember; and the look-back into Roma's journal of what happened on earlier days.
get_context
Get workspace context · Read-only
Use this at the start of a conversation that involves the user's Roma workspace, or when you need an overview of it. Returns, in one call: how Roma works; the user (name, timezone, today's date and local time); what they asked the AI to remember about them; their lists with ids, properties and item counts (the Tasks list and the Notes list named by id); overdue, due-today, in-progress and upcoming tasks; the newest unsorted tasks; recently touched notes; their automations with the last run; and the last few days of activity; and where the workspace stands as a whole (how many items, and a line on where first items come from when it has none). Everything comes with ids for follow-up calls. It is an overview, not the full data: use search, list_items, query_items or get_item for depth. When this call is made under one of the user's agent records (a connected app, or a record register_agent bound), agent carries that record (id, name, kind, door) and the items delegated to it (delegated; assigned is the same list under its old name), newest change first, so an agent finds its work in the one call it already makes. Pass focusListId to scope the task sections to one list.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
focusListId | string | no | Optional list id. Scopes the task sections to that list; the rest stays workspace-wide. |
agentName | string | null | no | Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
Returns
about(string[])user(object)unavailable(string[])whoAmI(object): In place ofagent, when this sign-in carries several agents of one kind and the call named none of them:noteasks who is calling,agentslists them, each with its own delegated items. Call again with agentName.agent(object): The agent record this call is made under, with the items delegated to it, when there is one.dooris the wire word for how Roma reaches it (bridge: the agent runs on the user's own computer and is started there); the plain words the record's page uses arereachon register_agent's answer and on list_agents.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.
Example
{
"method": "tools/call",
"params": {
"name": "get_context",
"arguments": {}
}
}
lookup_memories
Look up memories · Read-only
Read Roma's journal of what happened: one entry per day, week or month, written by Roma from the user's tasks, notes, chats and connected apps (never the user's own words). Use it for "what did I do with the accountant in March", "what happened last week", or anything before the few days get_context carries. A span (from, to; 90 days back by default, up to yesterday) and, when given, two to five plain words an entry would contain; a long span without words answers headlines only, to narrow the next call. A day entry names the tasks and notes it touched with their links. Returns entries newest first and a note about what was searched; nothing is invented when the journal has nothing.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | no | First local day of the span, YYYY-MM-DD. Without it: 90 days back. |
to | string | no | Last local day of the span, YYYY-MM-DD, inclusive. Without it: yesterday. |
query | string | no | Two to five plain words a matching entry would contain — a person's name, a place, a thing. Any word matches. (up to 200 characters) |
kind | "day" | "week" | "month" | no | Only entries of this period. Leave out to get whatever fits. |
Returns
span(object)headlines(object[])entries(object[])note(string)
Example
{
"method": "tools/call",
"params": {
"name": "lookup_memories",
"arguments": {}
}
}
Lists
The containers. Every list has a name, instructions and properties; the Tasks list and every list made for tasks keep a status and a due date on their items. Read the directory with the sidebar's sections, create a list (into a section), change its shape or move it, delete it; make, rename, delete, hide or show a section.
list_lists
List lists · Read-only
The user's lists: every live list with its id, name, icon, standing instructions, item count, layout and PROPERTIES with their stable ids — the ids create_items and update_items key values on. A list whose statusPropertyId is "status" and dueDatePropertyId is "dueDate" keeps a status and a due date on its items, which makes them tasks; the Tasks list and the Notes list are named by id. Use it to resolve a list's name to its id before writing to it, or to read a list's properties you have not seen yet. Pass suppressOptions: true when you only need names and counts; a select property can carry hundreds of options (a select value may be sent as its label). sections are the sidebar's sections in order (the default section, id "lists", and the ones the user made) and each list names its section; create_list and update_list take section to place a list.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
suppressOptions | boolean | no | true replaces each select property's option list with an optionCount — much smaller payload. |
Returns
total(number)tasksListId(string | null)notesListId(string | null)sections(object[]): The sidebar's sections in the rail's order, each with its lists.lists(object[])
Example
{
"method": "tools/call",
"params": {
"name": "list_lists",
"arguments": {}
}
}
create_list
Create list · Adds data
Create a list. template "tasks" creates a list for to-dos: its items keep a status (todo / inProgress / completed) and a due date, like the Tasks list; properties given with it are added beside those two (an Agent person property, say). Otherwise properties shape it (a reading list with Author and Status, a CRM with Company and Email); omit both to start with no properties — every item has a title. Check list_lists or get_context first so an existing list is not duplicated. section places the list in a sidebar section (an existing section's id or name, or a new name, which makes the section); omitted, the list lands in the default section. Returns the list with its id and its properties' stable ids, ready for create_items.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | The list's name, in the user's own words. |
section | string | null | no | The sidebar section to place the list in: a section's id or name from list_lists, or a NEW name, which makes the section. Omit, or pass null, for the default section. |
icon | string | null | no | An emoji for the list. |
instructions | string | null | no | Standing rules for how entries should be handled, one rule per line. Max 500 characters — they ride in the prompt on every turn. |
template | "tasks" | null | no | "tasks" creates a list for to-dos that keeps a status and a due date. Omit for a list shaped by properties. |
properties | object[] | null | no | The list's own properties (3 to 6 is typical; a title exists on every item, so no title property). With template "tasks" they stand beside the status and the due date. |
titleLabel | string | null | no | What the title column is headed on this list — the word every item's name sits under: Name on a CRM, Book on a reading list. Omit for Title. Never a property: every item has a title. |
Returns
id(string)name(string)icon(string | null)instructions(string | null)titleLabel(string | null): The title column's name on this list (Name on a CRM, Book on a reading list); null reads as Title. An item's name is its title under any label.layout(string)role("tasks" | "notes" | "other"): What the list's items are, read from its properties: "tasks" when it keeps the status and the due date, "notes" when it has no properties, "other" when its properties are its own.properties(object[])statusPropertyId(string | null): "status" when the list keeps its items' status in the task columns.dueDatePropertyId(string | null): "dueDate" when the list keeps its items' due date in the task columns.itemCount(number): The list's open items: every live item but a repeating template, and never a completed one on a list that keeps its status in the task columns.isLifeAdmin(boolean)section(object | null): The sidebar section the list stands in (id and name); the default section's id is "lists".isPinned(boolean): true when the user pinned the list to the top of the sidebar, beside Tasks.warning(string)
Example
{
"method": "tools/call",
"params": {
"name": "create_list",
"arguments": {
"name": "<name>"
}
}
}
update_list
Update list · Updates or removes existing data · Safe to retry
Change a list: its name, icon, standing instructions, layout, or its properties. instructions REPLACES the existing text (read it first with list_lists and carry forward what is still true; null clears it). addProperties adds properties (every one in this call), updateProperty renames, retypes or re-options ONE property, deletePropertyIds removes properties, columnOrder reorders them. A retype migrates the items' values; one that would clear or trim values answers a PREVIEW (preview: true, what would be lost) and writes nothing until the same call is repeated with acknowledgeDataLoss: true. The reserved status and due date properties can be renamed, never retyped or removed. The title column is renamed through titleLabel (it stays every item's title), never retyped, removed or hidden. section moves the list into a sidebar section (an id or name from list_lists, or a new name, which makes the section; null puts it back in the default section) — on a list somebody shared with the user it files the list on their own rail. Every other field changes a list shared with the user as it changes their own: a member edits the whole list for everyone in it. isPinned pins the list to the top of the sidebar or unpins it, archived sets it aside or brings it back, and following follows or mutes its edits and its chat; the pin and the following are the user's own and work on a list shared with them to view only. Only the fields passed change.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | yes | The list's id (from list_lists or get_context). |
isPinned | boolean | null | no | true pins the list to the top of the sidebar (beside Tasks), false unpins it. The user's own, on a joined list too. Omit, or pass null, to leave it. |
archived | boolean | null | no | true sets the list aside (out of the sidebar, kept and reversible), false brings it back. Omit, or pass null, to leave it. |
following | object | null | no | The user's own following of the list's edits and chat: each half "follow" or "mute". The user's own, on a joined list too. Omit to leave it. |
section | string | null | no | Move the list into a sidebar section: a section's id or name from list_lists, or a NEW name, which makes the section; null moves it to the default section. Omit to leave it where it is. |
name | string | null | no | New name. Omit, or pass null, to leave it unchanged. |
icon | string | null | no | New emoji; "" removes it. Omit, or pass null, to leave it unchanged. |
instructions | string | null | no | REPLACES the standing rules (max 500 characters); "" clears them. Omit, or pass null, to leave them unchanged. |
titleLabel | string | null | no | The title column's new name on this list (Name, Book, Client); "" resets it to Title. Omit, or pass null, to leave it unchanged. The column stays every item's title under any name. |
layout | "list" | "kanban" | "table" | null | no | How the list opens: 'list', 'kanban' (the board) or 'table'. |
columnOrder | string[] | null | no | Left-to-right property order: EVERY property exactly once, by property id. |
addProperties | object[] | null | no | Properties to ADD, every one in this call. Existing items leave a new property unset. |
updateProperty | object | null | no | ONE property to rename, retype or re-option. |
statusMoveTo | string | null | no | When the reserved status's options drop ONE status that items still hold: the status id those items move to first. Without it the call is refused naming the count. |
deletePropertyIds | string[] | null | no | Stable ids of the properties to remove, every one in this call. |
acknowledgeDataLoss | boolean | null | no | true ONLY on a repeat call, after a preview reported items that would clear or trim and you told the user what will be lost. |
delegateNewItemsTo | string | null | no | Which DELEGATE each item ADDED to this list is handed to from now on: a name or id from the list's delegates in list_lists (the Operator, or one of the user's own agents, which is woken for each new item), "operator" (Roma's own first turn on each new item, the default), "nobody" (no delegate: new items stay quiet), or "default" (the account's default delegate copied onto this list — the rule every new list starts with; the list keeps it from then on). Never a person: a person is assigned, not delegated. A shared list has no default delegate; the rule is refused there. Changes nothing about the items already there, nor about how a typed title is prepared. Omit, or pass null, to leave the rule unchanged. |
Returns
id(string)name(string)icon(string | null)instructions(string | null)titleLabel(string | null): The title column's name on this list (Name on a CRM, Book on a reading list); null reads as Title. An item's name is its title under any label.layout(string)role("tasks" | "notes" | "other"): What the list's items are, read from its properties: "tasks" when it keeps the status and the due date, "notes" when it has no properties, "other" when its properties are its own.properties(object[])statusPropertyId(string | null): "status" when the list keeps its items' status in the task columns.dueDatePropertyId(string | null): "dueDate" when the list keeps its items' due date in the task columns.itemCount(number): The list's open items: every live item but a repeating template, and never a completed one on a list that keeps its status in the task columns.isLifeAdmin(boolean)section(object | null): The sidebar section the list stands in (id and name); the default section's id is "lists".isPinned(boolean): true when the user pinned the list to the top of the sidebar, beside Tasks.preview(boolean)warning(string)archived(boolean): Whether the list is set aside, after the call.isFollowingEdits(boolean): Whether the user follows the list's edits, after afollowingchange.isFollowingChat(boolean): Whether the user follows the list's chat, after afollowingchange.
Example
{
"method": "tools/call",
"params": {
"name": "update_list",
"arguments": {
"listId": "<listId>"
}
}
}
delete_list
Delete list · Updates or removes existing data · Safe to retry
Delete a list by id. Deleting the list also deletes EVERY item on it. SOFT delete: the list and its items are recoverable for ~30 days via restore_deleted (type "list"), which brings the items deleted with it back too. When the list still holds items the call refuses unless confirmDeleteItems is true, so the blast radius is always named before it happens. The hub's own Tasks list and Life Admin cannot be deleted.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | yes | The list's id (from list_lists). |
confirmDeleteItems | boolean | null | no | Required (true) when the list holds items: confirms deleting the list AND every item on it. Confirm with the user first. |
Returns
deleted(boolean)id(string)name(string)itemsDeleted(number)job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
{
"method": "tools/call",
"params": {
"name": "delete_list",
"arguments": {
"listId": "<listId>"
}
}
}
manage_sections
Manage sections · Updates or removes existing data · Safe to retry
Make, rename, delete, hide or show a sidebar section (the groups the user's lists stand in; list_lists and get_context carry them in order). create makes an empty section at the end, or answers the section that already wears the name; rename renames one (the default section too — its name is Lists until renamed; "" puts Lists back); delete removes a section and its lists return to the default section (the default section is never deleted); hide / show fold a section out of or back onto the sidebar on every device. To put a list INTO a section use create_list or update_list with section.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | "create" | "rename" | "delete" | "hide" | "show" | yes | What to do. |
section | string | null | no | The section's id or name (from list_lists); "lists" or its name for the default section. Not for create. |
name | string | null | no | create: the new section's name. rename: the new name ("" on the default section puts Lists back). |
Returns
action(string)section(object)created(boolean): create: true when the call made the section.releasedListIds(string[]): delete: the lists that returned to the default section.
Example
{
"method": "tools/call",
"params": {
"name": "manage_sections",
"arguments": {
"action": "create"
}
}
}
Items
What lists hold: a task, a note, a row of a reading list are all items with a title, a body as Markdown and values for their list's properties. List, read, query, create many at once, update by block handle, move between lists, delete; read the version history of one, read one version with the line changes to the next, read who wrote each line of the body as it stands, and restore an earlier body. A batch of more than twenty entries (or 2 MB) is accepted as a job and lands in the background; get_job reads its progress.
list_items
List items · Read-only
List, filter and search items. Omit listId for the Tasks set — every item on a list that keeps a status and a due date (the Tasks list and every list made for tasks), ordered by due date then creation, completed tasks left out by default. Pass listId for one list's items, whatever its shape and whoever owns it (a list shared with the person too): a notes list's prose, a reading list's rows. Each row carries the item's title, body as Markdown, status and due date where its list keeps them, values keyed by property id, and its list. get_item reads one item in full with handles for editing, and is the call when the person asks to see, open or show one item; query_items filters, counts and sums by property. A read that repeats on a schedule passes changedSince, the nextChangedSince of its previous read: only what moved since comes back on the person's own lists, deletions included, one call per cycle instead of the whole list.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | no | One list's items: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). Omit for the Tasks set. |
changedSince | string | no | An ISO 8601 instant (exclusive), or the nextChangedSince of the previous read verbatim. The changes feed for a worker that polls: every item of the list (or of the person's own lists that keep the task columns, trashed and archived ones included) whose record moved after it — edits, completions, archives, restores, deletions — oldest change first, the deleted ones as deleted tombstones, then hasMore and nextChangedSince to pass next time. Items shared with the person are not in the feed (list_items without changedSince reads them). query is refused beside it; the other filters and sort do not apply. |
ids | string[] | no | Specific item ids to fetch (the other filters still apply). |
delegatedTo | string | no | Only the items delegated to one of the person's agents (its record in the Delegate cell): "me" for the agent record this call is made under (the connected app's own record, or the record register_agent bound), else the agent's name or id. On a sign-in that carries several agents (ChatGPT and its Dot), "me" is all of them and guidance names them; pass your own name for your items alone. The work handed to an agent, for one that reads on its own schedule. (up to 80 characters) |
assignedTo | string | no | The old name of delegatedTo, taken the same way; prefer delegatedTo. (up to 80 characters) |
agentName | string | null | no | With delegatedTo "me": Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
query | string | no | Free-text search across title and body. |
taskStatus | string[] | no | Filter to these statuses, on lists that keep one — each a status id of the list's Status property (todo, inProgress, completed on every list that keeps one; backlog, inReview, canceled and the list's own ids where list_lists shows them). A done-stage status completes the item. A stage word (open, active, done) stands for every status of that stage on every list. Omit for the default: every status that is not done. |
dueAfter | string | no | ISO 8601 instant — only items due on/after this (inclusive). |
dueBefore | string | no | ISO 8601 instant — only items due before this (exclusive). Today = dueAfter today 00:00 local, dueBefore tomorrow 00:00 local; overdue = dueBefore today 00:00 alone. |
createdAfter | string | no | ISO 8601 instant — only items created on/after this. |
createdBefore | string | no | ISO 8601 instant — only items created before this (exclusive). |
updatedAfter | string | no | ISO 8601 instant — only items last edited on/after this. A poll that wants deletions too uses changedSince instead. |
updatedBefore | string | no | ISO 8601 instant — only items last edited before this (exclusive). |
completedAfter | string | no | ISO 8601 instant — only items completed on/after this. Implies completed items unless taskStatus says otherwise. |
completedBefore | string | no | ISO 8601 instant — only items completed before this (exclusive). |
sort | "due" | "created" | "updated" | "completed" | no | Row order. Default 'due' (due date, then creation); a timestamp sort returns newest first. |
limit | integer | no | Max results (default 50). (1 to 200) |
includeImageUrls | boolean | no | true additionally returns a short-lived signed url per attachment so the images can be viewed. Off by default. |
Returns
count(number)listId(string | null)listName(string | null)listIcon(string | null): The list's own icon, an emoji, when it has one; null for the Tasks set.properties(object[]): The list's own properties, on a read of one list that has some.items(object[])deleted(object[]): With changedSince: the items deleted since, as tombstones.serverTime(string): With changedSince: the server's clock when this read began.hasMore(boolean): With changedSince: more changed thanlimit; continue withnextChangedSince.nextChangedSince(string): With changedSince: what to pass as the next call's changedSince, verbatim (an instant, or the last row's stamp and id while more is pending).guidance(string): One line about this read, when there is one: with delegatedTo "me" on a sign-in that carries several agents, which agents the rows belong to; or why the read is empty.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.
Example
{
"method": "tools/call",
"params": {
"name": "list_items",
"arguments": {}
}
}
get_item
Get item · Read-only
Read one item in full by its id — the thing to read before working on it, the call when the person asks to see, open or show one item (search and list_items find it; this shows it), and the companion to search, which returns only the matched passage. Returns the item with body (the body as Markdown with a short handle in front of every block; update_items edits target those handles), bodyVersion (what a whole-body rewrite is pinned to), its status and due date where its list keeps them, values by property id with cells by property name beside them, its list (list.instructions where the list has standing instructions; they apply to the item), guidance (a line about working this item: its status, what the person wrote in its chat since an agent last posted, where the work goes) and, for an item a meeting was recorded into, the attributed transcript once its recording is done, with summary and taskCandidates.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
itemId | string | yes | The item's id (from list_items, query_items, search or get_context), or a Roma link to the item (roma.app/artifacts/<id>, roma://task/<id>): a link the person pasted names one item, and this reads it. |
includeImageUrls | boolean | no | true additionally returns a short-lived signed url per attachment so the images can be viewed. Off by default. |
includeImages | boolean | no | true additionally returns the body's pictures themselves as image content blocks (up to ten, in body order, each under a line naming it) so they can be looked at — the way to read a screenshot or a receipt pasted into the body. Off by default. |
includeFiles | boolean | no | true additionally returns the words of the files in the body — the [name](roma://attachment/…) lines: a PDF's text, a scanned PDF transcribed, a text file as it is — as text blocks after the item (up to five files and 30,000 characters, in body order, each under a line naming it). The way to read a lease or a schedule attached to the item. Off by default. |
Returns
id(string)identifier(string | null): The item's fixed ID — its list's prefix and a number, TASK-1601 — which every item tool takes as its id too.title(string | null)body(string | null): The body as Markdown; with a short handle in front of every block on a read made for editing.bodyVersion(string): A fingerprint of the body as read; a whole-bodyrewritenames it asbaseVersion.taskStatus(string | null): On a list that keeps a status.dueAt(string | null): On a list that keeps a due date: the instant stored; a day when hasDueTime is false.hasDueTime(boolean | null): Whether dueAt's time of day is meant; false for a day.reminderAt(string | null): When the reminder rings, as an instant; null for none.completedAt(string | null)values(object): The item's values keyed by property id; a select value is an option id.cells(object of string): The item's values by property NAME, as text, where its list has properties of its own.isSharedWithMe(boolean): Shared with the person by its owner;editablesays what update_items admits on it.editable("all" | "titleAndBody"): On a row shared with the person:all— every field but the owner's own reminder, repeat and favorite, whether the item was shared with them one by one or through a list; update_items refuses the owner's own fields by name.listId(string | null)listName(string | null)listIcon(string | null): The list's own icon, an emoji, when it has one.expertId(string | null): The id of the item's standing expert (one of the user's experts, list_experts), when the user's own item carries one: that expert answers by default in the item's chat in Roma. Absent on a row shared with the user.summary(string | object)summarySeq(number | null): The number of the log line the summary rests on, so a reader of the item in Roma can tell a summary that lags its log from one that is current.synthesizedAt(string | null): When Roma last wrote the summary.createdAt(string | null)updatedAt(string | null)editedAt(string | null)archivedAt(string | null)recordingStatus(string)attachments(object[])bodyImages(object[]): The pictures the body shows (), whether or not they are attachments, with the size each was stored at (null when unknown) and its alt text; with includeImageUrls, a short-lived signed url on each; with includeImages on get_item, the pictures themselves as image content blocks.guidance(string): How to work this item right now: its status, what the person wrote in its chat since an agent last posted, where the work goes.expert(object | null): The item's standing expert, when the user's own item carries one: that expert answers by default in the item's chat in Roma, and get_expert reads its instructions. Null on a row shared with the user.list(object): Present when the item's list carries standing instructions: they apply to every item on it, this one included.label(string): For an item with no title: its first non-empty value, else its list's name.properties(object[]): The list's own properties, so a value can be written back by id.webUrl(string): The item's page in Roma, to open in a browser.appUrl(string): The item in the Roma Mac app: the app's own link scheme (yamo://artifacts/:id; yamo-staging:// against staging).transcript(string)recording(object)taskCandidates(object[])
Example
{
"method": "tools/call",
"params": {
"name": "get_item",
"arguments": {
"itemId": "<itemId>"
}
}
}
query_items
Query items · Read-only
Filter, sort, count or sum the items of ONE list by its properties — exact numbers instead of eyeballing a dump: "how many are unread", "expenses in March", "the wines rated 5". where clauses AND-combine on a property by id or name (on a list that keeps them, status and dueDate are properties too); a select value may be its label. mode 'list' (default) returns the matching items, paged with offset and limit; 'count' how many match; 'sum' the total of sumPropertyId across the matches. Archived items are left out unless includeArchived: true; each item reports its archivedAt.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | yes | The list to query: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). |
where | object[] | null | no | Filter clauses, AND-combined. Omit for every item. |
sort | object | null | no | Sort order. Omit for the list's default (newest first). |
mode | "list" | "count" | "sum" | null | no | 'list' (default) returns matching items; 'count' how many match; 'sum' totals sumPropertyId across matches. |
sumPropertyId | string | null | no | For mode 'sum': the numeric property to total (its stable id or name). |
createdAfter | string | null | no | ISO 8601 instant — items added on/after this. |
createdBefore | string | null | no | ISO 8601 instant — items added before this (exclusive). |
updatedAfter | string | null | no | ISO 8601 instant — items last edited on/after this. A read that repeats on a schedule passes the instant of its previous read here, or uses list_items' changedSince, which also carries deletions. |
updatedBefore | string | null | no | ISO 8601 instant — items last edited before this (exclusive). |
includeArchived | boolean | null | no | true also includes archived items (hidden from every list by default), so one can be brought back with update_items. |
limit | integer | null | no | mode 'list': max items per page (default 50). |
offset | integer | null | no | mode 'list': items to skip — page through a big list with offset + limit until hasMore is false. |
includeImageUrls | boolean | null | no | mode 'list': true additionally returns a short-lived signed url per attachment. |
Returns
mode("list" | "count" | "sum")listId(string)listName(string)listIcon(string | null): The list's own icon, an emoji, when it has one.count(number): How many items match.sum(number)sumPropertyId(string)properties(object[])items(object[])offset(number)hasMore(boolean)
Example
{
"method": "tools/call",
"params": {
"name": "query_items",
"arguments": {
"listId": "<listId>"
}
}
}
create_items
Create items · Adds data · Reaches outside Roma
Create items on one list, many in one call (1 to 100): a to-do or a dictated list of them on the Tasks list, a note on the Notes list, rows of a reading list or a CRM. Each entry carries a title, a body as Markdown, and values for the list's own properties as {propertyId, value} pairs (ids or names from list_lists; a select value may be its label or option id, a multiSelect value an array of them; an unknown label becomes a new option; a person value — who the item is for, Assigned to or any person column — is a member's name or id from the list's people in list_lists; an agent's name written there is taken as the item's delegate, the same as delegate, never as an assignee; a name nobody on the list answers to is refused, never added). An entry's delegate names the one agent whose turn the item is: "Operator" (Roma's own first turn), or one of the user's own agents by name or id from the list's delegates, which hands it the item and wakes it; "none" makes the item with no delegate; omitted, the list's own rule decides (Operator by default; a shared list has no default delegate). An item you make for the person gets no delegate unless you pass one. On a list that keeps a status and a due date an entry may set taskStatus, dueAt (a day, or a local time when one was stated, which also arms a reminder at that moment) and reminderAt (a reminder on a day, at the person's default reminder hour). The items are stored as written and indexed for search; no AI pass runs unless enrich is true, which on a tasks list derives the title and due date from the words. An entry's externalId (the caller's own id) makes re-sending safe: the same externalId returns the item already made, under existing. With matchOn, an entry whose named values match an existing item fills that item's empty values, body and images and overwrites nothing (changing a filled value is update_items' job); without it every entry is inserted. Images come as imageUrls (a Roma storage path from create_image_upload, or a public https image URL the server downloads); failures come back in imageFailures. One bad entry never fails the batch; it is reported under failed with its reason.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | no | The list every item lands on: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). Omit for the Tasks list. |
items | object[] | yes | Every item to create, in one call. (up to 100 items) |
agentName | string | null | no | Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
matchOn | string[] | null | no | Property ids or names that identify an existing item. When given, an entry whose listed values all match an existing item is not added again: the existing item gains the entry's values for its empty cells, its body if it had none, and its images, and keeps every cell it already had; matching is exact. Omit to always insert — no property is a natural key, so there is no default dedup. |
enrich | boolean | null | no | Run Roma's background AI pass on each item of a tasks list (title cleanup, due date and list suggestions). Default false: the items are stored as written. |
Returns
listId(string)listName(string)listIcon(string | null): The list's own icon, an emoji, when it has one.properties(object[]): The list's own properties, when it has some.items(object[])added(number): Items inserted by this call.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.mergedIds(string[]): Existing items an entry was merged into through matchOn.existing(object[])failed(object[])unknownKeys(string[])imagesAttached(number)imageFailures(object[])job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
{
"method": "tools/call",
"params": {
"name": "create_items",
"arguments": {
"items": [
{}
]
}
}
}
update_items
Update items · Updates or removes existing data · Safe to retry · Reaches outside Roma
Update items, many in one call, each with its own title, body edits and values; the status, due date, archive and favorite flags apply to every item in the call. Only the fields passed change; null leaves a field as it is. The body is edited with edits against the handles get_item returns in body — replace, insert, delete, setChecked, move, replaceText, or rewrite pinned to bodyVersion — applied in order, all or nothing; a refused call writes nothing on that item and returns the current body with fresh handles. The older way, body with the call's merge mode (append by default, prepend, insertAfter with anchor, replace with confirmReplace: true), still works; an item uses one or the other. The body is the result of the work: edit it as your work lands — the findings, the draft, the numbers, a ticked step — no permission needed; every body write is logged with what it did and can be put back by the person. Every item whose body you change takes message — the brief message for the person, at most 420 characters, what changed and what you need — and may take agentDetail, the part for agents: only what the edit itself does not say — the why, what you considered and rejected, the sources, the doubts — never the text you wrote (the log holds it) and never the message again, up to 20000 characters; a detail that mostly repeats the edit or the message is dropped and the item's warning says so. A body change without message is refused whole (messageRequired) and writes nothing. The message is posted in the item's thread under your name, carries the edit, and the edit's log line carries the message. A change to the title, the status, a date or a value needs no message. Roma's summary of the item — its own panel above the body — is Roma's, read and never written. values MERGE into the item (only the properties sent change; "" clears one; an unknown property is an error naming the valid ones). Assigning is a person value: "assign these to Mara" is each item's values carrying the list's person property — Assigned to, assignedTo, where the list has it — with her name or id from the list's people in list_lists, many items in one call; a name nobody on the list answers to is refused with the names that are, and "" unassigns; an agent's name written into a person cell is taken as the item's delegate, the same as delegate, never as an assignee. Delegating is the item's delegate: "hand these to ChatGPT" is each item's delegate carrying one of the user's own agents by name or id from the list's delegates in list_lists, which hands it the item and wakes it (a new delegate cancels the previous one's hand-off); "Operator" hands it to Roma's own operator; "none" removes the delegate. An agent's hand-off to another agent is an entry that carries delegate and nothing else that changes the item (a message is fine). A delegate naming the agent already in the Delegate cell beside another change is no hand-off: the other fields are written and nobody is woken. While the agent the item was last handed to still has it (it is working, waiting for the person, or waiting for its computer), naming it again changes nothing and the item's answer says who has it (notHandedOver, code handoffAlreadyHeld). Once that agent returned the item, handing it the item again is a new round and wakes it again; that holds for the agent already in the Delegate cell too, so never clear the delegate first to hand an item again (that is refused with handoffAlreadyHeld). The same holds once it worked on the item and then went quiet. An agent that never started on the item, or whose run failed, cannot be handed it again by an agent (handoffAlreadyHeld): only the person can. Three hand-offs by agents to the same agent on one item, and ten by agents in all, are refused with handoffLimitReached. A refused hand-off writes nothing. Only the person lifts a limit, in Roma: tell them to open the item in Roma and set Delegate to that agent themselves (an agent already in the cell is picked there again); their yes in your chat does not count. following (on an item, or on the call for every item) follows or mutes the item's edits and chat for the user alone. imageUrls add images (clearImages: true drops the old ones first). taskStatus, dueAt, reminderAt and muteReminder apply only on a list that keeps them: a due date is a day, or a local time when one was stated, which also arms a reminder at that moment; reminderAt arms a reminder on a day without touching the date; muteReminder turns it off; dueAt "none" clears the due date and its reminder. Items are written in order; a refusal stops the batch and names the items already written, so re-send only the rest. Returns each item, with body, bodyVersion and applied after a body write. An agent that holds a task (its record in the Delegate cell) gives it back with handoff: "returned" on the item, on the same call that writes its last result, with the message that call carries; the agent stays in the cell, the task reads Done, and the answer's returnedTo names who has it now. An agent never clears itself from the cell.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
items | object[] | yes | Every item to update, in one call. (up to 200 items) |
agentName | string | null | no | For an agent record: which of the agents on this sign-in or key is writing, when it carries several (ChatGPT and a Dot share one sign-in; several records on one key): pass your own record's name on every call. A sign-in or key with one record writes as that record whatever this says. Otherwise how a key-bound caller with no record is named on the message a body change posts (default "Your agent"). |
mode | "prepend" | "append" | "replace" | "insertAfter" | null | no | Legacy: how each item's body merges: 'append' (default, at the bottom), 'prepend' (at the top), 'insertAfter' (right after the line named in anchor), or 'replace' (swap the whole body — only when the user explicitly asked to rewrite it; requires confirmReplace: true). |
anchor | string | null | no | For mode 'insertAfter' only: a verbatim snippet of the existing line to insert after. Errors if not found. |
confirmReplace | boolean | null | no | Required (true) for mode 'replace': confirms the user explicitly asked to swap the WHOLE body, deleting everything in it. Never pass it on the user's behalf without that explicit ask. |
taskStatus | string | null | no | On a list that keeps a status: a status id of the list's Status property (todo, inProgress, completed on every list that keeps one; backlog, inReview, canceled and the list's own ids where list_lists shows them). A done-stage status completes the item. Applies to every item in the call. Status transitions report progress. |
dueAt | string | null | no | On a list that keeps a due date, for every item in the call: YYYY-MM-DD for a day the person named with no time (the usual case; nothing rings); YYYY-MM-DDTHH:MM in their local time when they stated a time, which also arms a push reminder at that moment. An instant with a zone (2026-10-28T09:00:00Z) is read as the day it falls on in their zone unless hasDueTime is true. A reminder already armed follows a moved day. "none" removes the due date with its time and reminder. |
hasDueTime | boolean | null | no | With a dueAt that carries a zone: true when its time of day is meant (the due is that moment and the reminder is armed), false to keep the day alone. Not needed for the two plain shapes. |
reminderAt | string | null | no | Arms a reminder without changing the visible due date, for every item in the call: YYYY-MM-DD (that day at the person's default reminder hour) or YYYY-MM-DDTHH:MM in their local time. An undated item is dated that day. A moment already passed arms nothing. Not beside dueAt "none" or muteReminder. |
muteReminder | boolean | null | no | true turns the reminder off and leaves the due date and its time as they are, for every item in the call. Not beside reminderAt. |
archived | boolean | null | no | true sets the item(s) aside (hidden from every list, kept and reversible); false brings them back. |
favorited | boolean | null | no | true pins the item(s) in the app's Favorites; false unpins them. |
following | object | null | no | The user's own following of every item's edits and chat in the call: each half "follow" or "mute". An item's own following wins for that item. Omit to leave it. |
Returns
updated(number)items(object[])imagesAttached(number)imageFailures(object[])links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
{
"method": "tools/call",
"params": {
"name": "update_items",
"arguments": {
"items": [
{
"itemId": "<itemId>"
}
]
}
}
}
move_items
Move items · Updates or removes existing data · Safe to retry
Move items onto another list: a task out to the Tasks list ("tasks"), a note onto the Notes list ("notes"), anything onto a list by id. Each item keeps its id, body, chat and history; its values follow their properties by id, then by name and type, select values by label. A value the destination list has no place for would be DROPPED: a first call that would drop values answers a preview (preview: true, droppedValues) and moves nothing; the same call with acknowledgeDataLoss: true then moves. The status and due date ride along unseen onto a list that keeps neither and show again on the way back. An item inside a list shared with the user moves as far as the app lets them: out onto one of their own lists (it becomes theirs, and everyone in the shared list loses it), or into another shared list they are in; such a move changes who can reach the item, so the first call answers a preview (accessChanges, the app's own question) and moves nothing until the repeat with acknowledgeDataLoss: true. An item shared with the user one item at a time stays its owner's to move: it is reported under refused with the reason, never moved.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
itemIds | string[] | yes | Ids of the items to move. (up to 100 items) |
listId | string | yes | The destination list: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). |
acknowledgeDataLoss | boolean | null | no | true ONLY on a repeat call, after a preview reported values the destination list has no place for, or people who will gain or lose access, and you told the user what will happen. |
Returns
preview(boolean)listId(string)listName(string | null)items(object[])droppedValues(object[])accessChanges(object[])refused(string[])refusals(object[])
Example
{
"method": "tools/call",
"params": {
"name": "move_items",
"arguments": {
"itemIds": [
"<itemIds>"
],
"listId": "<listId>"
}
}
}
delete_items
Delete items · Updates or removes existing data · Safe to retry
Delete items by id, up to 50 per call. SOFT delete: every item stays recoverable for ~30 days via restore_deleted (type "item") before it is purged, and drops out of search. Returns the deleted items. An item inside a list shared with the user deletes as the app lets them, under its owner with the user named; ids the user may not delete — not theirs, or shared with them one item at a time — are reported under refused with the reason, and the rest still delete.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
itemIds | string[] | yes | The items' ids. Up to 50 per call. (up to 50 items) |
Returns
deleted(number)items(object[])refused(string[])refusals(object[])job(object): Present when the batch was past the inline threshold (more than 20 entries or 2 MB in one call): the call was accepted and stored as a job, nothing is written yet, and the entries land in the background a few at a time. Poll get_job withjob.idfor progress; the other fields of the result are empty.
Example
{
"method": "tools/call",
"params": {
"name": "delete_items",
"arguments": {
"itemIds": [
"<itemIds>"
]
}
}
}
get_job
Get job · Read-only
Read the progress of a queued bulk write: a create_items, update_items, delete_items or delete_list call of more than 20 entries (or 2 MB) is accepted and answers a job instead of writing at once; the entries land in the background a few at a time. Returns the job's state (queued, running, done, failed), how many entries landed and how many failed, and each entry's outcome with the item it made or changed, or the reason it failed. Poll every few seconds until status is done or failed; the items appear on the list as they land.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
jobId | string | yes | The job's id, from the job block a bulk write answered with. |
Returns
id(string)tool(string)status("queued" | "running" | "done" | "failed")total(number)done(number): Entries that landed (an entry matched to an existing item counts here).failed(number)listId(string | null)error(string | null): Why the whole job stopped, when it failed.createdAt(string)startedAt(string | null)finishedAt(string | null)entries(object[]): The entries that have run so far, in order, up to the first 500.links(object): The roots of a row's links:<webOrigin>/artifacts/<id>is the item's page in Roma,<appScheme>://artifacts/<id>the same item in the Roma Mac app.
Example
{
"method": "tools/call",
"params": {
"name": "get_job",
"arguments": {
"jobId": "<jobId>"
}
}
}
create_image_upload
Create image upload · Adds data
Get pre-signed URLs to upload images DIRECTLY into Roma storage — the reliable alternative to passing third-party links in imageUrls (those must stay fetchable until the server downloads them; short-lived signed links often expire first). For each slot: HTTP PUT the raw image bytes to uploadUrl with the matching Content-Type header (valid ~2 hours), then pass its bucketPath as an imageUrls entry in create_items / update_items. Keep images at or under 10 MB (maxBytes). Up to 10 slots per call.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
mimeType | "image/png" | "image/jpeg" | "image/heic" | "image/webp" | yes | The image type you will upload (all slots in one call share it). |
count | integer | no | How many upload slots (default 1). (1 to 10) |
Returns
uploads(object[])maxBytes(number)validForSeconds(number)
Example
{
"method": "tools/call",
"params": {
"name": "create_image_upload",
"arguments": {
"mimeType": "image/png"
}
}
}
list_versions
List versions · Read-only
List the version history of one item or expert, newest first: one entry per write, each with who made it (user, ai or system, and the name it was signed with when there is one) and the cause (an edit in the app, an edit over this connection, a restore, Roma's own passes). Each entry is the body as it was BEFORE that write, so the entry naming an edit is the state that undoes it; restore_version puts one back. Use it to undo an edit, or to see how a body or an expert's instructions changed over time. Versions are kept for the item's life; a long history pages by before.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The item's or the expert's id (from list_items, search, get_item or list_experts). |
limit | integer | null | no | Entries per page, newest first (default 50, at most 200). |
before | string | null | no | Only the entries from before this instant (ISO 8601): the createdAt of the last entry seen, for the page before it. |
Returns
id(string)hint(string)versions(object[])
Example
{
"method": "tools/call",
"params": {
"name": "list_versions",
"arguments": {
"id": "<id>"
}
}
}
get_version
Get version · Read-only
Read one version of an item's or expert's body from list_versions or from a body line of read_log (its versionId): the body as it was at that snapshot, as Markdown, with its cells, and the line changes from it to the next state — diffAgainst "current" (the default) for the body as it is now, or another version id (the next body line's versionId in the log) for the edit that one line made. The diff is hunks of removed, added and context lines, so a long body that changed in three places answers those three places; a line that is a picture or a file carries media beside its Markdown, and a hunk whose words did not change is kind: "formatting"; includeBody: false answers the diff alone.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The item's or the expert's id. |
versionId | string | yes | The version to read, from list_versions or a log line's versionId. |
diffAgainst | string | null | no | "current" (default) or another version id of the same item: what the snapshot is compared with. |
includeBody | boolean | null | no | false leaves the body out and answers the entry and the diff alone (default true). |
Returns
id(string)version(object)markdown(string)values(object | null)diff(object)
Example
{
"method": "tools/call",
"params": {
"name": "get_version",
"arguments": {
"id": "<id>",
"versionId": "<versionId>"
}
}
}
get_blame
Get blame · Read-only
Who wrote each line of an item's body as it stands now: the body as numbered lines and runs of lines, each run with its writer (a person, their agent over this connection, the operator, an expert, an automation), the time, and the versionId of the snapshot that write replaced — the body line read_log names and get_version reads as a diff. A line belongs to the newest write that introduced or last changed its text; a line that only moved keeps its writer; a blank line joins the run above it. Lines older than the first snapshot are the item's creator's. The walk reads up to 500 snapshots back and says when it was cut (truncated, those runs with no writer). fromLine and toLine (1-based, inclusive) answer a window of the body.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The item's id (from list_items, search or get_item). |
fromLine | integer | null | no | The first line of the window (default 1). |
toLine | integer | null | no | The last line of the window (default the body's last line). |
Returns
id(string)bodyVersion(string): The stamp of the body the runs describe; update_items' rewrite takes it as baseVersion.lines(string[])ranges(object[])versionsWalked(number)truncated(boolean)
Example
{
"method": "tools/call",
"params": {
"name": "get_blame",
"arguments": {
"id": "<id>"
}
}
}
restore_version
Restore version · Updates or removes existing data · Safe to retry
Restore one item's or expert's body to an earlier version from list_versions (its cells too, where the snapshot kept them). The current body is snapshotted first, so a restore is itself undoable. When the person, or a collaborator, edited the body in Roma after that version, the call answers needsConfirmation and names those later edits instead of restoring; the same call with acceptLaterEdits: true, after the person agreed to lose them, restores. Writes made over this connection never ask: undoing them is what the tool is for.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | The item's or the expert's id. |
versionId | string | yes | The version to restore, from list_versions. |
acceptLaterEdits | boolean | null | no | true only after the person said yes to losing the edits made in Roma after that version, the ones the needsConfirmation answer named. Omit on the first call. |
Returns
restored(boolean)id(string)title(string | null)needsConfirmation(boolean)laterEdits(object[])hint(string)
Example
{
"method": "tools/call",
"params": {
"name": "restore_version",
"arguments": {
"id": "<id>",
"versionId": "<versionId>"
}
}
}
Search
Finds items and lists by meaning or keyword, with the best-matching passage per item; and greps one list's bodies by pattern, each hit with the block handle an edit targets.
search
Search items and lists · Read-only
Search the user's Roma workspace — their items (tasks, notes, the rows of every list they keep) and their lists, and what others shared with them (an item shared on its own, a list they joined and every item on it, each marked isSharedWithMe) — by meaning or keyword (hybrid semantic + keyword retrieval). Use this when the user asks about their own information, plans or anything they may have saved, and before adding something that may already exist. Their wording often won't match their notes' wording; the semantic arm bridges that gap (and across languages). Returns the best-matching passage per item, each with its list; get_item returns an item in full. An empty result means nothing relevant is saved. Not for general web knowledge.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | Natural-language query — what the user is trying to find, in their words. |
limit | integer | no | Max results (default 10). (1 to 20) |
after | string | no | Only items CREATED on/after this ISO 8601 timestamp. Use when scoping by when it was saved ("last week", "in March"). |
before | string | no | Only items CREATED before this ISO 8601 timestamp (exclusive). Pair with after to bound a window. |
Returns
count(number)results(object[])
Example
{
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "<query>"
}
}
}
grep_items
Grep a list's bodies · Read-only
Find the lines of one list's item bodies that match a pattern — a literal by default, a regular expression with regex: true — the way grep does, when the words are known: a function or flag name, a heading, an exact phrase. search finds by meaning and answers a passage; this answers every matching line with the block handle it sits in, the handle update_items' edits take, and a line of context each side, newest item first. The person's own list, or one shared with them. Case-folded unless caseSensitive; a regular expression is the database's grammar (POSIX), tested line by line.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | string | yes | The list to grep: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list). |
pattern | string | yes | What to find: a literal, or a regular expression with regex: true. (up to 200 characters) |
regex | boolean | null | no | true reads the pattern as a regular expression (default false: a literal). |
caseSensitive | boolean | null | no | true matches case exactly (default false). |
context | integer | null | no | Lines of context on each side of a hit (default 1, at most 3). |
limit | integer | null | no | Items answered at most (default 20); hasMore says when the list holds more matching items. |
matchesPerItem | integer | null | no | Lines answered per item at most (default 5); moreMatches says when the body holds more. |
Returns
listId(string)listName(string)count(number): Items answered.hasMore(boolean)items(object[])
Example
{
"method": "tools/call",
"params": {
"name": "grep_items",
"arguments": {
"listId": "<listId>",
"pattern": "<pattern>"
}
}
}
Chats
The chat on an item, as the room an agent shares with the person: read what was said, post a message under the agent's name — the brief part for the person and, when there is more to say than the edit itself, the part for agents under it — and read the item's log, Roma's own record of every change, which no agent writes.
read_chat_messages
Read chat messages · Read-only
Read the recent messages in an item's chat: what the user said there, what Roma replied, and what any agent posted with post_chat_message. On a shared item (shared on its own or through its list) the chat is its Thread, the one conversation the owner and every member see, so you read what the members said too. Pass since to read only what arrived after a moment you already saw; a read that repeats on a schedule passes the createdAt of the last message it saw every time. Empty when the item has no chat yet. A message from an agent may carry agentDetail, the part meant for agents — what the edit itself does not say: the why, what was considered and rejected, the sources, the doubts — and edit, the body edit it accompanies (the log line, its seq and the snapshot); a person's message carries neither, and Roma's own replies carry no agentDetail. The edit's text itself is the log's: read_log. A conversation bound to no item (the person's main chat, a list's chat) is read by conversationId, the id a mention's delivery carried.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
artifactId | string | no | The item's id, or a Roma link to it (roma.app/artifacts/<id>). One of artifactId / conversationId. |
conversationId | string | no | The conversation's id, for a chat bound to no item (the main chat, a list's chat): the conversation.id a mention's delivery carried. One of artifactId / conversationId. |
since | string | no | ISO 8601 instant. Only messages created after it are returned, oldest first: the createdAt of the last message you saw. |
limit | integer | no | Max messages (default 20). (1 to 50) |
Returns
sessionId(string | null)messages(object[])truncated(boolean)
Example
{
"method": "tools/call",
"params": {
"name": "read_chat_messages",
"arguments": {}
}
}
post_chat_message
Post chat message · Updates or removes existing data · Safe to retry
Post a message into an item's thread as the calling agent: a post for an action taken outside Roma with its link, or the one question the work is blocked on (a body change's message is the post for the work itself), at most 420 characters, saying what changed and what is needed from the person. A second post before the person has replied, the status has changed or 30 minutes have passed is refused. agentDetail, the part for agents behind the message, is for what the message does not say — the why, what was considered and rejected, the sources, the doubts — never the message again (a detail that mostly repeats it is dropped and warning says so). A body change posts its own message through update_items (message on the item), never here. On a shared item (shared on its own or through its list) the post lands in its Thread, where the owner and every member read it. The user sees it on every device as an unread reply on the item and as an Updates row under your name, and the agent cannot take it back, so a post per step reads as noise; a post the item's own body asks you for is the person's ask and is wanted. Set needsInput when the work is blocked on their answer. The same messageKey posted twice lands once. The person is offered Reply on your post only when you will read it: a live trigger wakes you by this agentName (manage_triggers, action create, with agentName), or you pass readsReplies: true because you read this chat again on your next run (read_chat_messages with since). Otherwise the post is a notification they cannot answer, so do not ask a question in it. The answer's listening says whether a reply would wake you at once. An agent with a record (a connected app, or the record register_agent bound) posts under the record's name whatever agentName says, and the person's Reply wakes it through its own door; only where one sign-in or key carries several agents does agentName say which of them posts. A mention in a chat bound to no item (the person's main chat, a list's chat) is answered there: pass the conversation.id the delivery carried as conversationId instead of an item. mentions addresses members of the item (or of the list a list room belongs to) by name or user id: a mentioned member gets a mention notification even when they muted the chat, so mention only who the message is for; a name nobody on it answers to is refused naming who is. A mention not already written into the message as a [@Name](roma://person/<id>) link is appended to its end so every client shows who was addressed, and the length cap counts the appended chips (tooLong). The operator is never mentioned here: the person addresses the operator in a room, not an agent.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
artifactId | string | no | The item's id, or a Roma link to it (roma.app/artifacts/<id>). One of artifactId / conversationId. |
conversationId | string | no | The conversation's id, for a post into a chat bound to no item (the main chat, a list's chat): the conversation.id a mention's delivery carried. One of artifactId / conversationId. |
mentions | string[] | no | Members to address, by name or user id, at most 10: each gets a mention notification even when they muted the chat. Never "operator". Only who the message is for. (up to 10 items) |
message | string | yes | The message for the person, as Markdown, at most 420 characters including the mention chips appended for mentions; what does not fit goes to agentDetail. The message is plain sentences, as a chat is: Markdown for a link, inline code or a short list, and bold only on a phrase inside a sentence; never a heading and never a whole line in bold: a message this short is one section, and the thread draws either as a title. (up to 420 characters) |
agentDetail | string | no | Optional: the part for agents — only what the message does not say: the why, what you considered and rejected, the sources, the doubts, what is left — any style, up to 20000 characters, read by the next agent behind the message in Roma. Never the message again: a detail that mostly repeats it is dropped and warning says so. (up to 20000 characters) |
agentName | string | no | How a caller with no record is named in the chat (default "Your agent"). For an agent record: which of the agents on this sign-in or key is posting, when it carries several (ChatGPT and a Dot share one sign-in; several records on one key): pass your own record's name on every call. A sign-in or key with one record posts as that record whatever this says. (up to 60 characters) |
needsInput | boolean | no | True when the message is a question the work waits on. |
readsReplies | boolean | no | True when you read this chat again on your next run, so the person may answer here even with no trigger waking you. |
messageKey | string | no | Idempotency key: a retry with the same key updates the same message. (up to 120 characters) |
Returns
id(string)sessionId(string)createdAt(string)listening(boolean): Whether a reply from the person would wake this agent through a trigger. False: the reply waits for the agent's next run.mentioned(object[]): The membersmentionsaddressed, as resolved.warning(string): The message landed and something beside it did not: agentDetail dropped as a copy of the message (detailDropped).
Example
{
"method": "tools/call",
"params": {
"name": "post_chat_message",
"arguments": {
"message": "<message>"
}
}
}
read_log
Read the log · Read-only
Read an item's (or a list's) log, Roma's own record of everything that happened to it: every change with who made it and when — a person, Roma's operator, an expert, an agent, an automation — every body change with what it did and the text it added (change and body) and the snapshot it replaced (versionId), every post in its thread (messageId), the summary's own writes. No agent writes into it; read it to see what changed before you and why, before continuing another agent's work. Pass since (the seq of the last line you saw) to read only what landed after it, oldest first; without it the newest lines, newest first, with nextBeforeSeq for the page before. The body itself is get_item's; the thread's words are read_chat_messages'.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
itemId | string | no | The item's id, its ID (TASK-12) or a Roma link. One of itemId / listId. |
listId | string | no | The list's id, for the list's own log. One of itemId / listId. |
since | integer | no | The seq of the last line you saw: only lines after it, oldest first. (-9007199254740991 to 9007199254740991) |
beforeSeq | integer | no | Paging backwards without since: lines with a seq below this one. (-9007199254740991 to 9007199254740991) |
limit | integer | no | Max lines (default 50). (1 to 200) |
kinds | string[] | no | Only these kinds: created, updated, moved, deleted, undeleted, restored, rewritten, posted, noted, joined, left, handoff, returned, released. |
Returns
entries(object[])nextBeforeSeq(number | null)truncated(boolean)
Example
{
"method": "tools/call",
"params": {
"name": "read_log",
"arguments": {}
}
}
wait_for_item
Wait for item · Read-only
Hold until something new lands on this item, at most 25 seconds; call again to keep waiting. For the agent that handed a task to another agent and waits for the answer in the same conversation. Answers the new log lines (the read_log shape) that were not written by you, the task's agentState at that moment, and nextSince, the seq to pass as since on the next call. until says what ends the wait: "return" (a returned or released line: the other agent gave the task back, or Roma released it: silent for four hours, the chain stopped, a failed run, or the person reassigned it; any released line ends the wait), "post" (a post by someone else), or "any" (default: any new line by someone else). timedOut: true means nothing came in time; call again. One wait per item at a time: a second call while one waits answers at once with busy: true.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
itemId | string | yes | The item's id, its ID (TASK-12) or a Roma link. |
since | integer | no | The seq of the last log line you saw: only lines after it count. Default: the newest seq when the call starts, so only what lands from now on. (-9007199254740991 to 9007199254740991) |
timeoutSeconds | integer | no | How long to hold, 1 to 25 seconds (default 25). (1 to 25) |
until | "any" | "return" | "post" | no | What ends the wait: "any" (default), "return", or "post". |
agentName | string | null | no | Who is calling, when this sign-in carries several agents (several Grok Bots of one account; ChatGPT and a Dot): your own agent's name, or its agentId. Pass it on every call. A sign-in or key with one agent is that agent whatever this says. |
Returns
lines(object[])agentState(any | null): The task's hand-off state at that moment (as get_item answers it), null when no agent holds it.nextSince(number): Pass assinceon the next call.timedOut(boolean)busy(boolean): True when another wait of yours on this item was already running: this call answered at once.
Example
{
"method": "tools/call",
"params": {
"name": "wait_for_item",
"arguments": {
"itemId": "<itemId>"
}
}
}
Sharing
Who a list or item is shared with: invite people by email, turn the public link on or off, remove a member, leave, stop sharing, and read who is on it.
manage_sharing
Manage sharing · Updates or removes existing data · Safe to retry · Reaches outside Roma
Read or change who a list or an item is shared with. members reads who is on it: the members with their level, the pending invitations and the public link. invite sends an email invitation to each address in emails at level — "edit" (Can edit, the default) or "full" (Can edit and invite); there is no viewer level. link turns the public link on or off (linkOn): on, anyone with the link can edit. remove takes a member off (member: a name or user id), leave takes the user off a list or item somebody shared with them, stop ends the sharing for everyone. An invite, and a link turned on, answer a PREVIEW first (preview: true, with wouldInvite or wouldMakeLinkOn) and change nothing until the same call is repeated with confirm: true; the other actions run at once. Who may do what: the owner turns the link, removes a member and stops the sharing; the owner or a member with full access invites; a member leaves. An item held through a shared list is left or removed through the list, not the item. Returns the action, the subject (kind, id, title, isShared) and the action's own fields: members and invitations for a read; results per email (outcome, sent) for an invite; shareUrl and linkOn for the link; removed, left or ended. A subject the user cannot reach, a member nobody answers to, or an action the user's standing does not allow is refused with the reason.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | "members" | "invite" | "link" | "remove" | "leave" | "stop" | yes | What to do. |
listId | string | null | no | The list's id (from list_lists). One of listId / itemId. |
itemId | string | null | no | The item's id, its ID (ROMA-12) or a Roma link to it. One of listId / itemId. |
emails | string[] | null | no | invite: the email addresses to invite. |
level | "full" | "edit" | null | no | invite: the level every invitee gets — "edit" (Can edit, the default) or "full" (Can edit and invite). |
linkOn | boolean | null | no | link: true turns the public link on (anyone with it can edit), false turns it off. |
member | string | null | no | remove: the member to take off, by name or user id. |
confirm | boolean | null | no | true on the repeat of an invite, or of a link turned on, after the preview: the call then sends the emails or turns the link on. |
Returns
action(string)subject(object)preview(boolean): true: nothing changed; repeat the call with confirm: true to do it.wouldInvite(string[]): preview of an invite: the addresses that would be emailed.level(string): preview of an invite: the level they would get.wouldMakeLinkOn(boolean): preview of a link turned on.note(string)members(object[])invitations(object[])results(object[])shareUrl(string | null)linkOn(boolean)removed(boolean)left(boolean)ended(boolean)
Example
{
"method": "tools/call",
"params": {
"name": "manage_sharing",
"arguments": {
"action": "members"
}
}
}
Trash
Every delete is soft. The trash lists what was deleted and restores one item or list per call for about 30 days.
list_deleted
List deleted items and lists (trash) · Read-only
The trash: everything soft-deleted in the last ~30 days — items and lists — newest first, each with the moment it is purged forever (purgesAt). Anything listed here can be brought back with restore_deleted. Filter by type, or omit type for both.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | "item" | "list" | no | Only this kind. Omit for both. |
limit | integer | no | Max entries per kind (default 25). (1 to 100) |
Returns
count(number)items(object[])
Example
{
"method": "tools/call",
"params": {
"name": "list_deleted",
"arguments": {}
}
}
restore_deleted
Restore deleted item or list · Adds data · Safe to retry
Bring back one soft-deleted item or list from the trash (see list_deleted). Restoring a list also brings back the items deleted with it; an item whose list is still in the trash can't come back alone (restore the list first). An item whose list is gone for good lands on the hub's default list for what it was (movedToDefaultList: true). Restores one thing per call. If it is already live the call succeeds with alreadyLive: true.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | "item" | "list" | yes | The entry's type, as list_deleted reported it. |
id | string | yes | The deleted item's or list's id. |
Returns
restored(boolean)alreadyLive(boolean)type(string)id(string)title(string | null)restoredItems(number)movedToDefaultList(boolean)
Example
{
"method": "tools/call",
"params": {
"name": "restore_deleted",
"arguments": {
"type": "item",
"id": "<id>"
}
}
}
Automations
Standing orders Roma runs on a schedule. Read them, read one in full with its steps, read what their runs found, and start one when the user asks.
list_automations
List automations · Read-only
List the user's automations — standing orders Roma runs on its own, on a schedule or on demand. Returns each one's id, name, what it does, status (active / paused / draft), when it runs, the next run, and how the last run ended. Use it when the user asks what runs on its own, when something runs next, or before reading or starting a run.
Parameters
This tool takes no parameters.
Returns
count(number)automations(object[])
Example
{
"method": "tools/call",
"params": {
"name": "list_automations",
"arguments": {}
}
}
get_automation
Get automation · Read-only
Read one of the signed-in user's own automations: its name, what it does, when it runs, its status, the next run, its steps as the user wrote them, and how the last run ended. A read only: it starts nothing and changes nothing; run_automation starts one, list_automations lists them all, get_automation_runs reads the runs.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
automationId | string | yes | The automation's id (from list_automations or get_context). |
Returns
id(string)name(string)status(string)when(string)nextRunAt(string | null)steps(string): The steps as written, Markdown; empty when there are none.webUrl(string)
Example
{
"method": "tools/call",
"params": {
"name": "get_automation",
"arguments": {
"automationId": "<automationId>"
}
}
}
get_automation_runs
Get automation runs · Read-only
Read one automation's recent runs, newest first: when each ran, how it ended, what it wrote (one line per action), the message it left for the user, and any error. Use it for "what did my morning brief find", "why did it fail", or to read the result of a run started with run_automation once it has finished.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
automationId | string | yes | The automation's id (from list_automations or get_context). |
limit | integer | no | How many runs, newest first (default 5, max 20). (1 to 20) |
Returns
automation(object)runs(object[])
Example
{
"method": "tools/call",
"params": {
"name": "get_automation_runs",
"arguments": {
"automationId": "<automationId>"
}
}
}
run_automation
Run automation now · Updates or removes existing data · Reaches outside Roma
Start one of the user's automations now — the same as Run now on its page in Roma. Use it only when the user asks to run a specific automation. The run happens inside Roma with the user's connected apps and can take a minute; its result lands in the user's Roma chat, not in this conversation. Read the outcome afterwards with get_automation_runs. Refused for a draft, while the same automation is already running, or once the daily run limit is reached.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
automationId | string | yes | The automation's id (from list_automations or get_context). |
Returns
id(string)name(string)runId(string)status(string)
Example
{
"method": "tools/call",
"params": {
"name": "run_automation",
"arguments": {
"automationId": "<automationId>"
}
}
}
Experts
The user's experts: each a named body of standing instructions they wrote in Roma for a kind of work (an editor, a reviewer, a coach), private to them. List them, read one's instructions to work under them, create one, update one; an item can carry one as its standing expert.
list_experts
List experts · Read-only
List the user's experts: each a named body of standing instructions they wrote in Roma for a kind of work (an editor, a reviewer, a coach), private to them. Returns every expert's id, name and the opening line of its instructions. Use it when the user asks which experts they have, names one, or asks for work done the way one of their experts does it; get_expert reads one in full.
Parameters
This tool takes no parameters.
Returns
count(number)experts(object[])
Example
{
"method": "tools/call",
"params": {
"name": "list_experts",
"arguments": {}
}
}
get_expert
Get expert · Read-only
Read one of the user's experts in full: its name and its standing instructions as Markdown, the way the user wrote them in Roma. Use it when the user names an expert for the work at hand ("use my Content Editor on this"), asks what one of them covers, or before updating one. By id (from list_experts or get_context) or by its exact name; a name that is none of theirs is not found.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
expertId | string | null | no | The expert's id. Pass this or name. |
name | string | null | no | The expert's name, exactly as list_experts shows it (case does not matter). |
Returns
id(string)name(string)firstLine(string): The opening line of its instructions.icon(string | null): The icon it wears in Roma — a name of the expert icon set, or null for the default.updatedAt(string)webUrl(string): The expert's page in Roma on the web.instructions(string): The whole standing instructions, as Markdown.
Example
{
"method": "tools/call",
"params": {
"name": "get_expert",
"arguments": {}
}
}
create_expert
Create expert · Adds data
Create an expert for the user: a name and its whole standing instructions as Markdown (second person, present tense, what to do; the shape the user's other experts have). Use it on the user's explicit ask to create one, never because they described how they want one answer written. A name the user already has is refused. The new expert shows in Settings → Experts in Roma, where it answers in the user's chats when mentioned by name.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | The expert's name, how the user will call it in (two or three words, the way a job title reads). (up to 120 characters) |
instructions | string | yes | The whole standing instructions, as Markdown. |
icon | "experts" | "writing" | "editing" | "review" | "ideas" | "creative" | "humor" | "language" | "book" | "business" | "goal" | "guidance" | "launch" | "winning" | "teaching" | "planning" | "productivity" | "pitch" | "marketing" | "people" | "support" | "like" | "email" | "voice" | "money" | "banking" | "accounting" | "investing" | "data" | "legal" | "pricing" | "shopping" | "code" | "databases" | "computing" | "science" | "research" | "vision" | "design" | "art" | "fixing" | "architecture" | "product" | "security" | "health" | "care" | "love" | "household" | "city" | "school" | "travel" | "maps" | "world" | "cars" | "music" | "photo" | "film" | "gaming" | "events" | "gift" | "crafts" | "sea" | "sunshine" | "night" | null | no | The icon it wears in Roma, from the set. Omit, or pass null, for the default. |
Returns
id(string)name(string)firstLine(string): The opening line of its instructions.icon(string | null): The icon it wears in Roma — a name of the expert icon set, or null for the default.updatedAt(string)webUrl(string): The expert's page in Roma on the web.
Example
{
"method": "tools/call",
"params": {
"name": "create_expert",
"arguments": {
"name": "<name>",
"instructions": "<instructions>"
}
}
}
update_expert
Update expert · Updates or removes existing data · Safe to retry
Update one of the user's experts: its name, its instructions, its icon, or any of them. instructions replaces the WHOLE body: read it with get_expert first and send the whole text with the change in it, a line that contradicts an existing one replacing that line rather than sitting beside it. A rename to a name the user already has is refused. The previous body stays in the expert's version history (list_versions, restore_version). Use it when the user says an expert missed something, should work differently, should be called something else, or should wear another icon.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
expertId | string | yes | The expert's id (from list_experts, get_expert or get_context). |
name | string | null | no | A new name. Omit, or pass null, to keep it. |
instructions | string | null | no | The whole standing instructions, as Markdown, replacing the body. Omit, or pass null, to keep it. |
icon | "experts" | "writing" | "editing" | "review" | "ideas" | "creative" | "humor" | "language" | "book" | "business" | "goal" | "guidance" | "launch" | "winning" | "teaching" | "planning" | "productivity" | "pitch" | "marketing" | "people" | "support" | "like" | "email" | "voice" | "money" | "banking" | "accounting" | "investing" | "data" | "legal" | "pricing" | "shopping" | "code" | "databases" | "computing" | "science" | "research" | "vision" | "design" | "art" | "fixing" | "architecture" | "product" | "security" | "health" | "care" | "love" | "household" | "city" | "school" | "travel" | "maps" | "world" | "cars" | "music" | "photo" | "film" | "gaming" | "events" | "gift" | "crafts" | "sea" | "sunshine" | "night" | null | no | A new icon from the set; experts is the default. Omit, or pass null, to keep it. |
baseUpdatedAt | string | null | no | The updatedAt get_expert returned; when the expert changed since, the write is refused and the body is read again. |
Returns
id(string)name(string)firstLine(string): The opening line of its instructions.icon(string | null): The icon it wears in Roma — a name of the expert icon set, or null for the default.updatedAt(string)webUrl(string): The expert's page in Roma on the web.changed(string[]): Which ofname,instructionsandiconchanged.
Example
{
"method": "tools/call",
"params": {
"name": "update_expert",
"arguments": {
"expertId": "<expertId>"
}
}
}
Triggers
Roma delivers an event to the agent the moment something changes, instead of the agent polling on a clock: a trigger names which events fire it (an item added or changed, a status, a move, a reply to the agent in a task chat, a run finished), a filter, and where the event goes: a signed webhook, or a poll an agent with no address reads. One tool, four actions.
manage_triggers
Manage triggers · Updates or removes existing data · Reaches outside Roma
The signed-in user's own triggers, in one tool: action list, create, update or delete. A trigger says which Roma events (an item created, changed or delegated, a reply posted, a list changed) are delivered to the user's own agent, and how: transport webhook POSTs each delivery to the https address the user's agent names in url, signed with the trigger's secret (Standard Webhooks); transport poll has no address, the agent reads its deliveries from Roma's deliveries route with its own key. Each delivery carries the item as get_item returns it, what changed, and who changed it. A failing address is retried three times over a day, then the trigger pauses; update resumes it or gives it a new address. agentName ties the trigger to the agent that calls, so the user's replies to its posts are delivered too. A trigger you make for an agent is made for your own agent: naming another agent, by agentId or by agentName, is refused, and one agent has one trigger (a second create is refused with the triggerId to update). The transport never changes on update; delete and create again. Twenty per account. A trigger that belongs to another of the user's agents is theirs alone: you can list it, and only that agent or the user changes or deletes it. Delete removes the trigger and its delivery history, and the chat confirms first. list answers the triggers, each one's last delivery, and the catalogue of events: item.created (an item was created on one of the person's lists: a task, a note, a row); item.updated (an item's title, due date, reminder, a property value or its archived flag changed); item.statusUpdated (a task's status changed (todo, inprogress, completed)); item.moved (an item moved onto another list); item.deleted (an item was deleted into the trash (recoverable for 30 days)); item.restored (an item came back from the trash); list.created (a list was created); list.updated (a list's name, icon, instructions, properties or archived flag changed); list.deleted (a list was deleted into the trash); list.restored (a list came back from the trash); item.delegated (the person delegated an item to an agent: the item's delegate cell gained the agent's record (data); message.posted (the person replied to an agent's post in an item's chat (reply on its row; data); automation.completed (an automation's run finished (`data).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | "list" | "create" | "update" | "delete" | yes | What to do. |
triggerId | string | no | For update and delete: the trigger's id (from list). |
name | string | no | For create (required) or update: what it wakes: "Claude Code on the Mac", "Codex for testing". (up to 80 characters) |
events | "item.created" | "item.updated" | "item.statusUpdated" | "item.moved" | "item.deleted" | "item.restored" | "list.created" | "list.updated" | "list.deleted" | "list.restored" | "item.delegated" | "message.posted" | "automation.completed"[] | no | For create (required) or update: which events fire it. |
filter | object | null | no | For create or update: what narrows an event to this trigger; on update null clears it. |
transport | "webhook" | "poll" | no | For create: webhook (default, needs url) or poll (no address; read with the deliveries route). |
url | string (uri) | no | For a webhook: the https address Roma POSTs to (create), or the new one (update). |
secret | string | no | For a webhook on create: your own whsec_ secret (base64, 32 bytes); minted when absent. (up to 200 characters) |
headers | object of string | no | For a webhook: extra request headers Roma sends on every POST to the user's agent, as the agent's own address requires. Stored, never read back; on update they replace the old ones. |
agentName | string | no | The agent this trigger wakes: yourself, exactly as you name yourself in post_chat_message ("Claude Code"). The trigger is then made for your own agent, and the person's replies to your posts fire it too. Another agent's name is refused. On update, empty clears it. Where several agents share one sign-in (every Grok Bot of one account) it says who is calling: your own name, or your own agentId. You change and delete only your own. (up to 60 characters) |
agentId | string | no | The agent RECORD this trigger wakes: your own. The items delegated to it (item.delegated) and the replies to its posts fire it. Leave it out or pass your own: another agent's id is refused. A trigger on item.delegated or message.posted that names no agent is made for your own agent; when your sign-in carries several agents, say which one. On update, empty clears it. (up to 60 characters) |
paused | boolean | no | For update: true pauses, false resumes. |
Returns
triggers(object[]): For list.events(object[]): For list: the catalogue.trigger(object): For create and update.secret(string | null): For create: the signing secret, this once; null for a poll trigger.deleted(boolean): For delete.
Example
{
"method": "tools/call",
"params": {
"name": "manage_triggers",
"arguments": {
"action": "list"
}
}
}
Agents
The user's agents as records: they add one under Settings → Agents and paste its message into the agent; right after connecting the agent tells Roma who it is (register_agent with its kind from the list, or the id from the message), and from then on the user delegates it items (the item's Delegate cell gains the record) and Roma delivers each delegation and each reply through the agent's own door. Three tools: the roster with whether Roma can reach each agent right now, the claim, and the guide as text (the common part and the kind's section, the same as roma.app/agents.md), for the texts an agent copies for the person.
list_agents
List agents · Read-only
The user's agents — the records under Settings → Agents — and whether Roma can reach each one right now (connected: its door proven and not stale, the record bound, its client not signed out). Only an agent Roma can hand work to (isRemote: a cloud agent, or a local one that is started on the user's computer) that is connected can be a delegate; the names here are the names delegate takes on create_items and update_items and delegateNewItemsTo takes on update_list. Returns each record's id, name, kind, whether Roma can hand it work at all (isRemote), whether it is connected, its state, when Roma last heard from it, when it was last reachable, and reach: how Roma gets a task to it, in the words of its page (started on the user's computer, its own schedule, an address, email, a subscription, or not set up yet).
Parameters
This tool takes no parameters.
Returns
agents(object[])
Example
{
"method": "tools/call",
"params": {
"name": "list_agents",
"arguments": {}
}
}
register_agent
Register agent · Adds data · Safe to retry · Reaches outside Roma
Tell Roma which agent you are, once after connecting: register_agent with your kind from the list, or with the id from the message the person pasted. Roma then files this connection under the person's agent record of that kind in Settings → Agents, making the record when there is none, and names that record on your posts. Pass name when you go by a name of your own: the record carries it, and the name is how Roma tells you from another agent of your kind (a fresh sign-in that states no new name is taken as the person's existing agent of that kind connecting again). Several agents can share one sign-in (every Grok Bot of one account calls through the account's one connection): each registers itself with its kind and its OWN name and gets its own record, its own agentId and its own address. There a name one of the records carries is that agent, and a name none carries never makes a new agent and never renames one by itself: when the person already has an agent of your kind, the call is refused with a question (are you one of them under a new name, or a new one?), nothing is changed, and you answer on the next call with that agent's agentId (it is you, renamed) or with asNew true (you are a new one). Only a first agent of the kind is made without a question. When the person has several agents of your kind and you pass neither a name nor an agentId, the call is refused with the list of them, and nothing is changed: call again with your own name. The answer's keep line carries your agentId: save it in your own memory, never in one other agents read, and pass agentName with your name on every later call. With both, agentId wins. Calling again keeps the same record, and nothing is lost: the record, its key and its history stay; a url given again only updates where Roma delivers, and the user can change or remove any of it in Settings → Agents at any time. A kind outside the list is refused. After it the person can hand you items (the item's Delegate cell shows your record), Roma delivers each delegation and each reply to your posts through your door, and list_items with delegatedTo "me" (or the agent block of get_context) reads your work. On a webhook door Roma POSTs the delivery to the address given here, signed the Standard Webhooks way, text the one-line reason and data.item the item with its webUrl. Answers next, what to do now for your kind, and in agent the record's facts: signalUrl (the public address a hook of yours peeks at, Muse), pollUrl with triggerId (where a program reads its deliveries with its key), mailAddress (the confirmed address Roma mails, Instinct or a mail door; null until confirmed), keyRoad (how your kind uses a key: "bearer" on every call, "signin" as the key on Roma's key sign-in page, null when your kind never needs one), hasKey (a live key exists for the record; the person makes one on the record's page, only where access.canShowKey is true), keyMadeAt (when the newest live key was made), settingsUrl (the record's page in Settings → Agents), reach (how Roma gets a task to you, in the words of the record's page: id helper, checksItself, address, email, subscription, or none while Roma cannot hand you tasks yet, with a label and a line), access (kind signIn for an app's own sign-in, helper when you are started on the person's computer and your access is held there for you, ownKey for an agent that runs by itself on a key; canShowKey true only where a key is made by hand on the page and shown once; canReconnect true for a record that app runs: it has no key to make or replace, the person presses Connect again on its page, and the record keeps its name, history and settings), account (whose Roma this is: the owner's email and name, so you can name the account to the person) and setup (the record's steps with their state, nextStep the id of the first step still to do, null once all are done, and next the same line as the answer's). canBeHandedWork true means Roma reached you and the person can hand you a task now (reachableAt says when); it comes with provenAt set on the same answer. For an agent that app starts, offline true means the app is set up and is not running right now (canBeHandedWork is false then, and nothing is to be set up again), computer names the computer it runs on, and helper.source says who started it: macApp for Roma for Mac, terminal for a command in a terminal.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
agentId | string | no | The record's id: the id in the message the person pasted, also shown on the record's page in Settings → Agents. Wins over kind when both are given. |
kind | "chatgpt" | "dot" | "claude" | "claudeCode" | "codex" | "muse" | "museCode" | "instinct" | "grok" | "grokBot" | "other" | no | Your kind, when the message carried no id: chatgpt (ChatGPT), dot (ChatGPT Dot), claude (Claude), claudeCode (Claude Code), codex (Codex), muse (Muse), museCode (Muse Code), instinct (Instinct), grok (Grok), grokBot (Grok Bot), other (Custom Agent). Over a sign-in these are the only kinds; a call made with a Roma key that was minted for a record claims that record, whatever kind it says. |
name | string | no | The name you go by yourself in your own product, when you have one (a Muse the person named Totoro, a ChatGPT Dot named Lava, a Grok Bot named Groky). The record carries it, and your kind stays its label and its icon. Leave it out when you have no name of your own: the record keeps the name it has. Where several agents share one sign-in (every Grok Bot of one account) the name is who you are: a name one of the person's agents of your kind carries is that agent, and a name none carries is answered with a question while the person has an agent of your kind. To rename yourself there, pass your agentId with the new name. To be a new agent there, pass asNew true with your name. For every other kind a new name from the same connection renames your record: its id, its address, its history and its tasks stay. A name another record of the person holds gets a number. (up to 60 characters) |
asNew | boolean | no | Only with kind and name, where several agents share one sign-in (grokBot): true says you are a NEW agent, not one Roma already has. It is one of the two answers to Roma's question about a name none of the person's agents of your kind carries; the other answer is the existing agent's agentId. |
url | string | no | For an agent reached by a webhook: the https address Roma POSTs each delegation and reply to. A Claude scheduled task's Fire URL gets { text } with the delivery inside; any other address gets the delivery JSON as the body. |
headers | object of string | no | Extra request headers Roma sends on every POST to the agent's address, as that address requires (a scheduled task's fire URL, a routine). Stored, never read back. |
secret | string | no | The receiver's own whsec_ signing secret (a Grok automation shows one when its webhook trigger is made); Roma mints one when absent. (up to 200 characters) |
Returns
agent(object)next(string): What to do next for this kind of agent.pollUrl(string | null): For a bridge: where to read deliveries with your key (the same address as agent.pollUrl).keep(string): One line to save where you keep the Roma skill or your notes: your record's name and its agentId, and the call it is for. After any reconnect or new sign-in call register_agent with that agentId, or with your kind and that name, so Roma knows you again and makes no second record. Absent for a key caller, for Claude Code and Codex, which never pass an agentId (they claim again with their kind and name), and beside answeredAs.answeredAs(string): Present when you passed no name where several agents share one sign-in (every Grok Bot of one account) and the sign-in's one agent has a name of its own: it says which agent Roma answered as. You are that agent: nothing to do. You are another agent of the account: call again with your own name. No keep line comes with it.warning(string): Present when the claim answered WITHOUT binding this sign-in to the record: the record is bound to another sign-in, it is a Mac kind's record and this sign-in is not its CLI, or it is an agent running on a key of its own. Says where the person changes it. Absent when the sign-in was bound.
Example
{
"method": "tools/call",
"params": {
"name": "register_agent",
"arguments": {}
}
}
get_guide
Get the Roma guide or the Roma skill · Read-only
The Roma guide for agents and the Roma skill as text, the same as roma.app/agents.md, its pages and roma.app/skill.md, for the texts you copy for the person, whole. Read index, then rules once per session, then your section; help only when a step fails. Call it once after connecting; pass kind when Roma does not know yours yet. Pass part "index" for agents.md, "rules" for agents/rules.md, "section" for your kind's page, "help" for your kind's help page; both (the default) is index, rules and section together. Pass part "skill" for the Roma skill, the same text as roma.app/skill.md, when your fetch tool refuses that address, and "skill-full" for the full skill at roma.app/skill-full.md.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
kind | string | no | Your kind, when Roma does not know it yet: chatgpt (ChatGPT), dot (ChatGPT Dot), claude (Claude), claudeCode (Claude Code), codex (Codex), muse (Muse), museCode (Muse Code), instinct (Instinct), grok (Grok), grokBot (Grok Bot), hermes (Hermes), poke (Poke), town (Town), webhook (A webhook), email (An agent with an inbox), other (Custom Agent). Left out, the record this call is made under names it. |
part | "both" | "index" | "rules" | "section" | "help" | "skill" | "skill-full" | no | Which part to return: both (the default: index, rules and your section), index (agents.md alone), rules (the rules for every kind alone), section (your kind's section alone), help (your kind's help page, for a step that fails), skill (the Roma skill, the text of roma.app/skill.md), or skill-full (the full skill, roma.app/skill-full.md). |
Returns
version(string): The guide's version line.index(string): agents.md as Markdown: the first message, the order of the first calls, the two parts, the links. With part both or index.rules(string): The rules for every kind as Markdown, agents/rules.md. With part both or rules.section(object | null): Your kind's section as Markdown, under its title. Null when the kind is not known or has no section of its own. With part both or section.help(object | null): Your kind's help page as Markdown. Null when the kind has no help page yet. Only with part help.skill(string): The Roma skill as Markdown, the text of this build's /skill.md (part skill) or /skill-full.md (part skill-full).pages(object)note(string): Why the section or the help page is missing, when it is.
Example
{
"method": "tools/call",
"params": {
"name": "get_guide",
"arguments": {}
}
}