Skip to main content
Glama
sbl-sdsc

MCP GeneLab Server

by sbl-sdsc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

find_differentially_abundant_organisms

Read-onlyIdempotent

Find increased and decreased differentially abundant organisms for a single GeneLab assay, using DESeq2/ANCOM-BC significance filters and log2fc ranking.

Instructions

USE THIS TOOL (not the query tool) for any "differentially abundant organisms", DESeq2/ANCOM-BC abundance, or "increased/decreased abundance" 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 method-aware significance filtering (DESeq2 adj_p_value vs. ANCOM-BC q_value), and the safe lnfc handling that avoids silently dropping DESeq2 rows (where lnfc IS NULL would fail a naive lnfc > 0 filter).

Return the top-N organisms with increased and decreased differential abundance for a given assay_id.

Direction (increase vs. decrease) and ranking use log2fc, which is populated for BOTH DESeq2 and ANCOM-BC abundance edges in the GeneLab KG. log2fc is therefore used as the universal direction/ordering field and as the default magnitude filter.

The lnfc property is only populated for ANCOM-BC edges (DESeq2 leaves it null). It is returned in the result for reference and can be used as an additional magnitude filter via the lnfc_threshold parameter. log2fc is the direction filter because it is populated for both DESeq2 and ANCOM-BC rows; using lnfc for direction would null-filter every DESeq2 row out of the result.

Significance filtering is method-aware:

  • DESeq2 edges populate adj_p_value (not q_value); the adj_p_threshold applies.

  • ANCOM-BC edges populate q_value (not adj_p_value); the q_value_threshold applies. Each row is kept if its populated significance field meets the matching threshold.

Magnitude filtering:

  • log2fc_threshold (default 0.0) applies to every row, since log2fc is populated for both methods.

  • lnfc_threshold (default None = no filter) is method-aware: when set, it requires |lnfc| >= lnfc_threshold on rows where lnfc is populated. Rows where lnfc is null (i.e., DESeq2 rows) are not affected by this filter. Set lnfc_threshold to a positive number to add an ANCOM-BC-specific magnitude filter on top of log2fc.

This tool runs two queries on the GeneLab KG:

  1. Top-N organisms with increased abundance (log2fc > log2fc_threshold, significance and optional lnfc filters met, highest log2fc first)

  2. Top-N organisms with decreased abundance (log2fc < -log2fc_threshold, significance and optional lnfc filters met, lowest log2fc first)

Results include organism name, log2fc, lnfc, q-value, adj-p-value, and group means and standard deviations.

Input Schema

NameRequiredDescriptionDefault
top_nNoHow many organisms to display for each of increased and decreased abundance lists. Pass None (or omit) to return ALL organisms passing the magnitude + significance filters rather than a top-N — useful when the user asks for 'all significantly increased organisms' or wants the complete filtered set as CSV. When the full set is large, the CSV contains every row passing the filter.
assay_idYesAssay identifier (e.g., 'OSD-253-6c5f9f37b9cb2ebeb2743875af4bdc86')
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.
lnfc_thresholdNoOptional minimum |lnfc| magnitude. Only applied to rows with lnfc populated (ANCOM-BC). DESeq2 rows are not filtered by this parameter. Leave unset (None) to skip lnfc filtering entirely.
adj_p_thresholdNoAdjusted p-value threshold for DESeq2 abundance assays (default: 0.05). Applied to rows with adj_p_value populated.
log2fc_thresholdNoMinimum |log2fc| magnitude required for a row to be kept (default: 0.0 = any change). Applies to BOTH DESeq2 and ANCOM-BC rows since log2fc is populated for both methods.
q_value_thresholdNoq-value threshold for ANCOM-BC abundance assays (default: 0.05). Applied to rows with q_value populated.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare readOnlyHint/idempotentHint, but the description goes far beyond them: it discloses the method-aware significance branch (adj_p_value for DESeq2 vs q_value for ANCOM-BC), the lnfc-null population difference, the failure mode a naive `lnfc > 0` filter would cause, and that two separate queries are executed for the increase/decrease lists. This is exactly the kind of behavioral context annotations cannot carry.

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-loaded with the routing directive, then organized into clear sections (return shape, direction field, significance filtering, magnitude filtering, query mechanics). The universality of log2fc is explained more than once across paragraphs, which is mild redundancy given the tool's genuine complexity.

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?

Though there is no output schema, the description enumerates returned fields (organism name, log2fc, lnfc, q-value, adj-p-value, group means/SDs) and fully explains the filtering pipeline an agent needs to predict results. Nothing material for correct invocation 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 coverage is already 100%, but the description adds a real conceptual model: why log2fc (not lnfc) is the universal direction field, why lnfc_threshold is method-aware and cannot affect DESeq2 rows, and how the two significance thresholds map to their respective methods. Only session_id and top_n are left entirely to the schema, which is a minor gap against an otherwise strong semantic explanation.

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 organisms with increased and decreased differential abundance for a given assay_id') and explicitly names the sibling it is not ('USE THIS TOOL (not the `query` tool)'). The scope qualifier 'for a single assay' further separates it from the find_common_* siblings. An agent can select it 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?

Gives an explicit when (any differentially-abundant-organisms, DESeq2/ANCOM-BC abundance, or increased/decreased question for a single assay) and an explicit when-not (the `query` tool), plus the concrete cost of choosing wrong (loss of markdown tables, CSV side-channel, method-aware filtering, safe lnfc handling). 'For a single assay' also implicitly routes away from the common-across-assays sibling.

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