> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/mcp/tools.md).

# MCP tool reference

Browse all 97 Unitlab MCP tools for projects, data, annotation, AI labeling, workflows, quality, releases, and administration.

This reference covers the current **97 registered Unitlab MCP tools**, grouped by task. The catalog shown in your assistant depends on your workspace role and connection permissions. A listed tool can also require a particular project, task, or processing state.

## Read the current tool schema

MCP clients receive each available tool's typed input schema from the server. Use that schema for the exact arguments and required fields. Do not infer IDs or argument names from these summaries.

The assistant can request detailed Unitlab guidance with:

```json
{"tool": "save_annotations"}
```

Pass this input to `get_help`. It returns the tool's purpose, requirements, arguments, next steps, common errors, and related journeys.

Other useful `get_help` inputs are:

```json
{"topic": "upload-files"}
```

```json
{"topic": "pointcloud"}
```

Call `get_help` without arguments to list all available guides. For a live blocker, use `diagnose` with the relevant project, item, or task ID.

## How to read this reference

* **Read** means the tool is designated as a read operation. Your role and object visibility still apply.
* **Write** means the connection must have write access. Some write tools offer a preview or `dry_run`, but still require write access.
* A tool may perform several actions. Read its schema and help before using delete, trash, publication, membership, or workflow-changing arguments.
* Take identifiers from fresh tool results. Keep annotation revisions and workflow stage IDs current.

For an end-to-end sequence, see [Quickstart](https://docs.unitlab.ai/api-sdk-cli/mcp/quickstart) and [Workflows and automation](https://docs.unitlab.ai/api-sdk-cli/mcp/workflows).

## Getting started and help

| Tool          | Access | Purpose                                                                                                               |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| `get_context` | Read   | Show the connected workspace, member, effective permissions, write availability, supported data families, and limits. |
| `diagnose`    | Read   | Inspect current blockers for a connection, project, item, or task and suggest the next tools.                         |
| `get_help`    | Read   | Read built-in guides for a tool, workflow journey, data family, or error message.                                     |

## Projects and ontologies

| Tool                   | Access | Purpose                                                                                                        |
| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| `list_ontologies`      | Read   | List project or unattached workspace ontologies, or versions of a selected ontology.                           |
| `get_ontology`         | Read   | Read class, property, and option definitions, including their integer values.                                  |
| `create_ontology`      | Write  | Create classes for a project and establish its Live ontology when needed.                                      |
| `update_ontology`      | Write  | Change Live classes, properties, options, attributes, or required fields; remove or restore supported entries. |
| `set_ontology_version` | Write  | Publish an ontology draft, restore a previous version into a draft, or switch the Live ontology.               |
| `get_instructions`     | Read   | Read project labeling instructions and links to attached instruction files.                                    |
| `list_projects`        | Read   | Find projects visible to the connected member, with search and pagination.                                     |
| `get_project`          | Read   | Inspect a project's data, classes, settings, and active workflow.                                              |
| `create_project`       | Write  | Create an empty project with a default workflow.                                                               |
| `update_project`       | Write  | Update project settings or labeling instructions; also supports explicit deletion actions.                     |

## Data ingestion and curation

| Tool                 | Access | Purpose                                                                                                              |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `list_assets`        | Read   | Search and inspect accessible workspace library assets and their organization.                                       |
| `prepare_upload`     | Write  | Prepare a scoped file-transfer URL or multipart/folder upload session; it does not send the file bytes.              |
| `complete_upload`    | Write  | Finalize multipart uploads, LiDAR scene folders, and medical sessions that require completion.                       |
| `get_upload_status`  | Read   | Check processing and readiness of uploaded project items or library assets.                                          |
| `attach_data`        | Write  | Attach existing library assets to a project, optionally previewing the effect first.                                 |
| `detach_data`        | Write  | List attached sources, or detach a selected source or project-owned data; optional annotation clearing is permanent. |
| `group_assets`       | Write  | Combine related library files into Data Groups for grouped annotation work.                                          |
| `list_items`         | Read   | Search, filter, and page through project items with their tasks and workflow state.                                  |
| `update_items`       | Write  | Manage project item priority, tags, folders, archive state, benchmark designation, or permanent deletion.            |
| `create_tag`         | Write  | Create an item tag available to the project.                                                                         |
| `update_assets`      | Write  | Archive, unarchive, move, tag, trash, restore, or permanently delete selected library assets, folders, and datasets. |
| `create_dataset`     | Write  | Create a dataset from selected library assets.                                                                       |
| `update_dataset`     | Write  | Manage dataset metadata, add files, publish a version, or restore a previous version into the draft.                 |
| `update_folder`      | Write  | Create or rename library folders and register cloud-linked folder contents by reference.                             |
| `update_collection`  | Write  | Create, rename, add to, remove from, or delete a named collection of library files.                                  |
| `start_cloud_import` | Write  | Import selected cloud-storage object paths into a project by reference and start item processing.                    |

## Content and annotation

| Tool                    | Access | Purpose                                                                                                            |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `get_annotation_schema` | Read   | Read the item's allowed object types, coordinate units, classes, properties, and examples.                         |
| `get_annotations`       | Read   | Read existing labels, properties, tags, and the current revision; supports item and private-copy contexts.         |
| `validate_annotations`  | Read   | Check a proposed annotation change without storing it, including remaining validation problems.                    |
| `save_annotations`      | Write  | Add, update, or delete selected annotations with a revision check; omitted objects remain unchanged.               |
| `read_content`          | Read   | Read media, frames, slices, pages, text, rows, or audio with coordinate metadata and optional annotation overlays. |
| `paint_points`          | Write  | Assign or clear LiDAR point labels inside a supported region across selected frames.                               |

## AI-assisted labeling

| Tool                   | Access | Purpose                                                                                                         |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `segment_object`       | Write  | Generate a box, polygon, or mask from a box or click prompts on supported imagery.                              |
| `detect_objects`       | Write  | Detect instances of one requested class on a supported item or frame.                                           |
| `find_similar_objects` | Write  | Find objects resembling an example within the same supported item or frame.                                     |
| `refine_objects`       | Write  | Improve existing polygon or mask geometry with geometric or supported smart refinement.                         |
| `track_object`         | Write  | Extend an existing supported object track through video, medical slices, or a calibrated-camera LiDAR sequence. |

## Models and reference examples

| Tool                      | Access | Purpose                                                                                                                  |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `list_models`             | Read   | Inspect models available to the workspace, including modality, classes, prompt/reference requirements, and availability. |
| `get_model_run`           | Read   | Read a task's current or latest model-run state, progress, error, and retry eligibility.                                 |
| `start_model_run`         | Write  | Start or retry an eligible task at its current Model stage.                                                              |
| `cancel_model_run`        | Write  | Request cancellation of the task's current background model run.                                                         |
| `get_references`          | Read   | Read a Model stage's example items, private copies, approved objects, and published reference state.                     |
| `save_reference_examples` | Write  | Draw, approve, and publish reference objects for a workflow Model stage.                                                 |
| `delete_reference_object` | Write  | Remove a published reference object from its stage's examples.                                                           |
| `create_model`            | Write  | Register a workspace model endpoint as a draft for testing and confirmation in the web app.                              |
| `update_model`            | Write  | Manage an existing workspace model's settings or remove it.                                                              |

## Tasks and workflows

| Tool                  | Access | Purpose                                                                                             |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `list_tasks`          | Read   | Browse workflow stages or the tasks available in a selected stage.                                  |
| `get_task`            | Read   | Read a task's item, stage, assignment, available actions, and rejection feedback.                   |
| `get_next_task`       | Read   | Find the next task the member can work on without claiming it.                                      |
| `get_group`           | Read   | Read a Data Group and the related files that form its annotation task.                              |
| `claim_task`          | Write  | Take an eligible free task for the connected member.                                                |
| `assign_tasks`        | Write  | Assign eligible tasks to workspace members.                                                         |
| `release_task`        | Write  | Return a claimed task to the queue when the member has the required management permission.          |
| `get_workflow`        | Read   | Read the active graph, stages, edges, configuration, and stage item counts.                         |
| `configure_workflow`  | Write  | Validate or apply a complete workflow graph; a dry run reports affected tasks and model runs.       |
| `perform_task_action` | Write  | Apply an available task action, such as completing annotation, approving review, or rejecting work. |
| `move_tasks`          | Write  | Move selected tasks to a workflow stage, with dry-run impact reporting.                             |

## Quality and consensus

| Tool                      | Access | Purpose                                                                                               |
| ------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `claim_consensus_task`    | Write  | Claim the member's eligible private Consensus assignment.                                             |
| `get_consensus_task`      | Read   | Inspect a Consensus assignment and its state.                                                         |
| `submit_consensus_vote`   | Write  | Submit the member's annotated Consensus copy as a vote.                                               |
| `get_consensus_review`    | Read   | Read Consensus votes and the review state for a reviewer.                                             |
| `set_consensus_approval`  | Write  | Select or change object approvals while reviewing Consensus results.                                  |
| `finish_consensus_review` | Write  | Finish the Consensus review and publish its resulting annotations.                                    |
| `list_gold_labels`        | Read   | List benchmark answer keys and their item or private-copy references.                                 |
| `update_gold_label`       | Write  | Approve a benchmark answer key as a new version, or permanently delete the benchmark and its results. |
| `get_gold_results`        | Read   | Read benchmark comparisons and quality results.                                                       |
| `get_quality_issues`      | Read   | Find annotation validation problems and other supported quality issues.                               |
| `get_consensus_report`    | Read   | Read Consensus comparison and agreement reporting.                                                    |

## Comments and notifications

| Tool                      | Access | Purpose                                                                                        |
| ------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `list_comments`           | Read   | Read comment threads for accessible items or tasks.                                            |
| `add_comment`             | Write  | Add a comment or reply, optionally pinned to a location on the item.                           |
| `resolve_comment`         | Write  | Resolve or reopen a comment thread.                                                            |
| `list_issues`             | Read   | List accessible project comment threads, with status, creator, and responsible-member filters. |
| `list_notifications`      | Read   | Read notifications for the connected member.                                                   |
| `mark_notifications_read` | Write  | Mark selected notifications as read.                                                           |

## Releases and exports

| Tool                   | Access | Purpose                                                                                             |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `list_releases`        | Read   | List a project's dataset releases and their states.                                                 |
| `get_release`          | Read   | Read release metadata, progress, error details, and optional included items.                        |
| `retry_release`        | Write  | Retry a failed release without creating a new release identifier.                                   |
| `create_release`       | Write  | Create a versioned dataset export with supported formats, filters, and split percentages.           |
| `get_release_download` | Write  | Generate a temporary release download link; requires write access because the download is recorded. |
| `clone_release`        | Write  | Create a new project from a ready release, with annotations or items only.                          |
| `delete_release`       | Write  | Delete the selected release using its explicit destructive operation.                               |
| `update_release`       | Write  | Change release visibility or license settings and inspect available licenses.                       |

## Members and roles

| Tool            | Access | Purpose                                                                  |
| --------------- | ------ | ------------------------------------------------------------------------ |
| `list_members`  | Read   | List workspace members and their current role or assignment information. |
| `update_member` | Write  | Manage supported membership, role, status, or invitation actions.        |
| `list_roles`    | Read   | Read available workspace roles and permission definitions.               |
| `create_role`   | Write  | Create a custom role with selected permissions.                          |
| `update_role`   | Write  | Change or remove an eligible custom role.                                |

## Administration and statistics

| Tool                   | Access | Purpose                                                                                           |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `create_api_key`       | Write  | Create a workspace API key for SDK/API use and return the secret once; separate from MCP sign-in. |
| `update_api_key`       | Write  | Manage an existing workspace API key's settings, enabled state, or removal.                       |
| `list_cloud_storages`  | Read   | List connected cloud storage configurations without exposing stored secrets.                      |
| `create_cloud_storage` | Write  | Add a cloud storage configuration for supported import workflows.                                 |
| `update_cloud_storage` | Write  | Change or remove a connected cloud storage configuration.                                         |
| `list_audit_events`    | Read   | Inspect accessible workspace audit events with the supported filters.                             |
| `get_statistics`       | Read   | Read supported project or workspace progress and activity statistics.                             |

## Common contracts

### Pagination

List tools return a continuation such as `next_offset`. Pass it as `offset` to read the next page. `get_context` reports the maximum page size; some tools use lower limits. A partial page of annotations or items is not the complete dataset.

### Annotation revisions

Read `get_annotations` before editing and pass its `revision` as `expected_revision`. Use `null` when the item has no saved annotation version. A stale revision is rejected so an assistant does not silently overwrite another annotator's work.

### Idempotency

Tools that create resources or record supported actions can accept an `idempotency_key`. Use one new key per intended action and reuse it only for the identical retry. If a response is lost, read the current state before submitting another write.

### Asynchronous work

Uploads, model runs, and exports may return an identifier before processing finishes. Follow the returned `next_step` and poll the matching status tool. Do not create a second operation merely because the first is still processing.

### Destructive and externally visible actions

Project deletion, permanent asset deletion, release publication, membership changes, and workflow changes have effects beyond the current chat. Use the specific action only when it is intended. Review dry-run output where supported. Library trash and restore behavior can affect attached project copies differently; restoring a library file does not necessarily restore its deleted project annotations.

### Secret-bearing administration

`create_api_key` reveals the new secret only once through the assistant. A connection whose permission list withholds any part of the member's role cannot create such a key because the key would not inherit that narrowed list. Keep credentials out of shared conversations and public outputs.

## Help with a failed call

Errors commonly include a **Next:** sentence. Follow it or pass the error text to `get_help` using its `error` argument. See [Troubleshooting](https://docs.unitlab.ai/api-sdk-cli/mcp/troubleshooting) for connection, permissions, upload, model, and release problems.