🔍 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_group:aged,clinical_query:therapy")

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

Provider-native semantic retrieval (OpenAlex capability): unified_search("mechanisms of treatment resistance", sources="openalex", options="native_semantic")

Reproducible systematic retrieval (bulk/cursor where supported): unified_search("melanoma AND immunotherapy", sources="openalex,semantic_scholar", options="systematic")

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: Search query (natural language, ICD codes, or structured). Required unless pipeline is provided. 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. Source keys are exact and canonical; legacy hyphenated, spaced, abbreviated, or case-folded aliases are rejected. 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 publication-type heuristics (RCTs, meta-analyses); not a quality assessment 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_group: → 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 language: → language filter: english, chinese, etc. clinical_query: → clinical query filter (PubMed EBM). Values: therapy, therapy_narrow, diagnosis, diagnosis_narrow, prognosis, prognosis_narrow, etiology, etiology_narrow, clinical_prediction, clinical_prediction_narrow Tokens, keys, and values use exact canonical spelling with no surrounding whitespace. Example: "year:2020-2025,age_group:aged,sex:female,clinical_query:therapy" options: Comma-separated flags to toggle behaviors. Supported flags: preprints → also search arXiv, medRxiv, bioRxiv include_detected_preprints → retain records identified by the preprint heuristic in otherwise selected sources; this does not establish peer-review status clinical_trials → add a bounded ClinicalTrials.gov adjunct section to Markdown output (explicit opt-in) no_oa → skip Unpaywall OA link enrichment no_analysis → hide query analysis section in output no_scores → hide ranking scores and rank percentiles 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 native_semantic → use provider-native semantic retrieval; currently OpenAlex, max 50 results systematic → use deterministic bulk/cursor retrieval where supported (for example S2 and OpenAlex) shallow → disable deep search (faster, keyword-only) native_semantic and systematic are mutually exclusive Option tokens use exact canonical spelling with no surrounding whitespace. and automatically disable multi-strategy query expansion. Tokens use exact canonical spelling without surrounding whitespace or duplicates. 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
           template_params:
             P: ICU patients
             I: remimazolam
             C: propofol
             O: sedation

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

           template: exploration
           template_params:
             pmid: "12345678"

           template: gene_drug
           template_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 only by actions that
                    declare the same canonical parameter key
           variables: typed values available as ${name} placeholders;
                      embedded replacements must be strings

         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", "template_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 P/I/C/O and return a runnable PICO pipeline.

question_type and profile are closed enums. sources is an explicit array of supported unified-search providers; malformed values fail instead of being silently replaced. When question_type is omitted, the application service infers it from the clinical question.

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 validate_pico_plan(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) Recall-oriented: (P_terms) AND (I_terms OR C_terms); validate against eligible seed papers

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

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 publication-type filter; study quality still requires appraisal - "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 ("12345678" or "PMID: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 ("12345678" or "PMID: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 ("12345678" or "PMID: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) Inputs are string-only and fail as a complete batch when any PMID is invalid.

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 Batches are fail-closed and limited to 1,000 unique PMIDs. 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. iCite transport or response failures return an explicit retryable error and are never rendered as an empty/unindexed result.

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. Limited to 200,000 characters / 400,000 UTF-8 bytes; each entry is limited to 4,000 characters / 8,000 UTF-8 bytes. source_name: Optional single-line file label for reporting (up to 255 characters / 512 UTF-8 bytes). max_references: Hard input-entry limit from 1 through 200. Inputs above the selected limit are rejected instead of truncated.

Returns: JSON verification report with parsed fields, matched PubMed evidence, per-reference verification status, and explicit source_unavailable / not_checked rows when evidence could not be assessed.

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). False requires source="local"; official payloads are returned unmodified. 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

Authenticated Service Boundary

Remote authenticated callers cannot choose output_dir or template_file. Their notes always go to references/ under the current tenant's installed SessionManager data root; process-wide notes/workspace environment paths are intentionally ignored.

Args: pmids: Articles to save. Accepts "last", a PMID string, or a JSON array of PMID strings. 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 written/skipped files, index information, and wiki_validation. Local callers receive filesystem paths. Authenticated callers receive tenant-relative logical locators and never receive server host paths.

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 (open-access repository metadata and available text)

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

