Skip to main content
Glama
amanharshx

ultralytics-mcp

by amanharshx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

auto_annotate_start

Start a billable auto-annotation run that labels a dataset with a chosen model; requires confirm_cost, snapshots a dataset version, and can be polled or undone.

Instructions

Start an auto-annotation run on a dataset by slug, owner/slug, or a ul://owner/datasets/slug URI, labelling it with a model given by owner/project/model, ul://owner/project/model, or slug with a project (state-changing, billable, may cost credits). Requires confirm_cost=true: there is no cost preview, no published rate, and a 402 signals insufficient credits; gauge magnitude with datasets_get (the unlabeled image count by default, the total count when include_annotated is true). Sends only modelId plus any of confidence, iou, class_mapping, and include_annotated the caller sets explicitly, omitting the rest so the server's own defaults (confidence 0.25, iou 0.7, include_annotated false, illustrative only) apply undisturbed. There is no imgsz parameter. class_mapping bridges a model/dataset class-taxonomy mismatch (for example a 1-class model against an 80-class dataset, which otherwise fails outright); it passes through with no length check. Labels are additive, never overwritten, so no overwrite confirmation is needed. Every start snapshots a dataset version before labelling, listed via datasets_get and undoable exactly with dataset_version_restore. Billing settles at run time, not at dismissal, so auto_annotate_stop does not refund a charge already incurred. Use auto_annotate_status to poll and auto_annotate_stop to cancel.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
iouNoIoU threshold for generated labels. Omit to use the server default (currently 0.7).
modelYesModel ref by owner/project/model, ul:// URI, or slug (requires project).
datasetYesDataset ref by slug, owner/slug, or a ul://owner/datasets/slug URI.
projectNoProject ref required when model is given by slug.
confidenceNoConfidence threshold for generated labels. Omit to use the server default (currently 0.25).
confirm_costNoMust be true to allow a credit-costing auto-annotation run.
class_mappingNoModel class index -> dataset class index mapping, positioned by model class index. Required to bridge a class-taxonomy mismatch between the model and the dataset; passed through with no length check.
include_annotatedNoRe-label images that already carry annotations. Omit to use the server default (currently false).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.15
    • addedInput schema / additionalProperties
      Added value: +false
  2. Changed1 schema field changedv0.1.13
    • changedInput schema / properties / dataset / description
      Previous value: -"Dataset ref by slug, owner/slug, or ul:// URI."New value: +"Dataset ref by slug, owner/slug, or a ul://owner/datasets/slug URI."
  3. Addedv0.1.12

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds substantial behavior beyond that: state-changing and billable, no cost preview or published rate, 402 means insufficient credits, labels are additive and never overwritten, a dataset version snapshot is taken before every run, and billing settles at run time so stop does not refund.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded with the core action and reference formats before cost/lifecycle details. Every sentence carries load given the tool's complexity, though the single undivided paragraph is heavier than ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter billable mutation with no output schema, the description covers cost gating, billing timing, snapshot/undo path via dataset_version_restore, additive labelling semantics, and polling/cancellation siblings. An agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining that only explicitly set optional params are transmitted and the rest fall to server defaults, that class_mapping passes through with no length check, and that there is deliberately no imgsz parameter. These are semantics the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Start an auto-annotation run on a dataset") and enumerates the accepted reference formats for both dataset and model. It is clearly distinguished from siblings auto_annotate_status and auto_annotate_stop, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use and how-to-prepare: confirm_cost=true is mandatory, cost magnitude is gauged via datasets_get, class_mapping is the remedy for taxonomy mismatch, and status/stop are named for polling and cancellation. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools