Metabolomics research — metabolite identification, study analysis, and database searches across HMDB, MetaboLights, Metabolomics Workbench, KEGG. Use for annotating mass-spec features to known metabolites, finding metabolomics studies of a disease, and structured metabolomics research reports with m

Metabolomics Research Comprehensive metabolomics research skill that identifies metabolites, analyzes studies, and searches metabolomics databases. Generates structured research reports with annotated metabolite information, study details, and database statistics. Use Case Use this skill when asked to: Identify or annotate metabolites (HMDB IDs, chemical properties, pathways) Retrieve metabolomics study information from MetaboLights or Metabolomics Workbench Search for metabolomics studies by keywords or disease Analyze metabolite profiles or datasets Generate comprehensive metabolomics research reports Example queries: "What is the HMDB ID and pathway information for glucose?" "Get study details for MTBLS1" "Find metabolomics studies related to diabetes" "Analyze these metabolites: glucose, lactate, pyruvate" Databases Covered Primary metabolite databases: HMDB (Human Metabolome Database): 220,000+ metabolites with structures, pathways, and biological roles MetaboLights : Public metabolomics repository with thousands of studies Metabolomics Workbench : NIH Common Fund metabolomics data repository FooDB : Food chemical constituent database — use FooDB get compound (param fdb id , e.g. "FDB000004" ) for a food compound's structure plus HMDB/KEGG/PubChem/ChEBI cross references; ideal for food metabolomics annotation PubChem : Chemical properties and bioactivity data (fallback) Research Workflow The skill executes a 4 phase analysis pipeline: Phase 1: Metabolite Identification & Annotation For each metabolite in the input list: 1. Search HMDB by metabolite name 2. Retrieve HMDB ID, chemical formula, molecular weight 3. Get detailed metabolite information (description, pathways) 4. Fallback to PubChem for CID and chemical properties if HMDB unavailable Phase 2: Study Details Retrieval For provided study IDs: 1. Detect database type (MTBLS = MetaboLights, ST = Metabolomics Workbench) 2. Retrieve study metadata (title, description, organism, status) 3. Extract experimental design and data availability Phase 3: Study Search For keyword searches: 1. Search MetaboLights studies by query term 2. Return matching study IDs with preview information 3. Report total number of results Phase 4: Database Overview Always included in reports: 1. Sample recent studies from MetaboLights 2. Database statistics and availability 3. Integration information for all databases Usage Patterns Pattern 1: Metabolite Identification Input: Metabolite list: ["glucose", "lactate", "pyruvate"] Output report includes: HMDB IDs for each metabolite Chemical formulas and molecular weights Biological pathways PubChem CIDs SMILES representations Pattern 2: Study Retrieval Input: Study ID: "MTBLS1" or "ST000001" Output report includes: Study title and description Organism information Study status and release date Data availability Pattern 3: Study Search Input: Search query: "diabetes" Optional organism filter Output report includes: Matching study IDs Study titles and previews Total result count Pattern 4: Comprehensive Analysis Input: Metabolite list: ["glucose", "pyruvate"] Study ID: "MTBLS1" Search query: "diabetes" Output report includes: All phases combined (identification, study details, search results, overview) Cross referenced information Complete metabolomics research summary Input Parameters metabolite list (optional) List of metabolite names to identify and annotate. Format : List of strings Examples : ["glucose"] , ["lactate", "pyruvate", "acetate"] Note : Common names accepted; HMDB will find standard identifiers study id (optional) MetaboLights or Metabolomics Workbench study identifier. Format : String starting with "MTBLS" or "ST" Examples : "MTBLS1" , "ST000001" Note : Database auto detected from prefix search query (optional) Keyword to search metabolomics studies. Format : String (disease, compound, organism, method) Examples : "diabetes" , "glucose metabolism" , "LC MS" organism (optional) Target organism for study filtering. Format : String (scientific name) Default : "Homo sapiens" Examples : "Mus musculus" , "Saccharomyces cerevisiae" output file (optional) Path for the generated markdown report. Format : String (filename with .md extension) Default : Auto generated timestamp based filename Examples : "my analysis.md" , "metabolomics report.md" Output Format All analyses generate a structured markdown report with: Header section: Report title and generation timestamp Input parameters summary (metabolites, study ID, search query, organism) Phase sections: Clear section headers ( 1. Metabolite Identification, 2. Study Details, etc.) Subsections for each metabolite or result Consistent formatting (bold labels, tables for results) Database overview: Available databases and statistics Recent studies sample Integration information Error handling: Graceful error messages for unavailable data Fallback strategies documented in output "N/A" for missing fields (not blank) Implementation Notes SOAP Tool Handling HMDB tools are SOAP based and require special parameter handling: HMDB search : Requires operation="search" parameter HMDB get metabolite : Requires operation="get metabolite" parameter Do not use endpoint or method parameters (not applicable to SOAP) Response Format Variations Tools return different response formats handle all three: 1. Standard format : {status: "success", data: [...], metadata: {...}} 2. Direct list : [...] (e.g., metabolights list studies) 3. Direct dict : {field1: ..., field2: ...} (e.g., some detail endpoints) Always check response type with isinstance() before accessing fields. Fallback Strategy Follow this hierarchy for robustness: 1. Primary source : Try main database first (HMDB for metabolites, MetaboLights for studies) 2. Fallback source : Use alternative database if primary fails (PubChem for chemical properties) 3. Default behavior : Show error message with context, continue with remaining phases Progressive Report Writing Write report incrementally to avoid memory issues: 1. Create output file early in pipeline 2. Append sections as each phase completes 3. Flush to disk regularly for long analyses 4. Return file path for user access Tool Discovery The skill automatically discovers and uses these tools from ToolUniverse: HMDB Tools: HMDB search : Search metabolites by name HMDB get metabolite : Get detailed metabolite information MetaboLights Tools: metabolights list studies : List available studies metabolights search studies : Search studies by keyword metabolights get study : Get study details by ID Metabolomics Workbench Tools: MetabolomicsWorkbench get study : Get study information MetabolomicsWorkbench search compound by name : Search compounds PubChem Tools: PubChem get CID by compound name : Get PubChem CID PubChem get compound properties by CID : Get chemical properties No manual tool configuration required all tools loaded automatically. Common Issues Issue: HMDB returns "Error querying HMDB: 0" Cause : HMDB search returned empty results or index error accessing first result Solution : This is expected for uncommon metabolites; PubChem fallback will be attempted Issue: Study details show "N/A" for all fields Cause : Study ID not found or API unavailable Solution : Verify study ID format (MTBLS or ST ), check if study is public Issue: Tool not found errors Cause : Missing API keys for some databases Solution : Check .env.template , add required API keys to .env file (most metabolomics tools work without keys) Issue: Large metabolite lists cause slow execution Cause : Pipeline queries each metabolite individually Solution : Reports limit to first 10 metabolites; consider batching for 20 metabolites Summary The Metabolomics Research skill provides comprehensive metabolomics analysis through a 4 phase pipeline that: 1. Identifies metabolites using HMDB (primary) and PubChem (fallback) databases 2. Retrieves study details from MetaboLights and Metabolomics Workbench repositories 3. Searches studies by keywords across metabolomics databases 4. Generates structured reports with all findings in readable markdown format Key Features: ✅ 100% test coverage with working pipeline ✅ Handles SOAP tools correctly (HMDB requires operation parameter) ✅ Implements fallback strategies (HMDB → PubChem) ✅ Graceful error handling (continues if one phase fails) ✅ Progressive report writing (memory efficient) ✅ Implementation agnostic documentation (works with Python SDK and MCP) Best for: Metabolite annotation and pathway analysis Study discovery and data retrieval Comprehensive metabolomics research reports Multi database metabolomics queries Reasoning Framework Starting Point: Mass Spectrum Analysis Metabolite identification starts with the mass spectrum. LOOK UP DON'T GUESS — always search HMDB/PubChem with the calculated neutral mass rather than guessing identity from m/z alone. Step 1 — Calculate neutral mass : Determine ionization mode. Positive: subtract adduct mass ([M+H]+ = 1.0073, [M+Na]+ = 22.9892, [M+NH4]+ = 18.0344). Negative: add back ([M H] = +1.0073, [M+Cl] = +34.9694, [M+HCOO] = +44.9977). Step 2 — Search databases : Query HMDB by mass (±5 ppm for Orbitrap/Q TOF, ±0.5 Da for unit resolution). Multiple adduct hypotheses yield different neutral masses — check all plausible adducts before concluding. Step 3 — Resolve ambiguity : Exact mass alone often matches 5 20 candidates. Use isotope pattern (M+1/M+2 ratios indicate element composition — e.g., high M+2 suggests S or Cl), retention time, and MS/MS fragmentation to narrow down. A single mass match is L3 confidence; MS/MS match to reference spectrum is required for L2/L1. Evidence Grading (Metabolite Identification Confidence) L1 Confirmed : HMDB ID + retention time + MS/MS match to reference standard L2 Probable : HMDB match by exact mass + MS/MS similarity (cosine 0.7), no standard L3 Tentative : Matched by exact mass and molecular formula only; structural isomers unresolved L4 Unknown : Detected m/z with no database match; PubChem fallback may provide candidates Interpretation Guidance Metabolite identification : HMDB IDs provide the strongest annotation when paired with experimental validation. A PubChem only match (fallback) indicates the metabolite is chemically characterized but may lack biological context (pathways, disease associations). Always report the identification confidence level. Pathway enrichment strategy : When multiple metabolites map to the same KEGG or HMDB pathway, enrichment is meaningful only if the input list is unbiased (not pre selected for that pathway). Report hits vs. pathway size (3/5 detected is more informative than 3/500). LOOK UP DON'T GUESS — use HMDB get metabolite to get pathway annotations for each metabolite rather than assuming pathway membership from names alone. Biomarker discovery reasoning : A candidate biomarker should show: (1) consistent direction of change across samples (fold change 1.5), (2) statistical significance (FDR adjusted p < 0.05), (3) biological plausibility — LOOK UP the metabolite's known disease associations via HMDB, and (4) reproducibility in an independent cohort. Single study HMDB associations are hypothesis generating, not confirmatory. Check MetaboLights/Metabolomics Workbench for independent validation datasets. Synthesis Questions A complete metabolomics report should answer: 1. What is the identification confidence level for each metabolite (L1 L4)? 2. Which biological pathways are enriched among the identified metabolites? 3. Do any metabolites

tooluniverse-metabolomics