🔍 Unified Search - Single entry point for multi-source academic search.

Automatically analyzes your query and searches the best sources. No need to choose between PubMed, OpenAlex, CrossRef, etc.

═══════════════════════════════════════════════════════════════════ WHAT IT DOES: ═══════════════════════════════════════════════════════════════════

1. Analyzes your query (complexity, intent, PICO elements)

2. Automatically selects best sources based on query type

3. Searches multiple sources in parallel

4. Deduplicates and merges results

5. Ranks by configurable criteria

6. Enriches with OA links (Unpaywall)

7. Auto-detects ICD-9/10 codes and expands to MeSH terms

8. Optionally searches preprints (arXiv, medRxiv, bioRxiv)

═══════════════════════════════════════════════════════════════════ EXAMPLES (most calls only need 1-2 params): ═══════════════════════════════════════════════════════════════════

Simple (1 param): unified_search("remimazolam ICU sedation")

With limit (2 params): unified_search("machine learning in anesthesia", limit=20)

Specify sources: unified_search("CRISPR gene therapy", sources="pubmed,openalex")

Auto minus one source: unified_search("sepsis biomarkers", sources="auto,-semantic_scholar")

Search all enabled sources except enrichment-only CrossRef: unified_search("icu sedation", sources="all,-crossref")

Clinical filters: unified_search("diabetes treatment", filters="year:2020-2025, age:aged, clinical:therapy")

Include preprints + shallow search: unified_search("COVID-19 vaccine", options="preprints, shallow")

Full control: unified_search("propofol vs remimazolam", sources="pubmed,semantic_scholar,europe_pmc", ranking="impact", filters="year:2020-, sex:female, species:humans", options="preprints, no_relax")

ICD Code Auto-Detection: unified_search("E11 complications") → Auto-expands E11 to "Diabetes Mellitus, Type 2"[MeSH]

Args: query: Your search query (natural language, ICD codes, or structured) limit: Maximum results per source (default 10, max 100) sources: Comma-separated list of sources to search. Available: "pubmed", "openalex", "semantic_scholar", "europe_pmc", "crossref", "core". Commercial connectors may also appear when enabled via env, e.g. "scopus" when SCOPUS_ENABLED=true and SCOPUS_API_KEY are configured, or "web_of_science" when WEB_OF_SCIENCE_ENABLED=true and WEB_OF_SCIENCE_API_KEY are configured. Default: auto-select based on query complexity. Supports "auto" and "all" with exclusions. Examples: "pubmed,openalex", "auto,-semantic_scholar", or "all,-crossref" Global disable env: PUBMED_SEARCH_DISABLED_SOURCES Example: PUBMED_SEARCH_DISABLED_SOURCES=semantic_scholar,core ranking: Ranking strategy: - "balanced": Default, considers all factors - "impact": Prioritize high-citation papers - "recency": Prioritize recent publications - "quality": Prioritize high-evidence studies (RCTs, meta-analyses) output_format: "markdown" (human-readable), "json", or "toon" (programmatic) filters: Comma-separated key:value pairs for filtering results. Supported keys: year:2020-2025 → publication year range year:2020- → from 2020 onwards year:-2025 → up to 2025 year:2024 → from 2024 onwards age: → age group filter (PubMed). Values: newborn, infant, preschool, child, adolescent, young_adult, adult, middle_aged, aged, aged_80 sex: → sex filter: male, female species: → species filter: humans, animals lang: → language filter: english, chinese, etc. clinical: → clinical query filter (PubMed EBM). Values: therapy, therapy_narrow, diagnosis, diagnosis_narrow, prognosis, prognosis_narrow, etiology, etiology_narrow, clinical_prediction, clinical_prediction_narrow Example: "year:2020-2025, age:aged, sex:female, clinical:therapy" options: Comma-separated flags to toggle behaviors. Supported flags: preprints → also search arXiv, medRxiv, bioRxiv all_types → include non-peer-reviewed articles no_oa → skip Unpaywall OA link enrichment no_analysis → hide query analysis section in output no_scores → hide similarity/relevance scores compact → compact structured JSON/TOON output no_next → hide next-tool suggestions in structured output no_provenance → hide section provenance in structured output no_relax → disable auto-relaxation on 0 results shallow → disable deep search (faster, keyword-only) Example: "preprints, shallow" or "no_analysis, no_scores" pipeline: YAML/JSON string defining a multi-step search pipeline. When provided, other parameters (except output_format) are ignored and the pipeline DAG is executed instead.

         Accepts **YAML** (recommended, human-friendly) or **JSON** format.

         **Template mode — YAML** (shortcut for common workflows):
           template: pico
           params:
             P: ICU patients
             I: remimazolam
             C: propofol
             O: sedation

         Other templates:
           template: comprehensive
           params:
             query: CRISPR gene therapy

           template: exploration
           params:
             pmid: "12345678"

           template: gene_drug
           params:
             term: BRCA1

         **Custom pipeline — YAML** (full DAG control, max 20 steps):
           name: My Custom Search
           steps:
             - id: s1
               action: search
               params:
                 query: remimazolam ICU
                 sources: pubmed,europe_pmc
                 limit: 50
             - id: s2
               action: search
               params:
                 query: propofol ICU
                 sources: pubmed
                 limit: 50
             - id: merged
               action: merge
               inputs: [s1, s2]
               params:
                 method: rrf
             - id: enriched
               action: metrics
               inputs: [merged]
           output:
             format: markdown
             limit: 20
             ranking: impact

         Shared params:
           globals: default params inherited by every step
           variables: values available as ${name} placeholders

         Debugging controls:
           dry_run: validate/preview the pipeline without searches
           stop_at: execute through one step id, e.g. "merged"

         **JSON also supported** (for programmatic use):
           {"template": "pico", "params": {"P": "ICU patients", "I": "remimazolam"}}

         Available actions:
           search      — literature search (params: query, sources, limit, min_year, max_year)
           pico        — PICO elements (params: P, I, C, O)
           expand      — MeSH/synonym expansion (params: topic)
           details     — fetch article details (params: pmids)
           related     — find related articles (params: pmid, limit)
           citing      — find citing articles (params: pmid, limit)
           references  — get article references (params: pmid, limit)
           metrics     — enrich with iCite citation metrics (inputs only)
           merge       — combine results (params: method=union|intersection|rrf)
           filter      — post-filter (params: min_year, max_year, article_types, min_citations, has_abstract)

Returns: Formatted search results with: - Query analysis (complexity, intent, PICO) - ICD code expansions (if detected) - Search statistics (sources, dedup count) - Ranked articles with metadata - Open access links where available - Preprints (if options includes "preprints") - Relaxation info (if auto_relax triggered) - Pipeline step summary (if pipeline mode)

Analyze a search query without executing the search.

Useful for understanding how unified_search will process your query before actually running it.

Args: query: The search query to analyze

Returns: Analysis including: - Complexity level (SIMPLE/MODERATE/COMPLEX/AMBIGUOUS) - Intent (LOOKUP/EXPLORATION/COMPARISON/SYSTEMATIC) - PICO elements (if detected) - Recommended sources - Recommended strategies

Validate agent-provided PICO elements and return a runnable search plan.

The agent, not this MCP server, extracts P/I/C/O from the user's natural language question. When only description is provided, this tool returns the schema the agent should fill and asks the agent to call this tool again with structured elements.

Args: description: Original clinical question for provenance. p: Population / patient group extracted by the agent. i: Intervention / exposure / index test extracted by the agent. c: Comparator extracted by the agent, optional. o: Outcome extracted by the agent, recommended. p_query/i_query/c_query/o_query: Optional expanded PubMed-ready query fragments. When present, the PICO pipeline uses these for search while preserving the human-readable P/I/C/O labels. question_type: therapy, diagnosis, prognosis, or etiology. Inferred heuristically when omitted. profile: Search profile for the PICO template, default balanced. sources: Comma-separated sources for the pipeline. limit: Final result limit for the pipeline.

Returns: JSON containing validation, PICO schema, query plan, and pipeline YAML that can be passed to unified_search(pipeline=...).

Gather search intelligence for a topic - returns RAW MATERIALS for Agent to decide.

This tool provides the BUILDING BLOCKS for search, not finished queries. The Agent decides how to use them.

══════════════════════════════════════════════════════════════════════ TWO USAGE MODES: ══════════════════════════════════════════════════════════════════════

MODE 1: KEYWORD SEARCH (single topic) ───────────────────────────────────── User: "搜尋 remimazolam 的文獻"

Step 1: generate_search_queries("remimazolam") Step 2: Build a Boolean query from returned materials Step 3: analyze_search_query(query="") Step 4: unified_search(query="")

══════════════════════════════════════════════════════════════════════

MODE 2: PICO SEARCH (clinical question) ─────────────────────────────────────── User: "remimazolam 在 ICU 鎮靜比 propofol 好嗎？會減少 delirium 嗎？"

Step 1: Agent extracts P/I/C/O from the clinical question, then calls parse_pico(description=..., p=..., i=..., c=..., o=...) to validate the structured handoff and get a runnable PICO pipeline.

Step 2: For EACH PICO element, call generate_search_queries() IN PARALLEL: - generate_search_queries("ICU patients") → P materials - generate_search_queries("remimazolam") → I materials - generate_search_queries("propofol") → C materials - generate_search_queries("delirium") → O materials

Step 3: Combine materials using Boolean logic: High precision: (P_terms) AND (I_terms) AND (C_terms) AND (O_terms) High recall: (P_terms) AND (I_terms OR C_terms) AND (O_terms)

Step 4: Add Clinical Query filter if appropriate: - therapy[filter] → 治療效果比較 - diagnosis[filter] → 診斷相關 - prognosis[filter] → 預後相關 - etiology[filter] → 病因相關

Step 5: Validate the final query with analyze_search_query()
Step 6: Execute unified_search() with the final Boolean query

══════════════════════════════════════════════════════════════════════

Features:

• Spelling correction via NCBI ESpell

• MeSH term lookup for standardized vocabulary

• Synonym expansion from MeSH database

• Query analysis: Shows how PubMed actually interprets each query (Agent's understanding vs PubMed's actual interpretation)

Args: topic: Search topic - can be a single keyword or PICO element strategy: Affects suggested_queries (if included) - "comprehensive": Multiple angles, includes reviews (default) - "focused": Adds RCT filter for high evidence - "exploratory": Broader search with more synonyms check_spelling: Whether to check/correct spelling (default: True) include_suggestions: Include pre-built query suggestions (default: True)

Returns: JSON with RAW MATERIALS: - corrected_topic: Spell-checked topic - keywords: Extracted significant keywords - mesh_terms: MeSH data with preferred terms and synonyms - all_synonyms: Flattened list of all synonyms - suggested_queries: Optional pre-built queries with: - estimated_count: How many results PubMed would return - pubmed_translation: How PubMed actually interprets the query

Find articles related to a given PubMed article. Uses PubMed's "Related Articles" feature to find similar papers.

═══════════════════════════════════════════════════════════════ 🔗 CITATION NETWORK EXPLORATION WORKFLOW ═══════════════════════════════════════════════════════════════

This is ONE of THREE tools for exploring citation networks:

1️⃣ find_related_articles() ← YOU ARE HERE │ 📌 Algorithm-based similarity (like PubMed "Similar Articles") │ 📌 Finds papers with similar topics, MeSH terms, authors │ 📌 Good for: Discovering related research you might have missed └─► Returns: Similar papers (not based on citations)

2️⃣ find_citing_articles() │ 📌 Forward citation search (who cited THIS paper?) │ 📌 Finds papers published AFTER the source article │ 📌 Good for: Tracking impact, finding follow-up studies └─► Returns: Papers that cite this article

3️⃣ get_article_references() │ 📌 Backward citation search (what did THIS paper cite?) │ 📌 Finds papers published BEFORE the source article │ 📌 Good for: Finding foundational papers, methodology sources └─► Returns: This article's bibliography

═══════════════════════════════════════════════════════════════ EXAMPLE WORKFLOW: ═══════════════════════════════════════════════════════════════

Step 1: Start with a key paper find_related_articles(pmid="23132851") → Find similar research directions

Step 2: Explore backward (foundations) get_article_references(pmid="23132851") → Find the foundational papers it builds on

Step 3: Explore forward (impact) find_citing_articles(pmid="23132851") → Find how the field developed after this paper

