ChatSpatial

annotate_cell_types

Destructive

Annotate cell types in spatial transcriptomics data.

Instructions

Annotate cell types in spatial transcriptomics data.

Args:
    data_id: Dataset ID
    params: Annotation parameters (method, reference_data_id, cell_type_key, etc.)

Note: Reference methods (tangram, scanvi) require reference_data_id to be preprocessed first.
Rule-based methods: marker_score labels the groups of cluster_label (e.g. spatial
domains) by mean log-normalized marker expression; threshold labels observations
by a cutoff on a numeric obs column (e.g. deconvolution_rctd_<cell type>).
Both write to output_key.

Input Schema

Name	Required	Description	Default
`params`	No
`data_id`	Yes

Output Schema

Name	Required	Description
`counts`	Yes
`method`	Yes
`data_id`	Yes
`warnings`	No	Non-fatal conditions that may affect result interpretation.
`cell_types`	Yes
`output_key`	Yes
`group_labels`	No	marker_score: label given to each group of cluster_label.
`group_scores`	No	marker_score: score of each group for each label.
`markers_used`	No	marker_score: marker genes found in the data for each label.
`confidence_key`	No
`confidence_scores`	No
`tangram_mapping_score`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv1.6.0Oct 22, 2026

addedInput schema / $defs / AnnotationParameters / properties / cluster_label / description

Added value: +"Categorical obs column with cluster or domain labels (e.g. 'spatial_domains_leiden'). Required for mllmcelltype and marker_score."

addedInput schema / $defs / AnnotationParameters / properties / marker_genes / description

Added value: +"Label -> marker genes. Required for cellassign and marker_score. For marker_score the order matters: labels are assigned in the given order."

addedInput schema / $defs / AnnotationParameters / properties / marker_score_exclusion

Added value: +{
+  "default": "rank_then_drop",
+  "description": "marker_score: handling of groups already given an earlier label. 'rank_then_drop': take the top marker_score_n_top groups by this label's score, then drop those already labeled (the label may get fewer groups). 'drop_then_rank': remove labeled groups first, then take the top groups of the rest.",
+  "enum": [
+    "rank_then_drop",
+    "drop_then_rank"
+  ],
+  "title": "Marker Score Exclusion",
+  "type": "string"
+}

addedInput schema / $defs / AnnotationParameters / properties / marker_score_n_top

Added value: +{
+  "default": 2,
+  "description": "marker_score: number of top-scoring groups assigned to each label.",
+  "maximum": 50,
+  "minimum": 1,
+  "title": "Marker Score N Top",
+  "type": "integer"
+}

addedInput schema / $defs / AnnotationParameters / properties / marker_score_unassigned_label

Added value: +{
+  "default": "Other",
+  "description": "marker_score: label for groups that no label claims.",
+  "minLength": 1,
+  "title": "Marker Score Unassigned Label",
+  "type": "string"
+}

changedInput schema / $defs / AnnotationParameters / properties / method / description

Previous value: -"tangram/scanvi: require reference_data_id. cellassign: requires marker_genes. singler: uses celldex reference."New value: +"tangram/scanvi: require reference_data_id. cellassign: requires marker_genes. singler: uses celldex reference. marker_score: labels the groups of cluster_label (e.g. spatial domains) by marker_genes scores. threshold: labels observations by a cutoff on a numeric obs column (e.g. a deconvolved proportion)."

changedInput schema / $defs / AnnotationParameters / properties / method / enum

Previous value: -[
-  "tangram",
-  "scanvi",
-  "cellassign",
-  "mllmcelltype",
-  "sctype",
-  "singler"
-]New value: +[
+  "tangram",
+  "scanvi",
+  "cellassign",
+  "mllmcelltype",
+  "sctype",
+  "singler",
+  "marker_score",
+  "threshold"
+]

addedInput schema / $defs / AnnotationParameters / properties / output_key

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "marker_score/threshold: obs column that receives the labels. Default: cell_type_marker_score or cell_type_threshold.",
+  "title": "Output Key"
+}

addedInput schema / $defs / AnnotationParameters / properties / threshold_comparison

Added value: +{
+  "default": ">=",
+  "description": "threshold: an observation passes when <value> <comparison> threshold_value.",
+  "enum": [
+    ">=",
+    ">",
+    "<=",
+    "<"
+  ],
+  "title": "Threshold Comparison",
+  "type": "string"
+}

