ChatSpatial

integrate_samples

Destructive

Integrate multiple spatial transcriptomics samples into a unified dataset.

Instructions

Integrate multiple spatial transcriptomics samples into a unified dataset.

Args:
    data_ids: List of dataset IDs to integrate
    params: Integration parameters (method, batch_key, n_pcs, etc.)

batch_correction=False pools the samples without correction (shared genes,
counts in layers['counts'], obs and coordinates kept), e.g. to pool sections
for analyze_cell_communication.

Input Schema

Name	Required	Description	Default
`params`	No
`data_ids`	Yes	Two or more distinct dataset IDs.

Output Schema

Name	Required	Description
`data_id`	Yes
`n_cells`	Yes
`n_genes`	No
`warnings`	No	Non-fatal conditions that may affect result interpretation.
`batch_key`	Yes
`n_samples`	Yes
`embedding_key`	No
`integration_method`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.6.0Oct 22, 2026

addedInput schema / $defs / IntegrationParameters / properties / batch_correction

Added value: +{
+  "default": true,
+  "description": "False: concatenate the samples without batch correction (method and n_pcs are ignored; inputs need not be preprocessed). Keeps the genes shared by all samples, their counts (layers['counts'], else X, else adata.raw) in layers['counts'], X = log1p of counts scaled to 10,000 per observation, every obs column and the spatial coordinates; batch_key holds the source dataset ID. Use it to pool sections, e.g. for cell communication.",
+  "title": "Batch Correction",
+  "type": "boolean"
+}

addedOutput schema / properties / n_genes

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "N Genes"
+}

Changed4 schema fields changedv1.5.3Aug 19, 2026

addedOutput schema / properties / batch_key

Added value: +{
+  "title": "Batch Key",
+  "type": "string"
+}

addedOutput schema / properties / embedding_key

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Embedding Key"
+}

addedOutput schema / properties / n_cells

Added value: +{
+  "minimum": 0,
+  "title": "N Cells",
+  "type": "integer"
+}

changedOutput schema / required

Previous value: -[
-  "data_id",
-  "n_samples",
-  "integration_method"
-]New value: +[
+  "data_id",
+  "n_samples",
+  "integration_method",
+  "n_cells",
+  "batch_key"
+]

Changed13 schema fields changedv1.3.2Aug 10, 2026
- addedInput schema / $defs / IntegrationParameters / additionalProperties
```
Added value: +false
```
- changedInput schema / $defs / IntegrationParameters / properties / n_epochs / anyOf
```
Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "exclusiveMinimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
```
- addedInput schema / $defs / IntegrationParameters / properties / scvi_dropout_rate / exclusiveMaximum
```
Added value: +1
```
- addedInput schema / $defs / IntegrationParameters / properties / scvi_dropout_rate / minimum
```
Added value: +0
```
- addedInput schema / $defs / IntegrationParameters / properties / scvi_n_hidden / exclusiveMinimum
```
Added value: +0
```
- addedInput schema / $defs / IntegrationParameters / properties / scvi_n_latent / exclusiveMinimum
```
Added value: +0
```
- addedInput schema / $defs / IntegrationParameters / properties / scvi_n_layers / exclusiveMinimum
```
Added value: +0
```
- addedInput schema / additionalProperties
```
Added value: +false
```
- addedInput schema / properties / data_ids / description
```
Added value: +"Two or more distinct dataset IDs."
```
- addedInput schema / properties / data_ids / minItems
```
Added value: +2
```
- addedOutput schema / additionalProperties
```
Added value: +false
```
- addedOutput schema / properties / n_samples / minimum
```
Added value: +2
```
- 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

B3.4/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioural detail for the batch_correction=False path (shared genes retained, counts into layers['counts'], X = log1p scaled to 10k, obs and coordinates preserved, batch_key holds source dataset ID). But the default integration path is behaviourally opaque, and the destructive side effects flagged by the annotations are never explained.

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

Conciseness3/5

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

The purpose is front-loaded in a single sentence and the Args block is terse. The final paragraph, however, restates the batch_correction=False schema description almost verbatim, so a large fraction of the description duplicates a structured field instead of adding new information.

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?

An output schema exists, so return values need not be explained, and the uncorrected pooling mode is covered thoroughly. What remains missing is the behaviour of the primary integration path, whether preprocessing is required before the default call, and what the destructive hint actually implies for existing datasets.

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?

Despite only 50% schema coverage, the description names the key knobs (method, batch_key, n_pcs) and explains the most consequential one, batch_correction, in operational terms rather than just its name. The nested IntegrationParameters object is largely self-documenting in the schema, so the description's contribution is proportionate rather than exhaustive.

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 opening sentence gives a specific verb plus resource ('Integrate multiple spatial transcriptomics samples into a unified dataset'), which is unambiguous and matches nothing else in the sibling list. It does not explicitly differentiate itself from near-neighbours such as register_spatial_data or preprocess_data, which is the only thing keeping it from a 5.

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

Usage Guidelines3/5

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

The description supplies one concrete usage scenario ('pool sections for analyze_cell_communication') for the batch_correction=False path, which is genuinely helpful routing. However, it gives no guidance on when to use the default corrected path, no prerequisites, and no statement of when this tool should be chosen over registering or preprocessing data instead.

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