Args: pmid: PubMed ID of the source article (accepts: "12345678", "PMID:12345678", 12345678). limit: Maximum number of related articles to return (1-50, default: 5).

Returns: List of related articles with details.

Find articles that cite a given PubMed article. Uses PubMed Central's citation data to find papers that reference this article.

═══════════════════════════════════════════════════════════════ 📈 FORWARD CITATION SEARCH (Impact Tracking) ═══════════════════════════════════════════════════════════════

Direction: Source Paper → Papers that cite it (FORWARD in time)

USE CASES: ──────────

• 🔬 Track research impact: Who built on this work?

• 📊 Find follow-up studies: What happened after this discovery?

• 🔄 Identify controversies: Papers that challenge or refute findings

• 📚 Literature review: Ensure you have the latest developments

COMPLEMENTARY TOOLS: ────────────────────

• get_article_references(): BACKWARD search (what this paper cited)

• find_related_articles(): Similar papers (topic-based, not citation-based)

═══════════════════════════════════════════════════════════════ EXAMPLE: ═══════════════════════════════════════════════════════════════

Find papers that cite a landmark CRISPR paper

find_citing_articles(pmid="23287718", limit=20) → Returns papers published AFTER 2012 that reference this work

Then analyze citation metrics

get_citation_metrics(pmids="last") → See which citing papers are most influential

Args: pmid: PubMed ID of the source article (accepts: "12345678", "PMID:12345678", 12345678). limit: Maximum number of citing articles to return (1-100, default: 10).

Returns: List of citing articles with details.

Get the references (bibliography) of a PubMed article.

Returns the list of articles that this paper cites in its bibliography. This is the OPPOSITE of find_citing_articles:

• get_article_references: Papers THIS article cites (backward in time)

• find_citing_articles: Papers that cite THIS article (forward in time)

═══════════════════════════════════════════════════════════════ 📚 BACKWARD CITATION SEARCH (Foundation Discovery) ═══════════════════════════════════════════════════════════════

Direction: Source Paper → Papers it cited (BACKWARD in time)

USE CASES: ──────────

• 🏛️ Find foundational papers: Core works the field builds on

• ⚗️ Methodology sources: Papers describing techniques used

• 📖 Background reading: Build understanding of a topic

• 🔍 Verify claims: Check sources for specific assertions

═══════════════════════════════════════════════════════════════ EXAMPLE WORKFLOW: ═══════════════════════════════════════════════════════════════

Start with a recent review article

get_article_references(pmid="38123456", limit=50) → Get the bibliography of this review

Find most-cited foundational papers

get_citation_metrics(pmids="last", sort_by="citation_count") → Identify which references are the most influential

Read a foundational paper

fetch_article_details(pmids="12345678") → Get full details of an important reference

Args: pmid: PubMed ID of the source article (accepts: "12345678", "PMID:12345678", 12345678). limit: Maximum number of references to return (1-100, default: 20).

Returns: List of referenced articles with details.

Fetch detailed information for one or more PubMed articles.

Args: pmids: PubMed IDs - accepts multiple formats: - "12345678" (single) - "12345678,87654321" (comma-separated) - "PMID:12345678" (with prefix) - ["12345678", "87654321"] (list) - 12345678 (integer)

Returns: Detailed information for each article.

Get citation metrics from NIH iCite for articles.

Returns field-normalized citation data including:

• citation_count: Total number of citations

• relative_citation_ratio (RCR): Field-normalized metric (1.0 = average)

• nih_percentile: Percentile ranking (0-100)

• citations_per_year: Citation velocity

• apt: Approximate Potential to Translate (clinical relevance 0-1)

Can sort and filter results by citation metrics.

Args: pmids: PubMed IDs - accepts multiple formats: - "12345678,87654321" (comma-separated) - ["12345678", "87654321"] (list) - "PMID:12345678" (with prefix) - "last" to use PMIDs from the last search sort_by: Metric to sort by: - "citation_count": Raw citation count (default) - "relative_citation_ratio": Field-normalized (recommended) - "nih_percentile": Percentile ranking - "citations_per_year": Citation velocity min_citations: Filter out articles with fewer citations min_rcr: Filter out articles with RCR below threshold (e.g., 1.0 = average) min_percentile: Filter out articles below percentile (e.g., 50 = top half)

Returns: Articles with citation metrics, sorted and filtered as requested.

Verify a plain-text reference list against PubMed evidence.

First version scope: - Reference-list verification only - Client supplies the extracted reference list text - Backend parses entries and resolves them via PMID / DOI / ECitMatch

Second version scope: - Adds unresolved review workflow for partial_match and unresolved rows - Returns a manual-review queue with retry queries and review checklist - Supports human-in-the-loop acceptance/rejection in client-side workflows

Args: reference_text: Plain-text references, ideally one per line or a numbered reference list extracted from a file. source_name: Optional file label for reporting. max_references: Maximum number of references to process.

Returns: JSON verification report with parsed fields, matched PubMed evidence, and per-reference verification status.

Export citations to reference manager formats.

╔═══════════════════════════════════════════════════════════════════╗ ║ RECOMMENDED: Use source="official" (default) for best quality ║ ╚═══════════════════════════════════════════════════════════════════╝

When to Use

• Exporting references to EndNote, Zotero, Mendeley

• Creating BibTeX for LaTeX documents

• Generating citation lists for manuscripts

Source Options

Format Selection Guide

• ris: EndNote, Zotero, Mendeley (official recommended)

• medline: NBIB format for PubMed tools

• csl: JSON for programmatic citation styling

• bibtex: LaTeX documents (local only)

• csv: Data analysis, Excel (local only)

Args: pmids: Articles to export. Accepts: - "last" → results from previous search - "12345678,87654321" → comma-separated PMIDs - ["12345678", "87654321"] → list of PMIDs - "PMID:12345678" → with prefix format: Export format (default: "ris") - official API: ris, medline, csl - local only: bibtex, csv, json include_abstract: Include abstracts in output (default: True) source: Citation source (default: "official") - "official": NCBI Citation API (recommended, best quality) - "local": Local formatting (more formats, offline capable)

Returns: JSON with status and export_text containing formatted citations.

Examples: # Export last search results (recommended) prepare_export(pmids="last", format="ris")

# Export specific PMIDs to BibTeX
prepare_export(pmids="12345678,87654321", format="bibtex", source="local")

