MCP GeneLab Server

Overview Schema Source Related Servers Discussions Admin

find_differentially_expressed_genes

Read-onlyIdempotent

Identify top up- and down-regulated genes for a given GeneLab assay using log2 fold change and adjusted p-value thresholds, returning ranked genes with means and standard deviations.

Instructions

USE THIS TOOL (not the query tool) for any "up/down-regulated genes", "DEGs", or "differential expression" question for a single assay.

The query tool can express the same Cypher, but using it for this category loses the formatted markdown tables, the inline CSV side-channel, the proper adj_p_value handling, and the parallel execution of the count queries this tool already provides correctly.

Return the top-N up- and down-regulated genes for a given assay_id.

This tool runs two queries on the GeneLab KG:

Top-N upregulated genes (log2fc > 0, adj_p_value <= adj_p_threshold, highest log2fc first)
Top-N downregulated genes (log2fc < 0, adj_p_value <= adj_p_threshold, lowest log2fc first)

Returning all passing rows: Pass top_n=None to return ALL rows that pass the filters rather than a top-N ranking. Use this when the user asks for "all significantly up/downregulated genes" or wants the complete filtered set as CSV.

Results include gene symbol, gene name, log2 fold change, adjusted p-value, and group means and standard deviations for each condition.

Input Schema

Name	Required	Description
`top_n`	No	How many genes to display for each of up- and down-regulated lists. Pass None (or omit) to return ALL genes passing the adj_p_value filter rather than a top-N — useful when the user asks for 'all significantly upregulated genes' or wants the complete filtered set as CSV. When the full set is large, the CSV contains every row passing the filter.
`assay_id`	Yes	Assay identifier (e.g., 'OSD-253-6c5f9f37b9cb2ebeb2743875af4bdc86')
`session_id`	No	Session id returned by `create_session()`. This server serves many users from one process; the session id is what keeps your output directory and generated plots private to you. Pass the SAME value on every tool call. If the server replies that the session is unknown or expired, call `create_session()` again and use the new id.
`adj_p_threshold`	No	Adjusted p-value threshold for significance (default: 0.05). Only genes with adj_p_value <= this value are returned.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv1.0.0Oct 16, 2026

addedInput schema / properties / adj_p_threshold

Added value: +{
+  "default": 0.05,
+  "description": "Adjusted p-value threshold for significance (default: 0.05). Only genes with adj_p_value <= this value are returned.",
+  "title": "Adj P Threshold",
+  "type": "number"
+}

addedInput schema / properties / session_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Session id returned by `create_session()`. This server serves many users from one process; the session id is what keeps your output directory and generated plots private to you. Pass the SAME value on every tool call. If the server replies that the session is unknown or expired, call `create_session()` again and use the new id.",
+  "title": "Session Id"
+}

addedInput schema / properties / top_n / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / top_n / default
```
Previous value: -5New value: +10
```

changedInput schema / properties / top_n / description

Previous value: -"How many genes to return for each of up- and down-regulated lists"New value: +"How many genes to display for each of up- and down-regulated lists. Pass None (or omit) to return ALL genes passing the adj_p_value filter rather than a top-N — useful when the user asks for 'all significantly upregulated genes' or wants the complete filtered set as CSV. When the full set is large, the CSV contains every row passing the filter."

removedInput schema / properties / top_n / type
```
Removed value: -"integer"
```

changedOutput schema / (root)

Previous value: -{
-  "$defs": {
-    "Annotations": {
-      "additionalProperties": true,
-      "properties": {
-        "audience": {
-          "anyOf": [
-            {
-              "items": {
-                "enum": [
-                  "user",
-                  "assistant"
-                ],
-                "type": "string"
-              },
-              "type": "array"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Audience"
-        },
-        "priority": {
-          "anyOf": [
-            {
-              "maximum": 1,
-              "minimum": 0,
-              "type": "number"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Priority"
-        }
-      },
-      "title": "Annotations",
-      "type": "object"
-    },
-    "TextContent": {
-      "additionalProperties": true,
-      "description": "Text content for a message.",
-      "properties": {
-        "_meta": {
-          "anyOf": [
-            {
-              "additionalProperties": true,
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Meta"
-        },
-        "annotations": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/Annotations"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null
-        },
-        "text": {
-          "title": "Text",
-          "type": "string"
-        },
-        "type": {
-          "const": "text",
-          "title": "Type",
-          "type": "string"
-        }
-      },
-      "required": [
-        "type",
-        "text"
-      ],
-      "title": "TextContent",
-      "type": "object"
-    }
-  },
-  "properties": {
-    "result": {
-      "items": {
-        "$ref": "#/$defs/TextContent"
-      },
-      "title": "Result",
-      "type": "array"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "find_differentially_expressed_genesOutput",
-  "type": "object"
-}New value: +null

First observedv0.4.0May 29, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the two-query execution model, the filter conditions (log2fc sign, adj_p_value), the retained markdown/CSV side-channel, and the returned columns. It stops short of describing pagination or size limits on large result sets.

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 routing decision in the first sentence and then describes behavior in short, scannable blocks. Slightly verbose in the 'Returning all passing rows' section, which partly restates the schema's top_n description, but no sentence is truly wasted.

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 a read-only analysis tool with no output schema, the description fully covers invocation intent, filter semantics, the top_n=None alternative, and the returned fields, so an agent has everything needed to call 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 nonetheless adds real meaning: it explains the top_n=None bypass (return ALL passing rows), the filter semantics that the ranking applies, and the full column set returned, going beyond the schema's per-field text.

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 ('Return the top-N up- and down-regulated genes for a given assay_id') and explicitly scopes to a single assay, distinguishing it from siblings like find_common_differentially_expressed_genes and the generic query tool.

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?

Explicitly routes the agent: 'USE THIS TOOL (not the `query` tool)' for up/down-regulated genes, DEGs, or differential expression questions, and names the exact condition ('all significantly up/downregulated genes') under which top_n=None should be used instead of a ranked list.

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

find_differentially_expressed_genes

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools