Skip to main content
Glama
sbl-sdsc

MCP GeneLab Server

by sbl-sdsc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

find_differentially_methylated_regions

Read-onlyIdempotent

Identify differentially methylated regions (hyper/hypo) from GeneLab assays. Pool replicates, filter by genomic location, and export complete CSV results.

Instructions

USE THIS TOOL (not the query tool) for any "hyper/hypo-methylated regions", "DMRs", or "differential methylation" question — including all-rows requests, promoter/exon/intron-filtered methylation queries, and pooling methylation across replicate assays. Falling back to query for this category reproduces the work this tool already does (proper IS-NOT-NULL guards, gene-symbol join, parallel count queries, location filtering, deterministic CSV emission) and loses the formatted markdown

  • inline CSV side-channel.

Return hyper- and hypo-methylated regions for one or more assays.

This tool runs two queries on the GeneLab KG:

  1. Hypermethylated regions (methylation_diff > methylation_diff_threshold, q_value <= q_value_threshold, highest first)

  2. Hypomethylated regions (methylation_diff < -methylation_diff_threshold, q_value <= q_value_threshold, lowest first)

Pooling across assays: Pass a list to assay_id to pool results across multiple methylation assays (the Cypher uses a.identifier IN $assay_ids). Common use case: a study has 2+ methylation assays representing replicate runs of the same comparison, and the user wants the combined evidence rather than per-assay tables. The output adds an assay_id column so each row's source is visible.

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 hypermethylated promoter regions" or wants the complete filtered set as CSV. To keep the response readable when the full set is large, the inline markdown table is capped at the first 100 rows and a note is shown; the CSV contains every row.

MethylationRegion location filters (in_promoter, in_exon, in_intron, dist_to_feature_max) are applied DURING the Cypher query. This means when a user asks for "top hypermethylated regions in the promoter", pass in_promoter=True and the tool will correctly rank within the promoter universe. Do NOT post-filter the unfiltered top-N — that produces wrong results because regions outside the filter (e.g. non-promoter regions) occupy slots in the unfiltered top-N and displace correctly-ranked filtered regions. Multiple filters combine with AND, so in_promoter=True with in_intron=False returns promoter regions that are not intronic.

WHEN TO USE THIS TOOL vs. direct Cypher via the query tool: Use THIS tool for any "hyper/hypo methylated regions" question, including pooled-across-assays, all-passing-rows, and filter-by-location variants. It produces formatted markdown tables AND an inline CSV that the user can save directly. Falling back to direct Cypher loses the formatted output and the CSV.

Input Schema

NameRequiredDescriptionDefault
top_nNoHow many regions to display for each of hyper- and hypo-methylated lists. Pass None (or omit) to return ALL rows passing the filters rather than a top-N — useful when the user asks for 'all hypermethylated promoter regions' or wants to download the complete filtered set as CSV. When the full set is large (>100 rows), the inline markdown table is capped at the first 100 rows for readability while the CSV contains every row.
in_exonNoMethylationRegion location filter. When True, return only regions overlapping an exon (mr.in_exon = true). When False, exclude exon-overlapping regions. None (default) imposes no exon filter. Combines with other filters via AND.
assay_idYesAssay identifier, or a list of assay identifiers to pool. Pass a single string (e.g. 'OSD-48-968c...') to query one assay. Pass a list (e.g. ['OSD-48-968c...', 'OSD-48-4dc1...']) to pool results across multiple methylation assays — useful when a study has independent replicate methylation assays with identical factor spaces and you want the combined evidence. The output table will have an additional 'assay_id' column so each row's source is identifiable, and the same region significantly methylated in two pooled assays will appear as two rows.
in_intronNoMethylationRegion location filter. When True, return only regions overlapping an intron (mr.in_intron = true). When False, exclude intron-overlapping regions. None (default) imposes no intron filter. Combines with other filters via AND.
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. When True, return only regions overlapping a gene promoter (mr.in_promoter = true). When False, exclude promoter-overlapping regions (mr.in_promoter = false). None (default) imposes no promoter filter. The filter is applied during the Cypher query, so 'top_n' and the 'showing N of TOTAL' count both reflect the filtered set — promoter-only top-N rankings are computed from the promoter-only universe, NOT post-filtered from the global top-N.
q_value_thresholdNoq-value threshold for significance (default: 0.05). Only regions with q_value <= this value are returned.
dist_to_feature_maxNoMethylationRegion distance filter. When set, return only regions whose dist_to_feature (bp to the nearest annotated gene feature) is <= this value. None (default) imposes no distance filter. Useful for narrowing to regions tightly associated with gene bodies.
methylation_diff_thresholdNoMinimum |methylation_diff| magnitude (in percentage points) required for a row to be kept (default: 0.0 = any change). Hypermethylated rows must have methylation_diff > methylation_diff_threshold; hypomethylated rows must have methylation_diff < -methylation_diff_threshold. The GeneLab KG stores methylation_diff as a raw percentage, so a threshold of 10 means '10 percentage points or more', matching typical methylKit reporting conventions.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare readOnly/idempotent/openWorld=false; the description goes well beyond them by disclosing that two ordered queries run (hyper descending, hypo ascending), that pooling adds an `assay_id` column and duplicates shared regions, that filters execute inside the Cypher rather than being post-applied, and that markdown is capped at 100 rows while CSV carries every row. This is unusually rich behavioral context.

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?

Front-loaded and well sectioned, but noticeably redundant: the 'use this tool, not `query`' instruction and the CSV/markdown benefit are stated in the opening paragraph and again in the closing 'WHEN TO USE' block, and the `top_n=None` semantics duplicate the schema description. Every sentence is relevant, but several repeat the same point.

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?

With no output schema and 9 parameters, the description carries the full burden and does so: it explains the return shape (formatted markdown plus inline CSV side-channel), the row addressing (assay_id column), and the truncation behavior. Nothing an agent needs to call or interpret this correctly is missing.

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 the baseline is 3, but the description adds meaning the schema does not carry on its own: the rationale for `top_n=None`, the warning that post-filtering an unfiltered top-N yields wrong rankings, and the note that multiple location filters combine with AND. It also restates some schema content (thresholds, pooling), which caps it at 4 rather than 5.

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 hyper- and hypo-methylated regions for one or more assays) and immediately positions itself against the sibling `query` tool. An agent can tell what it does and that it is the canonical entry point for DMR questions without opening the schema.

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 enumerates when to use it ('any hyper/hypo-methylated regions, DMRs, or differential methylation question — including all-rows requests, promoter/exon/intron-filtered queries, and pooling across replicate assays') and names the alternative (`query`) plus the cost of choosing it. Exclusions and trigger phrases are both present.

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