# Get CSL-JSON for programmatic use
prepare_export(pmids="last", format="csl", source="official")

Save searched articles as guided local wiki/Foam/Markdown notes.

When to Use

• After unified_search, persist the selected literature into a local note library.

• Give agents a structured alternative to generic write_file calls.

• Create wiki notes with Foam-compatible wikilinks, MedPaper-like reference notes, and frontmatter.

• Use stable wiki/Foam link targets and return wiki_validation for unresolved-link checks.

Local Directory Resolution

1. output_dir argument, if provided

2. PUBMED_NOTES_DIR environment variable

3. PUBMED_WORKSPACE_DIR/references

4. PUBMED_DATA_DIR/references

Args: pmids: Articles to save. Accepts "last", comma-separated PMIDs, list, or int. output_dir: Optional target folder for notes. note_format: "wiki" (default, Foam-compatible), "foam", "markdown", or "medpaper". include_abstract: Include abstracts in article notes. overwrite: Overwrite existing per-article notes when filenames collide. create_index: Create a collection index note linking saved articles. collection_name: Optional title/file stem for the index note. template_file: Optional Markdown template with placeholders like {title}, {pmid}, {citation_key}. include_csl_json: Write references.csl.json beside notes for citation-manager handoff.

Returns: JSON with output_dir, written files, skipped files, index path, and wiki_validation.

Examples: save_literature_notes(pmids="last") save_literature_notes(pmids="last", note_format="medpaper", output_dir="./references") save_literature_notes(pmids="12345678,87654321", template_file="./ref-template.md")

🔥 Enhanced multi-source fulltext retrieval.

Automatically tries multiple sources to find the best fulltext:

1. Europe PMC (if PMC ID available)

2. Unpaywall (finds OA versions via DOI)

3. Institutional direct/EZproxy fetch (when DOI-backed and enabled)

4. CORE (200M+ open access papers)

With extended_sources=True, also searches: 5. CrossRef (publisher links) 6. DOAJ (Gold OA journals) 7. Zenodo (research repository) 8. PubMed LinkOut (external providers) 9. Semantic Scholar, OpenAlex, arXiv, bioRxiv, medRxiv

Accepts flexible input - provide ANY ONE of:

• identifier: Auto-detects PMID, PMC ID, or DOI

• pmcid: Direct PMC ID

• pmid: PubMed ID (will lookup PMC ID)

• doi: DOI (will search Unpaywall/CORE)

Args: identifier: Auto-detect format - PMID, PMC ID, or DOI Examples: "PMC7096777", "12345678", "10.1001/jama.2024.1234" pmcid: PubMed Central ID (e.g., "PMC7096777", "7096777") pmid: PubMed ID (e.g., "12345678") doi: DOI (e.g., "10.1001/jama.2024.1234") sections: Filter sections (e.g., "introduction,methods,results") include_pdf_links: Include PDF download links (default: True) include_figures: Include figure metadata with image URLs (default: False) extended_sources: Search the extended downloader chain after the standard policy (default: False) output_format: Response format - "markdown" (default), "json", or "toon" allow_browser_session: Control browser-session fallback. - True: force broker fallback when configured - False: disable broker fallback - None: use auto mode from broker configuration

Returns: Fulltext content with PDF links from all available sources.

Example: get_fulltext(identifier="PMC7096777") get_fulltext(doi="10.1038/s41586-021-03819-2") get_fulltext(pmid="12345678", extended_sources=True)

Get text-mined annotations from Europe PMC.

Returns entities extracted from the article text including genes, diseases, chemicals, organisms, and more. Useful for identifying key concepts.

Args: pmid: PubMed ID of the article (accepts: "12345678", 12345678). pmcid: PMC ID (alternative to PMID, accepts: "PMC7096777", "7096777"). semantic_type: Filter by entity type. Options: - "GENE_PROTEIN": Genes and proteins - "DISEASE": Diseases and conditions - "CHEMICAL": Drugs and chemicals - "ORGANISM": Species and organisms - "GO_TERM": Gene Ontology terms - None: Return all types (default)

Returns: List of text-mined entities with counts and sections.

Get structured figure metadata (label, caption, image URL) and PDF links from a PMC Open Access article.

Returns all figures with their captions and direct image URLs, plus PDF download links for the complete article.

Accepts flexible input - provide ANY ONE of:

• identifier: Auto-detects PMID or PMC ID

• pmcid: Direct PMC ID

• pmid: PubMed ID (requires PMC ID lookup)

Args: identifier: Auto-detect format - PMID or PMC ID. Examples: "PMC12086443", "40384072" pmcid: PubMed Central ID (e.g., "PMC12086443" or "12086443"). pmid: PubMed ID (e.g., "40384072"). The article must be in PMC. include_subfigures: Parse sub-figures (e.g., Figure 3A, 3B) as separate entries. include_tables: Also extract tables rendered as images.

Returns: Structured figure data with image URLs, captions, and PDF links.

Example: get_article_figures(identifier="PMC12086443") get_article_figures(pmid="40384072")

Search NCBI Gene database for gene information.

═══════════════════════════════════════════════════════════════ USE CASES: ═══════════════════════════════════════════════════════════════

• Look up gene function and description

• Find gene aliases and official symbols

• Get chromosome location

• Find genes by name or function

Args: query: Gene name, symbol, or function keyword organism: Filter by organism (e.g., "human", "Homo sapiens", "mouse") limit: Maximum results (1-50)

Returns: JSON with gene records including symbols, names, locations

Get detailed information about a gene by NCBI Gene ID.

Args: gene_id: NCBI Gene ID (from search results or known)

Returns: JSON with gene details including symbol, name, summary, location

Get PubMed articles linked to a gene.

This uses NCBI's curated gene-to-publication links, which are more precise than keyword searches.

Args: gene_id: NCBI Gene ID limit: Maximum PubMed IDs to return (1-100)

Returns: JSON with linked PubMed IDs

Search PubChem for chemical compounds.

═══════════════════════════════════════════════════════════════ USE CASES: ═══════════════════════════════════════════════════════════════

• Look up drug/compound information

• Find molecular formula and structure

• Get compound synonyms and identifiers

• Research chemical properties

Args: query: Compound name or description limit: Maximum results (1-50)

Returns: JSON with compound records including names, formulas, properties

