Skip to main content
Glama
sbl-sdsc

MCP GeneLab Server

by sbl-sdsc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

find_common_differentially_abundant_organisms

Read-onlyIdempotent

Find common differentially abundant organisms across multiple assays, separating increased and decreased signals to reveal cross-method concordance.

Instructions

USE THIS TOOL (not the query tool) for any "common differentially abundant organisms across assays", "organisms increased in BOTH assays", "shared abundance signals across methods" (e.g. DESeq2 vs ANCOM-BC concordance), or any cross-assay abundance intersection question. Falling back to query for this category reproduces the per-assay fetch + inner-join logic this tool already does correctly (parallel fetches, method-aware significance filtering, lnfc handling that doesn't drop DESeq2 rows, separate increased vs. decreased intersections) and loses the formatted markdown + inline CSV side-channel and the assay-reference legend.

Find common differentially abundant organisms across multiple assays.

Useful for comparing results from different analysis methods (e.g., DESeq2 vs ANCOM-BC 1 vs ANCOM-BC 2) to identify organisms consistently detected as differentially abundant.

Direction (increase vs. decrease) and ranking use log2fc, which is populated for BOTH DESeq2 and ANCOM-BC edges in the GeneLab KG. log2fc is therefore the universal magnitude filter (log2fc_threshold); lnfc is ANCOM-BC-only and would null-filter every DESeq2 row if used for direction.

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.

This function:

  1. Takes a list of assay IDs as input (2 or more)

  2. Gets ALL organisms passing the magnitude and method-aware significance filters for each assay

  3. Inner joins among increased and among decreased abundance organisms

  4. Returns markdown tables showing common organisms and their log2fc values

Input Schema

NameRequiredDescriptionDefault
assay_idsYesList of assay identifiers for abundance comparisons (e.g., different methods like DESeq2, ANCOM-BC)
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 for filtering organisms (default: 0.0 = any change). Applied 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.7/5.0
Behavior5/5

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

Annotations only cover readOnly/idempotent/openWorld, so the description carries the rest and does so well: it discloses the internal algorithm (parallel fetches, method-aware significance filtering, separate increased/decreased intersections), the null-handling of lnfc that would drop DESeq2 rows, and the output artifacts (markdown tables, inline CSV side-channel, assay-reference legend).

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 with the routing guidance, which is good, but the first paragraph is a single dense run-on and several facts are stated twice (log2fc populated for both methods / universal magnitude filter; lnfc is ANCOM-BC-only). Roughly a third of the text could be cut without loss.

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?

Even without an output schema, the description describes the return shape (markdown tables of common organisms with log2fc, CSV side-channel, legend) and fully covers the filtering semantics an agent needs for a 6-parameter, cross-assay intersection tool.

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, but the description adds genuine meaning: it explains WHY log2fc_threshold is the universal magnitude filter and WHY lnfc_threshold is method-aware (using lnfc for direction would null-filter every DESeq2 row). That rationale is not inferable from the schema text alone.

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 and resource with explicit scope: 'common differentially abundant organisms across multiple assays', distinct from the per-assay `find_differentially_abundant_organisms` sibling. The description also names the anti-pattern tool (`query`) so an agent can separate the two without opening schemas.

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 says 'USE THIS TOOL (not the `query` tool)' and enumerates the triggering question phrasings ('common differentially abundant organisms across assays', 'increased in BOTH assays', 'shared abundance signals across methods'). It even explains the cost of the wrong choice (reproducing per-assay fetch + inner-join and losing the markdown/CSV output).

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