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 projects with ids, their lists with column 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 project, pass focusProjectId to narrow the task sections.

Make Roma the 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:

1. Add this to the chat's custom instructions, a Claude project's instructions, or the memory the assistant keeps:

   At the start of a conversation about my work, plans or anything I keep, use Roma's get_context to see my tasks, notes and what I asked it to remember. Save tasks and notes to Roma when I ask.

2. 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, "remind me to call the dentist tomorrow" becomes create_task with a due time, and "what did I decide about the lease?" becomes search followed by get_note.

Save research as a note in a project

A person asks the assistant to research something and keep the result.

1. list_projects to resolve the project's name to its id. If none fits, leave projectId out and the note lands unsorted.
2. create_note with a title and the body as Markdown. Headings, lists and links survive; nothing is rewritten.
3. Later additions go through update_note with mode: "append", or insertAfter with an anchor line to place them under a heading.

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."

1. list_collections to find the list and its columns with their ids.
2. add_collection_items with one row per book, values keyed by column id or name. A select value may be a label; an unknown label becomes a new option.
3. Pass matchOn (the title column, say) when the same batch might be sent twice, so a retry merges instead of duplicating.
4. Corrections go through update_collection_items, never a second add: only the keys you send change.

Work from a task

An agent that does the work, not just the reminding.

1. get_task_context for the task: its body, its subtasks, its project.
2. update_task with taskStatus: "inProgress" so the person sees it moving.
3. Do the work. Append findings, links and drafts to the body with update_task (append is the default).
4. update_task with taskStatus: "completed", or leave it in progress with a note on what is still open.

A call that changes nothing returns the row 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.

Read what an automation found

"What did my morning briefing say today?"

1. list_automations, which also rides get_context, to find the automation's id.
2. get_automation_runs for 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.

Undo

Every delete is soft. list_deleted shows the trash with each item's purge day; restore_deleted with the item's type and id brings it back. A task whose project was deleted meanwhile returns unsorted. A row whose list is still deleted asks you to restore the list first.

Troubleshooting