Get detailed information about a compound by PubChem CID.

Args: cid: PubChem Compound ID

Returns: JSON with compound details including formula, SMILES, properties

Get PubMed articles linked to a compound.

Uses NCBI's curated compound-to-publication links.

Args: cid: PubChem Compound ID limit: Maximum PubMed IDs to return (1-100)

Returns: JSON with linked PubMed IDs

Search ClinVar for clinical variants.

═══════════════════════════════════════════════════════════════ USE CASES: ═══════════════════════════════════════════════════════════════

• Look up clinical significance of genetic variants

• Find variants associated with diseases

• Research gene-disease associations

• Get variant pathogenicity classifications

Args: query: Gene name, variant, or disease condition limit: Maximum results (1-50)

Returns: JSON with variant records including significance and conditions

Build a citation tree (network) from a single article.

🌳 Creates a visual citation network showing research lineage:

• Forward (citing): Who cites this paper? (newer research)

• Backward (references): What does this paper cite? (foundational work)

⚠️ IMPORTANT: Only accepts ONE PMID at a time to control API load. For multiple papers, call this tool separately for each.

📊 Output Formats (output_format parameter):

• "cytoscape": Cytoscape.js format (default, academic standard)

• "g6": AntV G6 format (modern, high-performance)

• "d3": D3.js force graph format (flexible, Observable)

• "vis": vis-network format (simple, quick prototypes)

• "graphml": GraphML XML (desktop tools: Gephi, yEd, VOSviewer)

• "mermaid": Mermaid diagram (VS Code preview, Markdown) ⭐NEW

Args: pmid: Single PubMed ID (e.g., "12345678"). Only ONE PMID accepted - do NOT pass multiple. depth: How many levels to traverse (1-3, default 2). - depth=1: Direct citations/references only - depth=2: Also get citations of citations (recommended) - depth=3: Maximum depth (can be slow, ~100+ API calls) direction: Which direction to build the tree: - "forward": Only citing articles (who cites this) - "backward": Only references (what this cites) - "both": Both directions (default, recommended) limit_per_level: Max articles to fetch per node per level (default 5) include_details: Include full article details (default True) output_format: Graph format for visualization (default "cytoscape") - "cytoscape": Cytoscape.js (academic standard, bioinformatics) - "g6": AntV G6 (modern, TypeScript, great for large graphs) - "d3": D3.js force layout (most flexible, Observable notebooks) - "vis": vis-network (simple and easy) - "graphml": GraphML XML (Gephi, VOSviewer, yEd, Pajek) - "mermaid": Mermaid diagram (preview in VS Code Markdown)

Returns: JSON string with graph data in the requested format. Includes metadata and statistics regardless of format.

Example usage: # Build 2-level tree for a paper (default Cytoscape.js format) build_citation_tree(pmid="33475315", depth=2, direction="both")

# Use AntV G6 format for modern web visualization
build_citation_tree(pmid="33475315", depth=2, output_format="g6")

# Export GraphML for Gephi analysis
build_citation_tree(pmid="33475315", depth=2, output_format="graphml")

Build a research timeline for a topic OR specific PMIDs.

═══════════════════════════════════════════════════════════════ 🎯 TWO MODES OF OPERATION ═══════════════════════════════════════════════════════════════

Mode 1: Search by topic (default) build_research_timeline(topic="remimazolam")

Mode 2: Build from specific PMIDs build_research_timeline(pmids="12345678,23456789", topic="My Timeline")

═══════════════════════════════════════════════════════════════ MILESTONE DETECTION ═══════════════════════════════════════════════════════════════

Automatically detects significant milestones including:

• First reports and mechanism discoveries

• Clinical trial phases (Phase 1/2/3/4)

• FDA/EMA approvals

• Meta-analyses and systematic reviews

• Guidelines and consensus statements

• Safety alerts and label updates

• High-impact landmark studies

═══════════════════════════════════════════════════════════════ OUTPUT FORMATS (output_format parameter) ═══════════════════════════════════════════════════════════════

• "text": Human-readable text format (default)

• "tree": Research lineage tree — branches by sub-topic (NEW)

• "mermaid": Mermaid timeline (VS Code, GitHub preview)

• "mindmap": Mermaid mindmap of research branches (NEW)

• "json": Full JSON data

• "timeline_js": TimelineJS library format

• "d3": D3.js visualization format

Args: topic: Research topic (drug name, gene, disease, etc.) Required if pmids not provided. Examples: "remimazolam", "BRCA1", "pembrolizumab melanoma" pmids: Comma-separated PMIDs or "last" for previous search results If provided, builds timeline from these specific articles. Example: "12345678,23456789,34567890" max_events: Maximum number of events to include (default: 30) min_year: Filter articles from this year (optional, topic mode only) max_year: Filter articles until this year (optional, topic mode only) include_all: Include non-milestone articles as generic events output_format: "text", "tree", "mermaid", "mindmap", "json", "json_tree", "timeline_js", or "d3"

Returns: Research timeline with detected milestones in requested format.

Examples: # By topic build_research_timeline(topic="remimazolam", max_events=20) build_research_timeline(topic="CAR-T therapy", min_year=2015, output_format="mermaid")

# By PMIDs
build_research_timeline(pmids="12345678,23456789", topic="Propofol Studies")
build_research_timeline(pmids="last", topic="Previous Search", output_format="json")

Analyze milestone distribution for a research topic.

Provides statistics on:

• Milestone type distribution

• Temporal patterns (which years had most activity)

• Evidence quality breakdown

• Key high-impact studies

Args: topic: Research topic to analyze max_results: Maximum articles to analyze

Returns: Detailed analysis of milestone patterns.

Example: analyze_timeline_milestones("remdesivir COVID-19")

Compare research timelines of multiple topics.

Useful for:

• Comparing drug development timelines

• Contrasting research evolution across conditions

• Understanding parallel research tracks

Args: topics: Comma-separated topics to compare Example: "remimazolam,propofol,dexmedetomidine" max_events_per_topic: Maximum events per topic

Returns: Comparative analysis of the timelines.

Example: compare_timelines("remimazolam,propofol", max_events_per_topic=10)

Analyze a scientific figure or image for literature search.

═══════════════════════════════════════════════════════════════════════ 🔬 VISION-TO-LITERATURE SEARCH (Experimental) ═══════════════════════════════════════════════════════════════════════