source is a discriminated identifier object, so the schema itself requires exactly one explicit PMID, PMCID, or DOI kind.

Args: source: One object such as {"kind":"pmid","value":"12345678"}, {"kind":"pmcid","value":"PMC7096777"}, or {"kind":"doi","value":"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(source={"kind":"pmcid","value":"PMC7096777"}) get_fulltext(source={"kind":"doi","value":"10.1038/s41586-021-03819-2"})

Get text-mined annotations from Europe PMC.

Returns entities extracted from the article text including genes, diseases, chemicals, organisms, and more. source is exactly one PMID or PMCID.

Args: source: {"kind":"pmid","value":"12345678"} or {"kind":"pmcid","value":"PMC7096777"}. 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.

source is a discriminated identifier object, so the schema itself requires exactly one explicit PMID or PMCID.

Args: source: {"kind":"pmcid","value":"PMC12086443"} or {"kind":"pmid","value":"40384072"}. 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(source={"kind":"pmcid","value":"PMC12086443"})

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)

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) 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: Markdown summary followed by JSON 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 persisted, versioned, evidence-backed Research Chronicle.

A chronicle is the durable record of how a research topic evolved, and the single entry point for research-evolution work (it replaces the older one-shot timeline tools). It is stored with a monotonic revision number, so re-running it later produces revision N+1 and you can diff revisions to see exactly what changed.

The primary axis is chronological; research branches are a secondary organizing dimension. Both come from the same stored snapshot, and preserve shared provenance in output="timeline" and output="tree". Agreement between projections is not independent evidence verification.

Every entry carries:

• a one-sentence claim with inline citations

• supporting / contradicting / updating evidence articles

• a research branch (lineage) assignment

• provenance and a confidence score

The typed provenance graph links Topic → Branch → Entry → EvidenceArticle and is validated against edge invariants. The audit reports evidence coverage, identifier coverage, branch coverage, graph integrity, and chronology gaps, so you always know how complete the picture is.

Args: topic: Research topic (drug, gene, disease, intervention). Required unless pmids or a stored chronicle_id is supplied. pmids: Comma-separated PMIDs, or "last" to chronicle the previous search results instead of running a new search. max_events: Maximum timeline events to consider (topic mode). Omit to inherit the continued revision's value, else 30. min_year: Earliest publication year to include (topic mode). max_year: Latest publication year to include (topic mode). chronicle_id: Continue an existing chronicle (creates revision N+1) instead of deriving the ID from the topic. Passing it alone re-runs the stored scope, so the resulting diff shows research movement rather than a changed window. output: "summary" (default compact Markdown with the chronological spine), "json", "chronicle_map", "timeline", "tree", "graph", "evidence", "milestones", "mermaid" (horizontal time spine with lineage branches), or "narrative". "json", "chronicle_map", "timeline", "tree", "graph", "evidence", and "milestones" return JSON; the rest return Markdown.

Returns: The requested rendering plus an artifact locator when durable artifact persistence is enabled and succeeds. The artifact contains the full snapshot, projections, evidence table, milestone analysis, and audit regardless of output. Artifact failure is reported but does not roll back the already saved Chronicle revision.

Examples: build_research_chronicle(topic="remimazolam") build_research_chronicle(pmids="last", topic="My Reading List") build_research_chronicle(topic="CAR-T therapy", output="mermaid") build_research_chronicle(chronicle_id="remimazolam-9f2b1c4d")

Read stored Research Chronicles: load, list, diff, narrate, analyze, compare.

This is the read facade over chronicles created by build_research_chronicle. Chronicles persist across sessions, so you can revisit a topic weeks later and see precisely what moved. Because the evidence is already stored, analysis and comparison are instant and do not re-run any search.

Actions:

• "load": read one revision (defaults to latest) in any output format

• "list": list stored chronicles, most recently updated first

• "diff": compare two revisions — added, not observed/removed from the later view, and updated entries, plus evidence churn, branch churn, and the audit status transition. Absence does not prove retirement.

• "narrate": render evidence-backed Markdown where every claim carries its entry ID and article identifiers

• "milestones": entry-type and status distribution, per-year activity, evidence quality, and landmark entries for one chronicle

