MCP tools reference

The Annota AI MCP server exposes the tools below. Your assistant picks them for you based on what you ask, so you rarely need to name a tool. Use this page to understand what an assistant can do once you connect it with MCP.

How tools work

One permission for all tools. There are no per-tool scopes. When you authorize a client, it gets access to every tool, limited to the organizations you belong to and what your permissions allow in each.
Read, write, or destructive. Each tool tells your client whether it only reads data, changes data, or deletes or cancels something for good. Your client can use this to ask for your confirmation before a change. The Type column below shows it.
Organization first. Most tools need an organization and often a dataset or knowledge base. Your assistant finds them with the list tools.
Safe retries. Tools that create something or start a job accept a request ID, so retrying the same call does not create duplicates.
Temporary links. Tools that return files (original assets, exports, model versions, knowledge base originals) return a temporary download link.
No chat tools. The server has no Brain chat tools. Your assistant searches and reads knowledge bases with the tools below and answers with its own model.

Account

Tool	What it does	Type
`get_current_user`	Returns your Annota AI user profile.	Read
`list_organizations`	Lists the organizations you belong to.	Read

Datasets

Tool	What it does	Type
`list_datasets`	Lists the datasets in an organization.	Read
`get_dataset`	Gets one dataset.	Read
`create_dataset`	Creates an image or document dataset.	Write
`update_dataset`	Changes a dataset’s name or description.	Write
`delete_dataset`	Permanently deletes a dataset with its assets, labels, annotations, and finished exports.	Destructive

Assets

Tool	What it does	Type
`list_assets`	Lists the assets in a dataset, optionally filtered by label, annotation presence, or review status.	Read
`get_asset`	Gets one asset’s details and review status.	Read
`get_asset_file`	Gets one asset with a temporary link to its original file.	Read
`create_asset`	Creates an asset and returns a temporary upload link for a local file.	Write
`import_asset`	Imports a file you selected in ChatGPT into an image or document dataset.	Write
`get_file_upload`	Checks whether an uploaded file has been validated and processed.	Read
`update_asset_review_status`	Sets an asset’s review status: unannotated, pending review, approved, or rejected.	Write
`batch_update_asset_review_status`	Sets the review status of 1 to 100 assets in one dataset at once. If one fails, none change.	Write
`delete_asset`	Permanently deletes an asset with its annotations and files.	Destructive
`batch_delete_assets`	Permanently deletes 1 to 100 assets with their annotations, OCR pages, and files. If one fails, none are deleted.	Destructive

Labels

Tool	What it does	Type
`list_labels`	Lists a dataset’s labels and how often each one is used.	Read
`create_label`	Creates a label in a dataset.	Write
`update_label`	Changes a label’s name or color.	Write
`delete_label`	Permanently deletes a label. Its annotations are deleted unless they are moved to another label.	Destructive

Annotations

Tool	What it does	Type
`list_annotations`	Lists the bounding box and polygon annotations of an asset.	Read
`create_annotation`	Creates one bounding box or polygon annotation.	Write
`update_annotation`	Changes an annotation’s label, shape, or both.	Write
`delete_annotation`	Permanently deletes one annotation.	Destructive

Documents and OCR

Tool	What it does	Type
`list_document_pages`	Lists the pages of a document that have OCR text.	Read
`read_document_page`	Reads the Markdown text of one page, in parts of up to 16,000 characters.	Read
`update_document_page`	Replaces the corrected Markdown of one page. It does not change the document’s review status.	Write
`get_ocr_job`	Shows OCR progress: processed, total, and failed pages, with per-page status and errors.	Read
`retry_ocr_job`	Retries unfinished pages after a failed, partial, or paused OCR job.	Write

Exports

Tool	What it does	Type
`list_exports`	Lists a dataset’s exports and their status.	Read
`create_export`	Starts an export: COCO for image datasets, LLM wiki or Markdown ZIP for document datasets.	Write
`get_export`	Gets one export with a temporary download link once it has succeeded and has not expired.	Read
`delete_export`	Permanently deletes a finished export. Exports still running cannot be deleted.	Destructive