This tool enables searching for scientific literature based on images.

WORKFLOW (Agent MUST follow all steps automatically): ─────────────────────────────────────────────────────────

1. Provide an image (URL or base64-encoded)

2. This tool returns the image using MCP ImageContent protocol

3. YOU (the Agent) analyze the image using your vision capabilities

4. Extract relevant ENGLISH search terms from the image

5. IMMEDIATELY call search_biomedical_images() or unified_search() with the extracted terms - DO NOT wait for user confirmation

6. Return both the analysis and search results to the user

⚠️ IMPORTANT RULES: ────────────────

• ALL search queries must be in ENGLISH (Open-i requirement)

• After analyzing the image, proceed to search automatically

• Do NOT just describe the image and stop - complete the full workflow

• If the image shows a medical condition, extract the medical term in English

SEARCH TYPES: ─────────────

• "comprehensive": General analysis, extract all relevant terms (default)

• "methodology": Focus on methods, equipment, techniques shown

• "results": Focus on data, graphs, statistical findings

• "structure": Focus on molecular/chemical structures

• "medical": Focus on clinical/medical imaging findings

USE CASES: ──────────

• 📊 Scientific figures → Find papers with similar data/charts

• 🔬 Microscopy images → Find related research

• 🧬 Molecular structures → Find papers about the compound

• 📈 Graphs/plots → Find papers with similar analyses

• 🏥 Medical images → Find case reports or clinical studies

• ⚗️ Lab equipment → Find methodology papers

IMPORTANT: ────────── After analyzing the image, IMMEDIATELY search for related literature. Do NOT ask the user "do you want me to search?" — just do it. Use English medical terminology in all search queries.

Args: image: Base64-encoded image data OR data URI (data:image/png;base64,...) url: URL of the image to analyze context: Optional context about what to look for in the image search_type: Type of analysis focus (comprehensive/methodology/results/structure/medical)

Returns: List containing: - ImageContent: The image for you to analyze - TextContent: Instructions for next steps

Example: analyze_figure_for_search(url="https://example.com/figure1.png") analyze_figure_for_search(url="https://...", search_type="medical") analyze_figure_for_search(image="data:image/png;base64,iVBORw0...")

Configure your institution's link resolver for full-text access.

═══════════════════════════════════════════════════════════════════════════════ 🏛️ INSTITUTIONAL ACCESS CONFIGURATION ═══════════════════════════════════════════════════════════════════════════════

This tool configures OpenURL link resolver integration, allowing you to access paywalled articles through your institution's library subscription.

═══════════════════════════════════════════════════════════════════════════════ HOW IT WORKS: ═══════════════════════════════════════════════════════════════════════════════

1. Your library subscribes to journals through publishers

2. Library provides a "Link Resolver" service (SFX, 360 Link, Primo, etc.)

3. OpenURL passes article metadata to the resolver

4. Resolver checks your subscriptions and provides full-text access

═══════════════════════════════════════════════════════════════════════════════ USAGE: ═══════════════════════════════════════════════════════════════════════════════

Option 1: Use a preset (easiest) ───────────────────────────────── configure_institutional_access(preset="ntu")

Available presets:

• 台灣: "ntu" (台大), "ncku" (成大), "nthu" (清大), "nycu" (陽明交大)

• 美國: "harvard", "stanford", "mit", "yale"

• 英國: "oxford", "cambridge"

• 通用: "sfx", "360link", "primo" (需要 resolver_url)

Option 2: Custom URL ───────────────────── configure_institutional_access( resolver_url="https://your.library.edu/openurl" )

Option 3: Disable ───────────────────── configure_institutional_access(enable=False)

═══════════════════════════════════════════════════════════════════════════════ FINDING YOUR RESOLVER URL: ═══════════════════════════════════════════════════════════════════════════════

1. Go to your library's website

2. Look for "Find Full Text", "Link Resolver", or "OpenURL"

3. Or search: "[Your University] link resolver"

4. The URL usually looks like:

   • https://resolver.library.edu/openurl

   • https://library.primo.exlibrisgroup.com/openurl/...

   • https://sfx.library.edu/sfx_local

Args: resolver_url: Your institution's link resolver URL preset: Use a known institution's preset configuration enable: Whether to enable OpenURL links (default: True) test: Compatibility flag reserved for clients that still pass it. Use test_institutional_access() for an explicit resolver test.

Returns: Configuration status message

Generate institutional access link (OpenURL) for an article.

═══════════════════════════════════════════════════════════════════════════════ 🔗 GET LIBRARY ACCESS LINK ═══════════════════════════════════════════════════════════════════════════════

Generate an OpenURL that will take you through your library's link resolver to access the full text of an article.

PREREQUISITES: ───────────────── Must first call configure_institutional_access() to set up your resolver.

USAGE: ─────────────────

With PMID (easiest): get_institutional_link(pmid="38353755")

With DOI: get_institutional_link(doi="10.1001/jama.2024.1234")

With full metadata (most reliable): get_institutional_link( title="Some Article Title", journal="JAMA", year="2024", volume="331", issue="1", pages="45-52" )

Args: pmid: PubMed ID doi: Digital Object Identifier title: Article title journal: Journal name year: Publication year volume: Volume number issue: Issue number pages: Page range (e.g., "45-52")

Returns: OpenURL link or error message

List available institutional link resolver presets.

═══════════════════════════════════════════════════════════════════════════════ 📚 AVAILABLE RESOLVER PRESETS ═══════════════════════════════════════════════════════════════════════════════

These presets contain pre-configured URLs for common institutions. Use them with configure_institutional_access(preset="name").

Returns: List of available presets with URLs

Test your institutional link resolver configuration.

═══════════════════════════════════════════════════════════════════════════════ 🧪 TEST INSTITUTIONAL ACCESS ═══════════════════════════════════════════════════════════════════════════════

Tests if your configured link resolver is:

1. Properly configured

2. Reachable (network connection)

3. Returns a valid response

NOTE: This only tests if the resolver endpoint is reachable. Actual full-text access depends on your institution's subscriptions.

═══════════════════════════════════════════════════════════════════════════════ FREE TEST OPTIONS: ═══════════════════════════════════════════════════════════════════════════════

If you don't have institutional access, you can test with:

