Guides
The tool sequences behind the things people ask for. Each guide names the calls in order; the tool reference has every parameter.
Start every conversation oriented
Call get_context before anything else that touches the workspace. One call, about a thousand tokens, and the model knows the person's name and timezone, what is due, what is in progress, their lists with their ids and property ids, and what they asked Roma to remember. Every later call can then name an id instead of searching for it.
For a conversation that is about one list, pass focusListId to narrow the task sections.
Make Roma the to-do list your assistant reaches for
No AI chat has a "default task app" setting. What decides where "add this to my list" lands is the tool description the model reads and the instructions the person gave. Two lines do most of the work:
-
Add this to the chat's custom instructions, a Claude project's instructions, or the memory the assistant keeps:
Roma is my task app. At the start of a conversation about my work, plans or anything I keep, call Roma's get_context to see my tasks, notes and what I asked it to remember. When I mention something I need to do, add it to Roma as a task. When I ask what to work on next or what is on my plate, answer from Roma.
-
In Claude, set Roma's read-only tools to Always allow under Customize, then Connectors, so the orientation call runs without a prompt. In ChatGPT, choose the permission level for the plugin that suits you.
After that, "call the dentist tomorrow" becomes create_items on the Tasks list with tomorrow as a day, "tomorrow at 3 PM" the same with a local time that also arms a reminder, and "what did I decide about the lease?" becomes search followed by get_item.
Save research as a note
A person asks the assistant to research something and keep the result.
list_liststo find the list it belongs on, by name. If none fits,listId: "notes"lands it on the Notes list.create_itemswith one entry: a title and the body as Markdown. Headings, lists and links survive; nothing is rewritten.- Later additions go through
update_itemswithedits: aninsertat theendof the body, or at thesectionEndof the heading they belong under. The olderbodywithmode: "append", orinsertAfterwith ananchorline, still works.
Before creating, search the topic once. What the person refers to usually already exists, and a second copy drifts from the first.
Fill a list from a conversation
"Add these five books to my reading list."
list_liststo find the list and its properties with their ids.create_itemswith the list's id and one entry per book, itsvaluesas{ propertyId, value }pairs keyed by property id or name. A select value may be a label; an unknown label becomes a new option.- Pass
matchOn(the property that names the thing, say) when the same batch might be sent twice, so a retry merges instead of duplicating. - Corrections go through
update_items, never a second create: only the values you send change.
Work from a task
An agent that does the work, not just the reminding.
get_itemfor the task: its body with a short handle in front of every block, itsbodyVersion, a line ofguidanceabout its state, and its list.read_chat_messagesfor what the person said there.update_itemswithtaskStatus: "inProgress"when the work actually starts, so the person sees it moving.- Do the work in the body with
update_itemsedits:replacea block,insertnext to one,setCheckeda checklist item,delete,move,replaceText, orrewritethe whole body with thebodyVersionread. Continue what is already there; never add a second copy of it. (The olderbodywithmodeappend / prepend / insertAfter / replace still works.) - Leave it in progress.
completedis the person's call. Post in the chat withpost_chat_messageonly for an action taken outside Roma, with its link, or the one question the work is blocked on.
A call that changes nothing returns the item without writing. A conflict with a write Roma made a moment earlier is retried once on the server, so an edit right after a create lands.
Run a worker loop
Roma as the queue for an agent that runs on its own: the person files tasks from their phone, the agent picks them up, does the work, and reports in the task's chat, where the person answers.
- Read by cursor, once per cycle.
list_itemswithchangedSinceset to the previous cycle'snextChangedSince(the first time, the instant the worker started) answers every item on the Tasks set whose record moved since, oldest change first, the deleted ones underdeleted, andnextChangedSincefor the next cycle.listIdnarrows it to one list. Never re-read the whole list each cycle. - Pick up a task that is
todoand set itinProgresswithupdate_itemsthe moment work starts. Leave it there when the work is done;completedis the person's call. - Do the work in the body with
update_itemsedits. Post in the chat withpost_chat_messagefor an action taken outside Roma, with its link, or the one question the work is blocked on, withneedsInput: true. - Read the person's answer with
read_chat_messagesandsinceset to thecreatedAtof the last message the worker saw. The chat is how the person steers the agent; the body is where the work lands. - A cycle every minute or two is plenty. The limit is 60 calls a minute per connection, and a worker on cursors makes two or three calls a cycle.
A trigger replaces the scheduled read: Roma wakes the worker when a task changes or a reply lands, by webhook or by a poll the worker holds open.
Read what an automation found
"What did my morning briefing say today?"
list_automations, which also ridesget_context, to find the automation's id.get_automation_runsfor its recent runs: the closing message each run left, what it did, when.
To start one, run_automation. The client asks first, because a run can act through the person's connected apps; the result lands in their Roma chat and get_automation_runs reads it back a moment later. "What does it actually do" is get_automation: the steps as written, the schedule, the last run.
Work under one of the person's experts
"Use my Content Editor on this." The person keeps experts in Roma: named bodies of standing instructions for a kind of work, private to them.
get_expertby name, or by the idget_contextcarries beside the names: its instructions as Markdown. Read it once; the instructions apply to the rest of the conversation.- Do the work here, under those instructions: the draft, the review, the edit through
update_items. - A task or note made for that work can carry the expert:
expertIdoncreate_items, or later onupdate_items. In Roma that expert then answers by default in the item's chat.
"My Wordsmith keeps writing long, add a rule." get_expert, then update_expert with the whole instructions and the new rule in them; the previous body stays in the expert's version history. A new expert is create_expert, only when the person asks for one.
Undo
Every delete is soft. list_deleted shows the trash with each entry's purge day; restore_deleted with the entry's type (item or list) and id brings it back. Restoring a list brings back the items deleted with it. An item whose list is still in the trash asks you to restore the list first; one whose list is gone for good lands on the Tasks list.
A body, or an expert's instructions, that was rewritten: list_versions shows the history newest first, each entry the body as it was before that write, and restore_version with the entry that names the edit puts it back. The current body is snapshotted first, so a restore is itself undoable. When the person edited the body in Roma after that version, the call names those edits and waits for acceptLaterEdits: true; edits made over this connection never ask.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "not found" for an id you just read | The id belongs to another person, or the item was deleted since | Read it again; check list_deleted |
update_items refused a replace | A whole-body replacement needs confirmReplace: true | Prefer edits, or append and insertAfter; confirm only when the person asked to rewrite |
| Items were added twice | create_items without matchOn inserts every entry | Pass matchOn; fix the duplicates with delete_items |
| A select value was rejected | The value is neither an option id nor a label | Read the property's options from list_lists |
| An item moved to the wrong list | The destination id was guessed | Resolve it with list_lists first |
move_items answered a preview and moved nothing | The destination has no place for some of the values | Tell the person what would be dropped; repeat with acknowledgeDataLoss: true only once they agree |
get_expert answered not found | The name is not one of the person's experts as written, or the id is someone else's | list_experts for the names and ids; pass the id |
restore_version answered needsConfirmation | The person edited the body in Roma after that version | Say what would go and ask; repeat with acceptLaterEdits: true only once they agree |
| The conversation cannot see a new tool | The client cached the tool list | Refresh the connector, start a new conversation |