• "compare": compare 2-5 chronicles side by side, including the evidence articles they share

The required request discriminator makes invalid field combinations unrepresentable. compare takes one typed selection containing either 2-5 topic strings or 2-5 Chronicle IDs.

Returns: Markdown or JSON text depending on the action and output format.

Examples: read_research_chronicle(request={"action":"list"}) read_research_chronicle(request={"action":"load","chronicle_id":"remimazolam-9f2b1c4d","output":"tree"}) read_research_chronicle(request={"action":"diff","chronicle_id":"remimazolam-9f2b1c4d","from_revision":1}) read_research_chronicle(request={"action":"narrate","chronicle_id":"remimazolam-9f2b1c4d","mode":"full"}) read_research_chronicle(request={"action":"milestones","chronicle_id":"remimazolam-9f2b1c4d"}) read_research_chronicle(request={"action":"compare","selection":{"kind":"topics","values":["remimazolam","propofol"]}})

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 (the host agent performs the analysis and search): ─────────────────────────────────────────────────────────

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. Call search_biomedical_images() or unified_search() with extracted terms when literature retrieval is within the user-requested scope

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

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

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

• This tool returns an image and guidance; it does not invoke a vision model

• The host agent controls any subsequent search within its permissions

• 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: ────────── Image observations are search hypotheses that require source verification. Follow the user-requested scope and the host agent's execution rules. Use English medical terminology in all search queries.

Args: source: Exactly one typed image source: {"kind": "base64", "data": "data:image/png;base64,..."} or {"kind": "url", "url": "https://example.org/figure.png"}. 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: prepare_figure_search(source={"kind": "url", "url": "https://example.com/figure1.png"}) prepare_figure_search( source={"kind": "base64", "data": "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.

Remote service callers may call this tool with no configuration arguments to inspect the operator-installed configuration, but cannot mutate the server-owned, deployment-wide OpenURL settings. Configure those at deployment time or from a trusted local server instead.

═══════════════════════════════════════════════════════════════════════════════ 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) 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( source={"kind": "pmid", "value": "38353755"} )

With DOI: get_institutional_link( source={"kind": "doi", "value": "10.1001/jama.2024.1234"} )

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

Args: source: Exactly one explicit PMID, DOI, or bounded metadata object.

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.

Usage: diagnose_institutional_access( source={"kind": "doi", "value": "10.1097/ALN.0000000000003599"} )

diagnose_institutional_access(
    source={"kind": "pmid", "value": "38353755"},
    try_ezproxy=False
)

Args: source: Exactly one PMID or DOI. A PMID is resolved to a DOI when possible so direct and EZproxy probes can run. 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.

Query the curated ICD/MeSH crosswalk in one explicit direction.

Use icd_to_mesh with one complete ICD-9-CM or ICD-10-CM code, or mesh_to_icd with a MeSH term. The returned mapping is a limited convenience crosswalk, not a substitute for a current licensed UMLS terminology service.

🖼️ Search biomedical images from NLM Open-i.

Searches medical/scientific images from Open-i 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

═══════════════════════════════════════════════════════════════ 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") 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) 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) hmp_type: History of Medicine publication type. Requires collection="hmd".

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

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: Bounded array of canonical tags (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 either source:

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

• Local-only file: "file:path/to/pipeline.yaml" (disabled for authenticated service callers)

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.

Permanently delete a saved pipeline configuration and execution history.

For the default tenant, any process-level schedule is removed only after the stored pipeline deletion succeeds. Isolated tenants never mutate the shared process scheduler.

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: Required 5-field cron expression. Example: "0 9 * * 1" (Mon 9am). 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.

Remove the active schedule for a saved pipeline.

Args: name: Saved pipeline name whose schedule will be removed.

Returns: Removed schedule metadata, or a native MCP error when none exists.

Read session data through one schema-exact discriminated request.

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

• search_runs: list durable unified_search run envelopes

• search_run: read one run by stable run_id

• replay_search: return credential-free unified_search replay arguments

Each action accepts only its own fields. For remote artifact reads, select an artifact_id or artifact_uri locator and use artifact_file plus offset/max_chars to page through large files. Local paths remain redacted unless both include_local_paths and the server setting allow them.