1. Use "test_free" preset (EBSCO public resolver): configure_institutional_access(preset="test_free") test_institutional_access()

2. Most university resolvers will respond even without VPN, they just won't provide full-text (shows "Access options" page)

Args: pmid: PMID to use for testing (default: 38353755)

Returns: Test results including: - Configuration status - Network reachability - Generated OpenURL - Link to test manually

Diagnose why institutional fulltext access succeeds or fails for an article.

Runs up to three probes and reports each path's outcome:

1. Direct fetch (Phase 1, IP-aware) — follows https://doi.org/<doi> and classifies whether the publisher served fulltext, a paywall, or a login page. Works automatically when your network IP is on the publisher's institutional allow-list (campus / VPN).

2. EZproxy fetch (Phase 2, BYO-cookie) — rewrites the publisher hostname to your library's EZproxy host and replays your exported browser session cookie. Configured via env vars:

   • EZPROXY_HOST (e.g. ezproxy.lib.ntu.edu.tw)

   • EZPROXY_COOKIE_FILE (path to browser-exported cookies.json)

   • EZPROXY_ENABLED=1

3. OpenURL handoff — generated for you to open manually in a browser when the automated paths fail.

Args: pmid: PubMed ID (used to enrich the OpenURL). doi: DOI (required for the direct + EZproxy probes). try_direct: Run the Phase 1 direct probe (default True). try_ezproxy: Run the Phase 2 EZproxy probe (default True).

Returns: Markdown report listing every probe's status, classification, and advice on the next action to take.

Convert between ICD codes and MeSH terms (bidirectional).

═══════════════════════════════════════════════════════════════ 🔄 BIDIRECTIONAL CONVERSION ═══════════════════════════════════════════════════════════════

ICD → MeSH (provide code): convert_icd_mesh(code="E11") → Diabetes Mellitus, Type 2 convert_icd_mesh(code="I21") → Myocardial Infarction convert_icd_mesh(code="250") → Diabetes Mellitus (ICD-9) convert_icd_mesh(code="U07.1") → COVID-19

MeSH → ICD (provide mesh_term): convert_icd_mesh(mesh_term="Diabetes Mellitus") convert_icd_mesh(mesh_term="Heart Failure")

Automatically detects ICD version (ICD-9 vs ICD-10) from code format.

Args: code: ICD-9 or ICD-10 code (e.g., "E11", "250", "I21.9") mesh_term: MeSH term (e.g., "Diabetes Mellitus", "Heart Failure")

Returns: JSON with conversion result and ready-to-use PubMed query

Note: Provide either 'code' OR 'mesh_term', not both.

🖼️ Search biomedical images across Open-i and Europe PMC.

Searches medical/scientific images from multiple sources and returns image URLs with metadata (caption, article info, MeSH terms).

═══════════════════════════════════════════════════════════════ ⚠️ CRITICAL - LANGUAGE REQUIREMENT: ═══════════════════════════════════════════════════════════ Open-i ONLY supports English queries. If the user queries in non-English (Chinese, Japanese, Korean, etc.), you MUST:

1. Translate the query to English medical terminology first

2. Then call this tool with the English query Example: "喉頭水腫" → "laryngeal edema" "胸部X光肺炎" → "chest X-ray pneumonia"

The tool has built-in translation hints for common CJK medical terms, but YOU should always verify the translation is correct.

═══════════════════════════════════════════════════════════ SOURCES: ═══════════════════════════════════════════════════════════════

• Open-i (NLM): X-ray, microscopy, clinical images (~133K)

• Europe PMC: Figure captions from 33M+ articles (future)

═══════════════════════════════════════════════════════════════ EXAMPLES: ═══════════════════════════════════════════════════════════════

General image search: search_biomedical_images("chest pneumonia CT scan")

X-ray only: search_biomedical_images("fracture", image_type="x")

Microscopy images: search_biomedical_images("histology liver", image_type="mc")

Clinical teaching images (MedPix): search_biomedical_images("pneumothorax", collection="mpx")

Case reports with CC-BY license, sorted by date: search_biomedical_images( "lung cancer", article_type="cr", license_type="by", sort_by="d" )

Cardiology specialty images: search_biomedical_images("echocardiogram", specialty="c")

Video content only: search_biomedical_images("surgery technique", video_only=True)

═══════════════════════════════════════════════════════════════

Args: query: Search query (e.g., "chest X-ray pneumonia") sources: Image sources to search: - "auto": Select best sources (default) - "openi": Open-i only (best for medical images) - "europe_pmc": Europe PMC only (future) - "all": Search all sources image_type: Filter by image type (Open-i only): Positive filters: - "c": CT scan images - "g": Graphics / line art / diagrams - "m": MRI images - "mc": Microscopy / histology images - "p": PET scan images - "ph": Photographs / clinical photos - "u": Ultrasound images - "x": X-ray images Exclusion filters: - "xg": Exclude Graphics (removes graphic images from results) - "xm": Exclude Multipanel (removes multipanel images) - None: All types (default) collection: Filter by collection (Open-i only): - "pmc": PubMed Central articles - "mpx": MedPix clinical teaching images (high quality) - "cxr": Chest X-ray collection - "hmd": History of Medicine - "usc": USC collection - None: All collections (default) open_access_only: Only return open access images (default True) limit: Maximum number of images to return (default 10, max 50) sort_by: Sort results by (Open-i only): - "r": Relevance (default) - "d": Date (newest first) - "o": Oldest first - "t": Title - "e": Education relevance - "g": Graphics priority article_type: Filter by article type (Open-i only): - "cr": Case Report - "or": Original Research - "re": Review - "sr": Systematic Review - "ra": Research Article - "ed": Editorial - "lt": Letter - "bk": Book - and more... (see API docs) specialty: Filter by medical specialty (Open-i only): - "r": Radiology - "c": Cardiology - "ne": Neurology - "pu": Pulmonology - "d": Dermatology - "g": Gastroenterology - "or": Orthopedics - "o": Ophthalmology - "s": Surgery - "p": Pediatrics - "id": Infectious Disease - "i": Immunology - and more... (see API docs) license_type: Filter by Creative Commons license (Open-i only): - "by": CC-BY (Attribution) - "bync": CC-BY-NC (Attribution-NonCommercial) - "byncnd": CC-BY-NC-ND (Attribution-NonCommercial-NoDerivs) - "byncsa": CC-BY-NC-SA (Attribution-NonCommercial-ShareAlike) subset: Filter by subject subset (Open-i only): - "b": Behavioral Sciences - "c": Cancer - "e": Ethics - "s": Surgery - "x": Toxicology search_fields: Search in specific fields (Open-i only): - "t": Title only - "m": MeSH terms only - "ab": Abstract only - "msh": MeSH heading only - "c": Caption only - "a": Author only video_only: If True, only return video content (default False)

Returns: Formatted image results with URLs, captions, and article metadata

Manage saved pipelines through a single facade.

Supported actions:

• save: save or update a named pipeline

• list: list saved pipelines, optionally filtered by tag/scope

• load: load pipeline YAML from saved name or file source

• delete: delete a saved pipeline and its history

• history: inspect execution history for one saved pipeline

• schedule: create, update, or remove an APScheduler-backed schedule

Args: action: One of save, list, load, delete, history, schedule. Default: list. name: Pipeline name for save/delete/history/schedule. config: Pipeline YAML/JSON string for save. source: Pipeline source for load, e.g. "saved:weekly_search" or "file:path/to/pipeline.yaml". tag: Tag filter for list action. tags: Comma-separated tags for save action. description: Description for save action. scope: Scope for save/list actions: workspace, global, auto. limit: History entry limit for history action. cron: 5-field cron expression for schedule action. Empty string removes the schedule. diff_mode: Store diff-mode preference with the schedule. notify: Store notify preference with the schedule.

Returns: Same human-readable responses as the legacy pipeline management tools.

Save a pipeline configuration for later reuse.

The config format is identical to unified_search's pipeline parameter (YAML or JSON). Saved pipelines can be loaded later by name: unified_search(pipeline="saved:weekly_remimazolam")

Args: name: Unique identifier (alphanumeric + hyphens/underscores, max 64 chars). Overwrites if name already exists (upsert semantics). config: Pipeline YAML/JSON string. Same format as unified_search pipeline param. tags: Comma-separated tags for filtering (e.g., "anesthesia,sedation"). description: Human-readable description of the pipeline's purpose. scope: Storage scope - "workspace" (project-level, git-trackable), "global" (user-level, cross-project), or "auto" (workspace if available, otherwise global). Default: "auto".

Returns: Confirmation with pipeline metadata.

List all saved pipeline configurations.

Args: tag: Filter by tag (e.g., "sedation"). Empty = show all. scope: Filter by scope: "workspace", "global", or "" (show all).

Returns: Table of saved pipelines with name, scope, description, tags.

Load a pipeline configuration for review or editing.

Loads from one of three sources:

• Saved name: "weekly_remimazolam" or "saved:weekly_remimazolam"

• Local file: "file:path/to/pipeline.yaml"

The returned YAML can be reviewed, modified, and then:

• Executed directly: unified_search(pipeline="")

• Saved with changes: save_pipeline(name="...", config="")

Args: source: Pipeline source identifier (see above).

Returns: Full pipeline YAML content + metadata.

Delete a saved pipeline configuration and its execution history.

Args: name: Name of the saved pipeline to delete.

Returns: Confirmation of deletion.

Get execution history for a saved pipeline.

Shows past execution results with diff analysis: which articles are new compared to the previous run.

Args: name: Name of the saved pipeline. limit: Maximum number of history entries to return (default: 5).

Returns: Execution history with date, article count, new/removed articles, status.

Schedule a saved pipeline for periodic execution.

Args: name: Saved pipeline name. cron: Cron expression (5-field). Examples: "0 9 * * 1" (Mon 9am). Empty string removes an existing schedule. diff_mode: When True, store diff-mode preference with the schedule. notify: When True, store notify preference with the schedule.

Returns: Schedule confirmation or removal result.

Read session data through a single facade.

Actions:

• pmids: return PMIDs for one recorded search

• article: return one cached article payload

• summary: return current session summary and optional history

• list_artifacts: list persistent MCP output artifact manifests

• artifact: read one persistent artifact by artifact_id or artifact_uri

For remote artifact reads, use artifact_file plus offset/max_chars to page through large files without rerunning upstream searches or fulltext calls. Use artifact_tool/artifact_kind to filter list_artifacts. Local paths are redacted unless include_local_paths=True.

取得 session 中暫存的 PMID 列表。

解決 Agent 記憶滿載問題 - 不需要記住所有 PMID， 可以隨時從 session 取回。

Args: search_index: 搜尋索引 - -1: 最近一次搜尋 (預設) - -2: 前一次搜尋 - 0, 1, 2...: 第 N 次搜尋 query_filter: 可選，篩選包含此字串的搜尋

Returns: JSON 格式的 PMID 列表和搜尋資訊

Example: get_session_pmids() # 最近一次搜尋的 PMIDs get_session_pmids(-2) # 前一次搜尋的 PMIDs get_session_pmids(query_filter="BJA") # 包含 "BJA" 的搜尋

從 session 快取取得文章詳情。

比重新呼叫 fetch_article_details 更快， 且不消耗 NCBI API quota。

Args: pmid: PubMed ID

Returns: 文章詳細資訊 (如果在快取中)

取得當前 session 的摘要資訊。

顯示快取狀態、搜尋歷史摘要，幫助 Agent 了解 目前有哪些資料可用。

Args: include_history: 是否包含完整搜尋歷史 (預設 False) history_limit: 歷史筆數上限，僅當 include_history=True 時有效 (預設 10)

Returns: Session 摘要，包含快取文章數、搜尋次數、最近搜尋等

Examples: get_session_summary() # 基本摘要 get_session_summary(include_history=True) # 含完整搜尋歷史 get_session_summary(include_history=True, history_limit=20) # 更多歷史

取得當前 session 的 activity log 與搜尋歷史摘要。

適合讓 user 回顧最近做過哪些搜尋、cache/reading-list/exclusion 變化，以及作為 debug 時的 session-level 事件檢視。

Args: event_limit: 回傳的 event 筆數上限 (預設 50) kind: 可選，僅回傳特定 event kind include_history: 是否一併包含搜尋歷史摘要 (預設 True) history_limit: 搜尋歷史摘要筆數上限 (預設 10)

Returns: Session activity log 與搜尋歷史摘要