Skip to main content
Glama
sbl-sdsc

MCP GeneLab Server

by sbl-sdsc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

find_common_de_genes_overlapping_dm_regions

Read-onlyIdempotent

Find differentially expressed genes overlapping differentially methylated regions, categorized by up/down and hyper/hypo direction, with promoter methylation filtering for silencing analysis.

Instructions

USE THIS TOOL (not the query tool) for any "expression-methylation coupling", "classical epigenetic silencing", "DE genes that are also DM", "downregulated genes with promoter hypermethylation", or any cross-type intersection between differential expression and differential methylation. Falling back to query for this category reproduces the four-quadrant intersection logic this tool already does correctly (parallel DE+DM fetches across DIFFERENT assays, pooled-methylation aggregation when multiple methylation assays are passed as a list, MethylationRegion location filtering on the DM side, up_hyper/up_hypo/down_hyper/down_hypo direction categorization) and loses the four-quadrant markdown summary and the inline combined CSV.

Find differentially expressed genes that overlap with differentially methylated regions.

This cross-analysis tool:

  1. Gets DE genes from the expression assay (filtered by log2fc and adj_p thresholds)

  2. Gets genes associated with DM regions from the methylation assay(s) (filtered by methylation_diff, q_value, and any MethylationRegion location filters: in_promoter, in_exon, in_intron, dist_to_feature_max). If methylation_assay_id is a list, the methylation evidence is POOLED across the listed assays before the intersection — a gene is treated as hypermethylated if it passes the threshold in ANY of the pooled assays.

  3. Finds the intersection (genes that are BOTH differentially expressed AND differentially methylated)

  4. Reports the overlap categorized by direction (up+hyper, up+hypo, down+hyper, down+hypo)

For the classical epigenetic-silencing question — promoter hypermethylation reducing expression — pass in_promoter=True. When a study has replicate methylation assays (e.g. OSD-48 has two methylKit assays for the same Space Flight vs. Ground Control comparison), pass them as a list to capture the combined methylation evidence on the methylation side of the intersection.

Input Schema

NameRequiredDescriptionDefault
in_exonNoMethylationRegion location filter (True / False / None). See in_promoter.
in_intronNoMethylationRegion location filter (True / False / None). See in_promoter.
session_idNoSession 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.
in_promoterNoMethylationRegion location filter applied to the DM side of the overlap. When True, only DM regions overlapping a promoter contribute to the methylated-gene set. Use this for classical epigenetic-silencing questions: 'which downregulated genes have hypermethylation in their promoter?' → pass in_promoter=True.
adj_p_thresholdNoAdjusted p-value threshold for DE genes (default: 0.05)
log2fc_thresholdNoLog2 fold change threshold for DE genes (default: 1.0)
q_value_thresholdNoq-value threshold for DM regions (default: 0.05)
dist_to_feature_maxNoMethylationRegion distance filter. When set, only DM regions with dist_to_feature <= this value (bp) contribute to the methylated-gene set. None (default) imposes no distance filter.
expression_assay_idYesAssay identifier for differential expression data
methylation_assay_idYesAssay identifier for differential methylation data, or a list of identifiers to pool. Pass a single string to use one methylation assay (most common). Pass a list (e.g. ['OSD-48-968c...', 'OSD-48-4dc1...']) to pool methylation evidence across replicate methylation assays of the same comparison — a gene is treated as 'hypermethylated' if ANY of the pooled assays passes the threshold for it. This matches the natural reading of 'find DE genes that have hypermethylated promoter evidence in this study's methylation assays', where the methylation side is a union across assays before being intersected with the DE side.
methylation_diff_thresholdNoMethylation diff threshold for DM regions (default: 0.0)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), and the description adds real net-new behavior: pooled-methylation union semantics across a list of assays ('hypermethylated if it passes the threshold in ANY of the pooled assays') and the return artifacts (four-quadrant markdown summary and inline combined CSV). It does not cover failure behavior, empty-overlap handling, or result size, but the added disclosure goes meaningfully beyond the annotations.

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 routing instruction is front-loaded, which is the right priority. However, the opening parenthetical (pooling, MethylationRegion filtering, direction categorization, lost outputs) substantially duplicates the numbered step list that follows, so some sentences do not fully earn their place.

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 11-parameter cross-analysis tool with no output schema, the description covers inputs (DE/DM thresholds, location filters, pooling), the algorithm, edge cases (replicate assays, promoter silencing), and the return artifacts. An agent has everything needed to call it correctly and interpret results.

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 description coverage is 100%, so 3 is the baseline, but the description adds semantics the schema does not: it explains the union-across-assays semantics for a list-valued methylation_assay_id and gives a worked rationale for in_promoter=True. Thresholds and distance filters are left to the schema, which is reasonable.

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?

The description states a precise verb+resource: 'Find differentially expressed genes that overlap with differentially methylated regions', and then enumerates the four internal steps (DE fetch, DM fetch, intersection, direction categorization). This distinguishes it cleanly from sibling probes like find_differentially_expressed_genes and find_differentially_methylated_regions, which only handle one data type.

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 any expression-methylation coupling...' and names the alternative and what is lost by falling back (four-quadrant intersection logic, markdown summary, combined CSV). It also gives a concrete condition for the special case: pass in_promoter=True for the classical silencing question, and pass a list when a study has replicate methylation assays.

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