Tools

Every tool the Roma MCP server offers, as a client sees it over tools/list. 29 tools, in 7 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
• Tasks: list_tasks, get_task_context, create_task, update_task, delete_task
• Projects: list_projects, create_project, update_project
• Notes and search: search, list_notes, get_note, create_note, update_note, delete_note
• Collections: list_collections, get_collection_items, create_collection, update_collection, delete_collection, add_collection_items, update_collection_items, delete_collection_items, create_image_upload
• Trash: list_deleted, restore_deleted
• Automations: list_automations, get_automation_runs, run_automation

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 the two row tools download images from public URLs you name.

Ids. Every task, note, project, list, row 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.

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, what is due, recent notes, lists, automations and what they asked Roma to remember.

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 projects; overdue, due-today, in-progress and upcoming tasks; unsorted tasks; recently touched notes; their collections with columns; their automations with the last run; and the last few days of activity. Everything comes with ids for follow-up calls. It is an overview, not the full data: use search, list_tasks, get_note or get_collection_items for depth. Pass focusProjectId to scope the task sections to one project.

Parameters

Returns

• about (string[])
• user (object)
• unavailable (string[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "get_context",
    "arguments": {}
  }
}

Tasks

The to-do list. Create, list, read, update, move and delete tasks, each scoped to a project or left unsorted.

list_tasks

List tasks · Read-only

List, filter, and search the user's tasks — the way to find work to pick up. Returns tasks ordered by due date, then priority. Scope to the whole workspace, unsorted tasks only, or a single project. By default completed tasks are excluded.

Parameters

Returns

• count (number)
• tasks (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": {}
  }
}

get_task_context

Get task context · Read-only

Fetch one task with everything needed to start working on it: the full task row (description, status, priority, due date) and the project it belongs to. The equivalent of opening an issue.

Parameters

Returns

• task (object)
• project (object | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "get_task_context",
    "arguments": {
      "artifactId": "<artifactId>"
    }
  }
}

create_task

Create task · Adds data

Create a task. Omit projectId to leave it unsorted (no project); set projectId to file it under a project. The task is enriched by AI in the background after creation, so enriched fields may appear on a subsequent read. Returns the created task.

Parameters

Returns

• id (string)
• title (string | null)
• description (string | null)
• taskStatus (string | null)
• priority (string | null)
• dueAt (string | null)
• projectId (string | null)
• createdAt (string | null)
• updatedAt (string | null)
• editedAt (string | null)
• completedAt (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "title": "<title>"
    }
  }
}

update_task

Update task · Updates or removes existing data · Safe to retry

Update fields on an existing task — title, body, status, priority, due date, or which project it is in (projectId; null moves it out to unsorted). Use status transitions to report progress (e.g. todo → inProgress → completed). Only the fields you pass are changed. The body merge mode controls how description combines with the existing body — adding text appends/prepends; it never replaces unless you explicitly ask it to.

Parameters

Returns

• id (string)
• title (string | null)
• description (string | null)
• taskStatus (string | null)
• priority (string | null)
• dueAt (string | null)
• projectId (string | null)
• createdAt (string | null)
• updatedAt (string | null)
• editedAt (string | null)
• completedAt (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "update_task",
    "arguments": {
      "taskId": "<taskId>"
    }
  }
}

delete_task

Delete task · Updates or removes existing data · Safe to retry

Delete a task (or subtask) by id. This is a SOFT delete — the task is recoverable for ~30 days before it is purged. Deleting a task also removes it from search. Deletes one task per call so each delete is confirmed individually.

Parameters

Returns

• deleted (boolean)
• id (string)
• title (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "delete_task",
    "arguments": {
      "artifactId": "<artifactId>"
    }
  }
}

Projects

Containers for tasks, notes and lists. Resolve names to ids before filing anything.

list_projects

List projects · Read-only

List all of the user's projects. Use this to resolve a project name to its UUID before creating or filing a task, or to understand the workspace structure.

Parameters

This tool takes no parameters.

Returns

• count (number)
• projects (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

create_project

Create project · Adds data

Create a project — a folder that groups the user's tasks and notes. Use it when the user wants a new project, or to give work a home that has none; check list_projects or get_context first so an existing project is not duplicated. Returns the project with its id, ready for create_task / update_task projectId.

Parameters

Returns

• id (string)
• name (string | null)
• emoji (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "create_project",
    "arguments": {
      "name": "<name>"
    }
  }
}

update_project

Update project · Updates or removes existing data · Safe to retry

Rename a project or change its emoji. Only the fields you pass change; emoji null removes it. Does not move or change the project's tasks.

Parameters

Returns

• id (string)
• name (string | null)
• emoji (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "update_project",
    "arguments": {
      "projectId": "<projectId>"
    }
  }
}

Notes and search

Prose the user keeps. Search finds notes, tasks and list rows by meaning or keyword; notes are read and written as Markdown.

search

Search notes & tasks · Read-only

Search the user's Roma workspace — their notes, tasks, typed lists and the rows inside them — 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; get_note returns a note's full text. An empty result means nothing relevant is saved. Not for general web knowledge.

Parameters

Returns

• count (number)
• results (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "<query>"
    }
  }
}

list_notes

List notes · Read-only

List the user's notes, newest first. Scope to the whole workspace, unsorted notes only, or a single project. Returns a snippet of each body; use get_note for the full text. This is browse-by-container — use search to find by topic.

Parameters

Returns

• count (number)
• docs (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "list_notes",
    "arguments": {}
  }
}

get_note

Get note · Read-only

Read one note in full by its id — the companion to search: search returns the matched passage, this pulls the whole document when you need more than the snippet. Returns the note's title and full body as Markdown, and, for a note a meeting was recorded into, the attributed transcript once its recording is done.

Parameters

Returns

• id (string)
• title (string)
• content (string)
• projectId (string | null)
• createdAt (string | null)
• transcript (string)
• recording (object)

Example

{
  "method": "tools/call",
  "params": {
    "name": "get_note",
    "arguments": {
      "docId": "<docId>"
    }
  }
}

create_note

Create note · Adds data

Capture a note for the user. Omit projectId to leave it unsorted (no project); set projectId to file it under a project. The body is stored as authored within the editor's supported Markdown subset (unsupported constructs degrade to plain text) — no AI cleanup or reclassification runs — and indexed for search. Returns the created note.

Parameters

Returns

• id (string)
• title (string | null)
• content (string)
• projectId (string | null)
• createdAt (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "content": "<content>"
    }
  }
}

update_note

Update note · Updates or removes existing data

Edit an existing note — its title, body, or which project it's in. Only the fields you pass change. The body merge mode controls how content combines with the existing body. Re-indexes for search automatically.

Parameters

Returns

• id (string)
• title (string | null)
• content (string)
• projectId (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "update_note",
    "arguments": {
      "docId": "<docId>"
    }
  }
}

delete_note

Delete note · Updates or removes existing data · Safe to retry

Delete a note by id. This is a SOFT delete — the note is recoverable for ~30 days before it is purged. Deleting a note also removes it from search. Deletes one note per call so each delete is confirmed individually.

Parameters

Returns

• deleted (boolean)
• id (string)
• title (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "delete_note",
    "arguments": {
      "docId": "<docId>"
    }
  }
}

Collections

Typed lists: a table with named columns, one row per thing. Rows go in and are corrected many at a time.

list_collections

List collections · Read-only

List the user's collections (typed lists — a reading list, a watchlist, an expenses tracker). Returns each list's id, name, standing instructions, row count, and its COLUMNS with their stable ids — the ids add_collection_items and update_collection_items take. Use it before writing to a collection whose columns you have not read yet. Pass suppressOptions: true when you only need names/counts — select columns can carry hundreds of options (you don't need them to write: a select value may be sent as its label).

Parameters

Returns

• count (number)
• collections (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "list_collections",
    "arguments": {}
  }
}

get_collection_items

Get collection rows · Read-only

Read the rows of one collection. Values are keyed by COLUMN ID (see list_collections); a select column's value is an option id, a multiSelect column's an array of option ids. Each row also lists its image attachments (so you can verify an import's images actually landed); pass includeImageUrls: true for short-lived viewable links. Paginated: the result carries totalCount and hasMore — keep calling with offset until hasMore is false to read a large list completely. Archived rows are left out unless includeArchived: true. Use to check what a list already holds before adding to it.

Parameters

Returns

• count (number)
• totalCount (number)
• offset (number)
• hasMore (boolean)
• items (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "get_collection_items",
    "arguments": {
      "collectionId": "<collectionId>"
    }
  }
}

create_collection

Create collection · Adds data

Create a typed list with its columns. Every column is equal — declare the ones the list actually needs, including a name column if rows have names (a list of measurements or dates may have none). Returns the created list WITH the stable column ids to use when adding rows.

Parameters

Returns

• id (string)
• name (string)
• columns (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "create_collection",
    "arguments": {
      "name": "<name>"
    }
  }
}

update_collection

Update collection · Updates or removes existing data · Safe to retry

Rename a collection or edit its standing instructions. instructions REPLACES the existing text — read the current value first (list_collections) and carry forward anything still true; null clears them. Column (schema) editing is not available over MCP — new select options mint automatically when adding or updating rows.

Parameters

Returns

• id (string)
• name (string)
• instructions (string | null)

Example

{
  "method": "tools/call",
  "params": {
    "name": "update_collection",
    "arguments": {
      "collectionId": "<collectionId>"
    }
  }
}

delete_collection

Delete collection · Updates or removes existing data · Safe to retry

Delete a collection (typed list) by id. Deleting the list also deletes ALL its rows. SOFT delete — the list and its rows are recoverable for ~30 days via restore_deleted (type "collection"), which brings the rows deleted with it back too. When the list still holds rows the call refuses unless confirmDeleteItems is true, so the blast radius is always named before it happens.

Parameters

Returns

• deleted (boolean)
• id (string)
• name (string)
• itemsDeleted (number)

Example

{
  "method": "tools/call",
  "params": {
    "name": "delete_collection",
    "arguments": {
      "collectionId": "<collectionId>"
    }
  }
}

add_collection_items

Add collection rows · Adds data · Reaches outside Roma

Add rows to a collection, many in one call (the import path). Values are keyed by column id or name; a select value may be its label or option id, a multiSelect value is an ARRAY of them, and unknown labels become new options. Keys that match no column come back in unknownKeys. Images that could not be stored come back in imageFailures with the reason; create_image_upload is the reliable path for images. Every row is inserted unless matchOn names columns to match on; a matched row keeps every filled cell and only gains what it lacks (empty cells, notes, images), so nothing is overwritten. To change a filled cell use update_collection_items (re-adding without matchOn creates a duplicate).

Parameters

Returns

• added (number)
• itemIds (string[])
• unknownKeys (string[])
• imagesAttached (number)
• imageFailures (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "add_collection_items",
    "arguments": {
      "collectionId": "<collectionId>",
      "items": [
        {}
      ]
    }
  }
}

update_collection_items

Update collection rows · Updates or removes existing data · Safe to retry · Reaches outside Roma

Update existing rows of ONE collection, many in one call; pass only what changes. values MERGE into the row (only the keys sent change; "" clears a cell), body replaces the notes, imageUrls add images (clearImages: true drops the old ones first), archived sets a row aside or brings it back. A key matching no column is an error; rows earlier in the batch stay updated and are named, so re-send only the rest. Read row ids and current values with get_collection_items first.

Parameters

Returns

• updated (number)
• itemIds (string[])
• imagesAttached (number)
• imageFailures (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "update_collection_items",
    "arguments": {
      "collectionId": "<collectionId>",
      "items": [
        {
          "itemId": "<itemId>"
        }
      ]
    }
  }
}

delete_collection_items

Delete collection rows · Updates or removes existing data · Safe to retry

Delete rows from collections by id — up to 50 per call. SOFT delete: every row stays recoverable for ~30 days via restore_deleted (type "collectionItem") before it is purged, and drops out of search. Returns a per-id result — ids that don't resolve are reported and the rest still delete.

Parameters

Returns

• deleted (number)
• results (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "delete_collection_items",
    "arguments": {
      "itemIds": [
        "<itemIds>"
      ]
    }
  }
}

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 add_collection_items / update_collection_items. Keep images at or under 10 MB (maxBytes). Up to 10 slots per call.

Parameters

Returns

• uploads (object[])
• maxBytes (number)
• validForSeconds (number)

Example

{
  "method": "tools/call",
  "params": {
    "name": "create_image_upload",
    "arguments": {
      "mimeType": "image/png"
    }
  }
}

Trash

Every delete is soft. The trash lists what was deleted and restores one item per call for about 30 days.

list_deleted

List deleted items (trash) · Read-only

The trash: everything soft-deleted in the last ~30 days — tasks, notes, collections, and collection rows — 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 all kinds.

Parameters

Returns

• count (number)
• items (object[])

Example

{
  "method": "tools/call",
  "params": {
    "name": "list_deleted",
    "arguments": {}
  }
}

restore_deleted

Restore deleted item · Adds data · Safe to retry

Bring back one soft-deleted item from the trash (see list_deleted) — a task, note, collection, or collection row. Restoring a collection also brings back the rows deleted with it; a row whose list is still deleted can't come back alone (restore the collection instead). A restored task whose project was deleted meanwhile lands in the inbox (movedToInbox: true). Restores one item per call. If the item is already live the call succeeds with alreadyLive: true.

Parameters

Returns

• restored (boolean)
• alreadyLive (boolean)
• type (string)
• id (string)
• title (string | null)
• restoredItems (number)
• movedToInbox (boolean)

Example

{
  "method": "tools/call",
  "params": {
    "name": "restore_deleted",
    "arguments": {
      "type": "task",
      "id": "<id>"
    }
  }
}

Automations

Standing orders Roma runs on a schedule. Read them, 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_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

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

Returns

• id (string)
• name (string)
• runId (string)
• status (string)

Example

{
  "method": "tools/call",
  "params": {
    "name": "run_automation",
    "arguments": {
      "automationId": "<automationId>"
    }
  }
}