addedInput schema / $defs / AnnotationParameters / properties / threshold_fail_label

Added value: +{
+  "default": "fail",
+  "description": "threshold: label for observations that fail the comparison.",
+  "minLength": 1,
+  "title": "Threshold Fail Label",
+  "type": "string"
+}

addedInput schema / $defs / AnnotationParameters / properties / threshold_key

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "threshold: numeric obs column to compare with threshold_value. deconvolve_data writes one proportion column per cell type, named deconvolution_<method>_<cell type>.",
+  "title": "Threshold Key"
+}

addedInput schema / $defs / AnnotationParameters / properties / threshold_pass_label

Added value: +{
+  "default": "pass",
+  "description": "threshold: label for observations that pass the comparison.",
+  "minLength": 1,
+  "title": "Threshold Pass Label",
+  "type": "string"
+}

addedInput schema / $defs / AnnotationParameters / properties / threshold_value

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "threshold: cutoff compared with threshold_key. Required for threshold.",
+  "title": "Threshold Value"
+}

addedOutput schema / properties / group_labels

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "marker_score: label given to each group of cluster_label.",
+  "title": "Group Labels"
+}

addedOutput schema / properties / group_scores

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "additionalProperties": {
+          "type": "number"
+        },
+        "type": "object"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "marker_score: score of each group for each label.",
+  "title": "Group Scores"
+}

addedOutput schema / properties / markers_used

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "marker_score: marker genes found in the data for each label.",
+  "title": "Markers Used"
+}

Changed4 schema fields changedv1.3.2Aug 10, 2026

addedInput schema / $defs / AnnotationParameters / additionalProperties
```
Added value: +false
```
addedInput schema / additionalProperties
```
Added value: +false
```
addedOutput schema / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / warnings

Added value: +{
+  "description": "Non-fatal conditions that may affect result interpretation.",
+  "items": {
+    "type": "string"
+  },
+  "title": "Warnings",
+  "type": "array"
+}

Changed2 schema fields changedv1.2.10May 21, 2026

addedInput schema / $defs / AnnotationParameters / properties / sctype_allow_remote

Added value: +{
+  "default": false,
+  "description": "Allow scType to load remote R scripts and the default remote marker database for this call.",
+  "title": "Sctype Allow Remote",
+  "type": "boolean"
+}

addedInput schema / $defs / AnnotationParameters / properties / sctype_allow_runtime_r_install

Added value: +{
+  "default": false,
+  "description": "Allow scType to install missing R packages at runtime for this call.",
+  "title": "Sctype Allow Runtime R Install",
+  "type": "boolean"
+}

First observedv1.2.7May 11, 2026

TDQS

A3.8/5.0

Behavior3/5

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

The description adds meaningful behavioral context: rule-based methods write labels to output_key, reference methods require preprocessed reference data, and marker_score assigns labels in order. However, it does not warn about overwriting existing obs columns or discuss computational cost, even though annotations mark the tool destructive and open-world.

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?

The description is front-loaded with the purpose and then structured into Args and a Note. It is dense but efficient; a few details such as the full method list are left to the schema rather than repeated.

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

Completeness4/5

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

For a complex annotation tool with an output schema and destructive annotations, the description covers the main method families, prerequisites, and output-key behavior. It is not fully complete because it omits overwrite warnings and does not explain every method family, but the schema covers many parameter-level details.

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?

Although the top-level schema lists only data_id and params, the description adds real meaning beyond the schema by summarizing method categories, required reference_data_id, cell_type_key, marker_score/threshold behavior, and output_key. Many nested parameters are left to schema descriptions, but the key decision parameters are explained.

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

Purpose4/5

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

The description states a specific verb and resource: annotate cell types in spatial transcriptomics data. It is clear what the tool does, but it does not explicitly distinguish it from related siblings such as deconvolve_data or identify_spatial_domains.

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

Usage Guidelines4/5

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

It gives useful usage guidance by explaining that reference-based methods tangram and scanvi require reference_data_id to be preprocessed first, and by explaining marker_score versus threshold behavior. It still does not explicitly state when to choose this tool over sibling annotation or domain-identification tools.

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