Automatic annotation

Tool	What it does	Type
`preview_auto_annotate_run`	Previews the images that would be annotated, conflicts with existing annotations, and an estimate in credits.	Read
`start_auto_annotate_run`	Starts automatic annotation of an image dataset for the labels you choose.	Write
`get_auto_annotate_run`	Gets the latest automatic annotation run of a dataset.	Read

You can annotate only unannotated images, or all ready images. When you annotate all images, existing annotations for the same labels are skipped by default; your assistant can also overwrite them or add duplicates.

Dataset versions

Tool	What it does	Type
`list_dataset_snapshots`	Lists a dataset’s versions and their capture status.	Read
`get_dataset_snapshot`	Gets one version’s capture status and content counts.	Read
`create_dataset_snapshot`	Captures a new version of a dataset for training or export.	Write
`delete_dataset_snapshot`	Permanently deletes a version. Versions used by training or by an active export cannot be deleted.	Destructive

Models and training Private beta

Training is available to organizations in the private beta.

Tool	What it does	Type
`list_base_models`	Lists the pretrained bases you can start from, and the default one.	Read
`list_models`	Lists the models in an organization.	Read
`get_model`	Gets a model and whether training is enabled for it.	Read
`create_model`	Creates an object detection model.	Write
`update_model`	Changes a model’s name and description.	Write
`delete_model`	Permanently deletes a model with its training history and versions. Active training must stop first.	Destructive
`start_training_run`	Trains a model on a ready image dataset version. Only reviewed images are used; polygons become bounding boxes.	Write
`list_training_runs`	Lists a model’s training history and progress.	Read
`get_training_run`	Gets one training run with its configuration, progress, and metrics.	Read
`cancel_training_run`	Cancels queued or active training.	Destructive
`list_model_versions`	Lists a model’s successful versions and their final metrics.	Read
`get_model_version_download`	Returns a temporary download link for a model version.	Read

Knowledge bases

Tool	What it does	Type
`list_knowledge_bases`	Lists an organization’s knowledge bases with their sync status.	Read
`get_knowledge_base`	Gets a knowledge base with its indexed, pending, failed, and excluded documents.	Read
`create_knowledge_base`	Creates a knowledge base for a document dataset, or for a new empty one. It keeps following the dataset.	Write
`update_knowledge_base`	Changes a knowledge base’s name and description, and whether only approved documents are indexed.	Write
`delete_knowledge_base`	Deletes a knowledge base and its index. The document dataset stays.	Destructive
`retry_knowledge_base_documents`	Queues failed documents for indexing again.	Write
`list_knowledge_base_documents`	Lists a knowledge base’s documents with their indexing status and failures.	Read
`get_knowledge_base_index`	Reads the knowledge base’s document index: documents, page counts, and short summaries.	Read
`get_knowledge_base_document`	Reads one document’s summary and details.	Read
`search_knowledge_bases`	Searches the pages of up to 10 knowledge bases by keywords, including pages with similar meaning.	Read
`read_knowledge_base_pages`	Reads 1 to 5 original pages of one document, so your assistant can cite them.	Read
`get_knowledge_base_original`	Returns a temporary link to a document’s original file.	Read

Search results point your assistant to pages; it reads those pages before it cites them.

Tools that use credits

These tools use credits from your organization’s balance, the same as in the app:

Tool	Credits
`create_asset`, `import_asset` (documents), `retry_ocr_job`	OCR of document pages.
`start_auto_annotate_run`	Charged per image after inference; runs only while the balance is positive.
`create_knowledge_base`, and later changes to its dataset	Indexing of new or changed pages.
`search_knowledge_bases`	A few credits per search; needs a positive balance.

Reading pages, listing, and downloading do not use credits. Estimates in tool results are in credit units, where 10 units make one credit. See Credit usage for details.