ChatSpatial

identify_spatial_domains

Destructive

Identify spatial domains and tissue architecture.

Instructions

Identify spatial domains and tissue architecture.

Args:
    data_id: Dataset ID
    params: Spatial domain parameters (method, n_domains, resolution, etc.)

Input Schema

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

Output Schema

Name	Required	Description
`method`	Yes
`data_id`	Yes
`warnings`	No	Non-fatal conditions that may affect result interpretation.
`n_domains`	Yes
`domain_key`	Yes
`domain_counts`	Yes
`embeddings_key`	No
`refined_domain_key`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed28 schema fields changedv1.5.10Oct 12, 2026

changedInput schema / $defs / SpatialDomainParameters / properties / cluster_n_neighbors / anyOf

Previous value: -[
-  {
-    "exclusiveMinimum": 0,
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "maximum": 200,
+    "minimum": 2,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / $defs / SpatialDomainParameters / properties / cluster_n_neighbors / description

Previous value: -"Neighbors for clustering (leiden/louvain)."New value: +"k of the expression k-NN graph (leiden/louvain only). None reuses an existing neighbour graph (e.g. from compute_embeddings) or builds one with k=15; a value rebuilds the graph unless the stored one already has this k."

changedInput schema / $defs / SpatialDomainParameters / properties / cluster_spatial_weight / description

Previous value: -"Spatial information weight (leiden/louvain)."New value: +"Weight of the spatial graph when combined with the expression graph (leiden/louvain only). None uses 0.3."

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_clustering_method / description

Added value: +"Clustering of GraphST embeddings (graphst only). 'mclust' fits a Gaussian mixture with the cluster count; 'leiden'/'louvain' search the resolution that yields the cluster count. 'louvain' requires the louvain package."

changedInput schema / $defs / SpatialDomainParameters / properties / graphst_n_clusters / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "exclusiveMinimum": 0,
+    "maximum": 50,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_n_clusters / description
```
Added value: +"Cluster count for GraphST (graphst only). None uses n_domains."
```

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_radius / description

Added value: +"Number of nearest spots in GraphST's refinement vote; a count, not a distance, so it does not depend on coordinate units. Used only when graphst_refinement=True (graphst only)."

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_radius / maximum
```
Added value: +500
```
addedInput schema / $defs / SpatialDomainParameters / properties / graphst_radius / minimum
```
Added value: +1
```

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_random_seed / description

Added value: +"Seed for GraphST training and clustering (graphst only); identical calls give identical domains."

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_random_seed / minimum
```
Added value: +0
```

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_refinement / description

Added value: +"Apply GraphST's own label refinement (majority vote over the graphst_radius nearest spots) after clustering (graphst only)."

addedInput schema / $defs / SpatialDomainParameters / properties / graphst_use_gpu / description
```
Added value: +"Use CUDA/MPS when available, else CPU (graphst only)."
```

changedInput schema / $defs / SpatialDomainParameters / properties / n_domains / description

Previous value: -"Number of spatial domains to identify."New value: +"Number of spatial domains to identify. Used by spagcn, stagate, graphst (unless graphst_n_clusters is set) and aestetik with kmeans/bgm. Ignored by leiden, louvain and banksy, which are controlled by a resolution."

addedInput schema / $defs / SpatialDomainParameters / properties / refine_domains / description

Added value: +"Post-process the labels of any method by relabelling a spot to the majority label of its 10 nearest spots when the share of differing neighbours reaches refinement_threshold. Stored as an extra '<domain_key>_refined' column."

changedInput schema / $defs / SpatialDomainParameters / properties / refinement_threshold / description

Previous value: -"Neighbor agreement threshold for domain refinement."New value: +"Share of the 10 nearest spots that must carry a different label before refine_domains relabels a spot. Used only when refine_domains=True."

addedInput schema / $defs / SpatialDomainParameters / properties / resolution / description

Added value: +"Clustering resolution (higher = more domains). Used by leiden, louvain and aestetik with leiden/louvain. Not used by graphst, which searches the resolution that yields n_domains, or by banksy (see banksy_cluster_resolution)."

addedInput schema / $defs / SpatialDomainParameters / properties / resolution / exclusiveMinimum
```
Added value: +0
```
addedInput schema / $defs / SpatialDomainParameters / properties / resolution / maximum
```
Added value: +5
```

addedInput schema / $defs / SpatialDomainParameters / properties / spagcn_compat

Added value: +{
+  "default": "spagcn-1.2.7",
+  "description": "SpaGCN model behavior. 'spagcn-1.2.7' reproduces the published SpaGCN 1.2.7 results (fixed cluster centers, Louvain initialization). 'modern' trains the cluster centers with the DEC Student's t kernel; the default hyperparameters were tuned for 1.2.7 and give different domains.",
+  "enum": [
+    "spagcn-1.2.7",
+    "modern"
+  ],
+  "title": "Spagcn Compat",
+  "type": "string"
+}

changedInput schema / $defs / SpatialDomainParameters / properties / stagate_rad_cutoff / anyOf

Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "exclusiveMinimum": 0,
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / SpatialDomainParameters / properties / stagate_rad_cutoff / description

Added value: +"Radius of the STAGATE spatial graph, as a distance in the units of obsm['spatial'] (stagate only). None derives it from the spot spacing (3**0.25 x the median distance to the 6th nearest spot), which links about 6 neighbours per Visium spot as in STAGATE's Visium analyses, in array, pixel or micron coordinates alike."

changedInput schema / $defs / SpatialDomainParameters / properties / stagate_random_seed / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / SpatialDomainParameters / properties / stagate_random_seed / description
```
Added value: +"Seed for STAGATE training and its GMM clustering (stagate only). None uses 42."
```
addedInput schema / $defs / SpatialDomainParameters / properties / stagate_use_gpu / description
```
Added value: +"Use CUDA/MPS when available, else CPU (stagate only)."
```

changedInput schema / $defs / SpatialDomainParameters / properties / timeout / anyOf

Previous value: -[
-  {
-    "exclusiveMinimum": 0,
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "exclusiveMinimum": 0,
+    "maximum": 86400,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / $defs / SpatialDomainParameters / properties / timeout / description

Previous value: -"Maximum backend runtime in seconds. None uses 600 seconds."New value: +"Maximum backend runtime in seconds (all methods except leiden/louvain, which run in-process). None uses 3600 seconds for stagate and graphst (neural network training) and 600 seconds otherwise."

addedInput schema / $defs / SpatialDomainParameters / properties / use_highly_variable / description

Added value: +"Restrict the input to adata.var['highly_variable'] genes when that column exists (all methods)."

Changed17 schema fields changedv1.3.2Aug 10, 2026

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

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_clustering_method

Added value: +{
+  "default": "kmeans",
+  "description": "Clustering applied to AESTETIK embeddings. 'kmeans'/'bgm' use n_domains; 'leiden'/'louvain' use resolution.",
+  "enum": [
+    "bgm",
+    "kmeans",
+    "louvain",
+    "leiden"
+  ],
+  "title": "Aestetik Clustering Method",
+  "type": "string"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_latent_dim

Added value: +{
+  "default": 16,
+  "description": "AESTETIK latent embedding dimension.",
+  "exclusiveMinimum": 0,
+  "maximum": 512,
+  "title": "Aestetik Latent Dim",
+  "type": "integer"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_max_epochs

Added value: +{
+  "default": 100,
+  "description": "AESTETIK training epochs.",
+  "exclusiveMinimum": 0,
+  "maximum": 10000,
+  "title": "Aestetik Max Epochs",
+  "type": "integer"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_morphology_key

Added value: +{
+  "default": "X_pca_morphology",
+  "description": "obsm key holding the precomputed per-spot morphology embedding (AESTETIK only).",
+  "title": "Aestetik Morphology Key",
+  "type": "string"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_morphology_weight

Added value: +{
+  "default": 1.5,
+  "description": "Morphology weight in the AESTETIK joint loss.",
+  "maximum": 3,
+  "minimum": 0,
+  "title": "Aestetik Morphology Weight",
+  "type": "number"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_random_seed

Added value: +{
+  "default": 2023,
+  "title": "Aestetik Random Seed",
+  "type": "integer"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_transcriptomics_key

Added value: +{
+  "default": "X_pca",
+  "description": "obsm key holding the precomputed expression embedding (AESTETIK only).",
+  "title": "Aestetik Transcriptomics Key",
+  "type": "string"
+}

addedInput schema / $defs / SpatialDomainParameters / properties / aestetik_window_size

Added value: +{
+  "default": 3,
+  "description": "Odd side length of the AESTETIK neighborhood grid.",
+  "exclusiveMinimum": 0,
+  "maximum": 15,
+  "title": "Aestetik Window Size",
+  "type": "integer"
+}

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

Previous value: -"'spagcn' uses histology. 'banksy' uses spatial feature augmentation. 'stagate'/'graphst' use deep learning."New value: +"'spagcn' uses histology. 'banksy' uses spatial feature augmentation. 'stagate'/'graphst' use deep learning. 'aestetik' fuses precomputed expression and morphology embeddings."

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

Previous value: -[
-  "spagcn",
-  "leiden",
-  "louvain",
-  "stagate",
-  "graphst",
-  "banksy"
-]New value: +[
+  "spagcn",
+  "leiden",
+  "louvain",
+  "stagate",
+  "graphst",
+  "banksy",
+  "aestetik"
+]

changedInput schema / $defs / SpatialDomainParameters / properties / timeout / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "exclusiveMinimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / SpatialDomainParameters / properties / timeout / description
```
Added value: +"Maximum backend runtime in seconds. None uses 600 seconds."
```
addedInput schema / additionalProperties
```
Added value: +false
```
addedOutput schema / additionalProperties
```
Added value: +false
```

removedOutput schema / properties / statistics

Removed value: -{
-  "additionalProperties": true,
-  "title": "Statistics",
-  "type": "object"
-}

addedOutput schema / properties / warnings

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

First observedv1.2.7May 11, 2026

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds nothing behavioral: it does not say the tool writes domain labels back into the dataset, does not warn that some methods train neural networks (long runtime, GPU), and does not mention seed/reproducibility semantics. No contradiction, but negligible added value.

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?

Front-loads the purpose sentence, then a compact Args block with no filler. Well-sized, though the Args block is arguably redundant with the rich nested schema.

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

Completeness3/5

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

For a highly complex tool (30+ nested parameters, multiple methods, GPU training) the description is thin, but the nested schema is exhaustively documented and an output schema exists, so the biggest gaps are usage context and behavioral disclosure rather than parameter knowledge.

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

Parameters3/5

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

Top-level schema description coverage is 0%, but the nested SpatialDomainParameters def documents every field in detail. The description names the key knobs (method, n_domains, resolution), giving a useful entry point, though it does not explain that method selection changes which of those knobs matter.

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?

States a specific verb+resource: 'Identify spatial domains and tissue architecture.' This clearly distinguishes it from sibling analysis tools like find_spatial_genes or analyze_spatial_statistics. It stops short of naming any sibling explicitly, so no differentiation credit beyond the resource name.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no mention of prerequisites (e.g. data must be loaded/preprocessed, histology requirements for spagcn), and no comparison to alternative spatial tools. The Args block only restates the two top-level parameters.

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