# Guides

The tool sequences behind the things people ask for. Each guide names the calls in order; the [tool reference](/developers/tools) 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

| 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_note` refused a replace | A whole-body replacement needs `confirmReplace: true` | Prefer `append` or `insertAfter`; confirm only when the person asked to rewrite |
| Rows were added twice | `add_collection_items` without `matchOn` inserts every row | Pass `matchOn`; fix the duplicates with `delete_collection_items` |
| A select value was rejected | The value is neither an option id nor a label | Read the column's options from `list_collections` |
| A task moved to the wrong project | The destination id was guessed | Resolve it with `list_projects` first |
| The conversation cannot see a new tool | The client cached the tool list | Refresh the connector, start a new conversation |