Clinical Guidelines Search & Retrieval

Phase 0: Tool Verification (MANDATORY FIRST STEP)

Before searching, verify tools load:

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()
assert hasattr(tu.tools, 'NICE_Clinical_Guidelines_Search')

Correct call pattern (use either approach):

# Option A: direct attribute access
result = tu.tools.NICE_Clinical_Guidelines_Search(query='diabetes', limit=5)

# Option B: run_one_function
result = tu.run_one_function({'name': 'NICE_Clinical_Guidelines_Search', 'arguments': {'query': 'diabetes', 'limit': 5}})

Phase 1: Identify Query Strategy

Determine which tools to use based on the user's question:

Phase 2: Multi-Source Search

2.1 General Search (Use ≥3 databases)

NICE_Clinical_Guidelines_Search ⭐ (Best general source)

• Parameters: query (string, required), limit (integer, required)
• Returns: list directly (NOT wrapped in dict) — [{title, url, summary, content, date}, ...]
• Handle: result = tu.tools.NICE_Clinical_Guidelines_Search(...); isinstance(result, list)
• Example: NICE_Clinical_Guidelines_Search(query='type 2 diabetes management', limit=5)

GIN_Guidelines_Search ⭐ (Best multi-society aggregator)

• Parameters: query (string, required), limit (integer, required)
• Returns: list directly — [{title, url, description, source, organization}, ...]
• Example: GIN_Guidelines_Search(query='colorectal cancer screening', limit=5)

TRIP_Database_Guidelines_Search

• Parameters: query (string, required), limit (integer, required), search_type (string, required — must be 'guidelines')
• Returns: list directly — [{title, url, description, content, publication}, ...]
• Example: TRIP_Database_Guidelines_Search(query='diabetes', limit=5, search_type='guidelines')

WHO_Guidelines_Search ⚠️ (Limited relevance)

• Parameters: query (string, required), limit (integer, required)
• Returns: list directly — [{title, url, description, content, source}, ...]
• LIMITATION: Does not reliably filter by topic. May return unrelated recent WHO publications.
• Use for broad international queries; do not rely on for specific disease searches.
• Example: WHO_Guidelines_Search(query='diabetes', limit=5)

CMA_Guidelines_Search (Canadian)

• Parameters: query (string, required), limit (integer, required)
• Returns: list directly — [{title, url, description, content, date}, ...]
• Example: CMA_Guidelines_Search(query='diabetes', limit=5)

SIGN_search_guidelines (Scottish/UK)

• Parameters: query (string, required — NOT q), limit (integer, optional)
• Returns: list directly — [{number, title, topic, published, url}, ...]
• Example: SIGN_search_guidelines(query='diabetes', limit=5)

CTFPHC_search_guidelines (Canadian prevention)

• Parameters: query (string, required — NOT q), limit (integer, optional)
• Returns: list directly — [{title, url, year}, ...]
• Example: CTFPHC_search_guidelines(query='colorectal cancer', limit=5)

OpenAlex_Guidelines_Search

• Parameters: query (string, required), limit (integer, required), year_from (integer, optional), year_to (integer, optional)
• Returns: list directly — [{title, authors, institutions, year, doi}, ...]
• Example: OpenAlex_Guidelines_Search(query='diabetes management', limit=5) (year params optional)
• With years: OpenAlex_Guidelines_Search(query='diabetes management', limit=5, year_from=2020, year_to=2024)

EuropePMC_Guidelines_Search

• Parameters: query (string, required), limit (integer, required)
• Returns: list directly — [{title, pmid, pmcid, doi, authors}, ...]
• Note: May return loosely relevant results; use for literature discovery not definitive guidelines
• Example: EuropePMC_Guidelines_Search(query='diabetes guideline', limit=5)

PubMed_Guidelines_Search

• Parameters: query (string, required), limit (integer, required), api_key (string, optional — use '' for anonymous)
• Returns: list directly — [{title, pmid, pmcid, doi}, ...]
• Example: PubMed_Guidelines_Search(query='diabetes guideline', limit=5) (api_key optional)

2.2 Society-Specific Search

ADA Standards of Care (Diabetes)

ADA_list_standards_sections() — No parameters. Lists all 19 sections of ADA Standards of Care (2026).

• Returns list of section titles with PMIDs

ADA_search_standards(query, limit) — Search within ADA Standards.

• Returns: list — [{title, ...}]
• Note: Uses PubMed corporate author filter. Use broad medical terms, not specific phrases.
• ✅ Works: 'glycemic targets', 'pharmacologic approaches', 'cardiovascular risk'
• ❌ May fail: very specific phrases like 'first-line medication metformin'

ADA_get_standards_section(section_number) — Get metadata for a specific section.

• Returns dict with section abstract (not full PMC text)

AHA/ACC Cardiology

AHA_ACC_search_guidelines(query, limit) — Search AHA/ACC guidelines.

• Returns: list directly — [{title, ...}]
• Example: AHA_ACC_search_guidelines(query='heart failure management', limit=5)

AHA_list_guidelines(limit) / ACC_list_guidelines(limit) — List recent guidelines.

AHA_ACC_get_guideline(pmid) — Get full text of AHA/ACC guideline by PMID (via PMC).

• Returns dict with full text
• Example: AHA_ACC_get_guideline(pmid='37952199')

NCCN Oncology

NCCN_list_patient_guidelines(limit) — List all NCCN patient guideline resources (up to 74).

• Returns: list directly — [{cancer_type, url, category}, ...]
• ⚠️ Field is cancer_type, NOT title
• Use r[i]['cancer_type'] to get the cancer name, r[i]['url'] for URL

NCCN_search_guidelines(query, limit) — Search NCCN publications.

• Returns: list directly — [{title, ...}]
• Note: Returns PubMed abstracts of NCCN articles (JNCCN), not proprietary guideline text

NCCN_get_patient_guideline(url) — Get full text of a patient guideline.

• Parameter: url (string) — the full URL from NCCN_list_patient_guidelines
• Example: NCCN_get_patient_guideline(url='https://www.nccn.org/patientresources/patient-resources/guidelines-for-patients/guidelines-for-patients-details?patientGuidelineId=61')
• ⚠️ Do NOT pass an integer ID — pass the full URL string

MAGICapp Living Guidelines

MAGICapp_list_guidelines(limit) — List living guidelines.

• Returns: dict wrapped — r.get('data', []) gives the list
• ⚠️ Field is name, NOT title; use item['name'] for guideline title
• Use item['guidelineId'] for follow-up calls

MAGICapp_get_guideline(guideline_id) — Get full guideline details. MAGICapp_get_recommendations(guideline_id) — Get recommendations for a guideline. MAGICapp_get_sections(guideline_id) — Get sections.

NCI Resources ⚠️ (Research tools catalog, NOT clinical guidelines)

NCI_search_cancer_resources(q, size) — Search NCI Research Resources for Researchers (R4R).

• ⚠️ This is a catalog of bioinformatics tools, datasets, and lab instruments — NOT a clinical guidelines database
• Parameters: q (NOT query), size (NOT limit — use size for result count)
• Returns: dict — r.get('data', {}).get('results', []) gives the list
• Useful for: finding analysis tools, datasets, bioinformatics resources related to a cancer type
• Example: NCI_search_cancer_resources(q='colorectal cancer screening', size=5)

2.3 Pharmacogenomics Search (CPIC)

Recommended workflow for gene-drug queries:

Step 1: CPIC_get_gene_info(genesymbol='GENE')          → gene overview
Step 2: CPIC_get_gene_drug_pairs(genesymbol='GENE')    → all drug pairs + CPIC levels
Step 3: CPIC_list_guidelines(limit=50)                 → find guideline_id for gene+drug
Step 4: CPIC_get_recommendations(guideline_id=N)       → specific dosing recommendations
Step 5: CPIC_get_alleles(genesymbol='GENE')            → allele definitions

All CPIC tools return dict-wrapped: use r.get('data', []) to access results.

CPIC_get_gene_info(genesymbol) — Gene overview.

• Example: CPIC_get_gene_info(genesymbol='CYP2D6')

CPIC_get_gene_drug_pairs(genesymbol, limit) — All gene-drug interactions with CPIC levels.

• Returns: data = list of {genesymbol, drugid, cpiclevel, pgkbcalevel, usedforrecommendation, ...}
• cpiclevel A/B/C/D: A = strongest evidence

CPIC_list_guidelines(limit) — All CPIC guidelines.

• Returns: data = list of {name: 'GENE and Drug', guidelineId, url, ...}
• Use to find the guidelineId for a specific gene+drug pair

CPIC_get_recommendations(guideline_id, limit) — Get dosing recommendations.

• ⚠️ Parameter is guideline_id (integer), NOT genesymbol
• Workflow: first find guideline_id from CPIC_list_guidelines, then call this
• Example: CPIC_get_recommendations(guideline_id=100416, limit=20)
• Returns duplicate records per allele combination — deduplicate by phenotype before presenting

CPIC_get_alleles(genesymbol, limit) — Allele definitions.

• Use clinicalfunctionalstatus field (NOT functionalstatus which is always null)
• Example: CPIC_get_alleles(genesymbol='CYP2D6', limit=10)

CPIC_get_drug_info(drugname) — Drug details.

• Example: CPIC_get_drug_info(drugname='codeine')

CPIC_search_gene_drug_pairs(genesymbol, limit) — Search gene-drug pairs.

• ⚠️ Requires PostgREST filter syntax: genesymbol='eq.CYP2D6' (not just 'CYP2D6')
• Example: CPIC_search_gene_drug_pairs(genesymbol='eq.CYP2D6', limit=5)

2.4 Full-Text Retrieval

NICE_Guideline_Full_Text(url) — Get NICE guideline text.

• Use URL from NICE_Clinical_Guidelines_Search results
• Returns dict (may have empty data for some guidelines; try chapter URLs like .../chapter/Recommendations)

WHO_Guideline_Full_Text(url) — Get WHO guideline text.

• Note: Most WHO T2D content is in PDFs; tool may return PDF link not full text

AHA_ACC_get_guideline(pmid) — Get AHA/ACC guideline text via PMC.

Phase 3: Synthesize Results

3.1 Report Structure

# Clinical Guidelines: [Topic]

## Summary
[2-3 sentence overview of what guidelines say]

## Key Recommendations

### [Source 1: NICE/ADA/NCCN/etc.]
[Key recommendations with evidence grade, URL]

### [Source 2]
[Key recommendations]

## Pharmacogenomics (if applicable)
[CPIC phenotype-to-recommendation table]

## References
[All URLs cited]

3.2 Evidence Grading

• Grade A (ADA) / Class I (AHA) / Strong (SIGN) = high confidence
• Grade B/C = moderate confidence; Grade D / Consensus = expert opinion
• CPIC Level A = strongest PGx evidence; B = moderate; C/D = limited
• Note recommendation year — guidelines vary in currency (SIGN 2025, ADA 2026, NICE Feb 2026)

3.3 CPIC Recommendation Deduplication

CPIC returns multiple records for the same phenotype (one per allele combination). Before presenting:

seen_phenotypes = set()
unique_recs = []
for rec in recs:
    phenotype = rec.get('phenotype') or rec.get('lookupkey', '')
    if phenotype not in seen_phenotypes:
        seen_phenotypes.add(phenotype)
        unique_recs.append(rec)

Phase 4: Decision Logic

General disease guideline:

1. NICE (query, limit) — UK, high quality
2. GIN (query, limit) — multi-society aggregator ⭐ best for breadth
3. TRIP (query, limit, search_type='guidelines')
4. If cardiac → add AHA_ACC_search_guidelines
5. If cancer → add NCCN_search_guidelines + NCCN_list_patient_guidelines
6. If diabetes → add ADA_list_standards_sections + ADA_search_standards

Pharmacogenomics:

1. CPIC_get_gene_info(genesymbol) → overview
2. CPIC_get_gene_drug_pairs(genesymbol) → all drugs with CPIC levels
3. CPIC_list_guidelines(limit=50) → find guideline_id for target gene+drug
4. CPIC_get_recommendations(guideline_id=N) → specific recs (deduplicate by phenotype)

Full text retrieval:

1. Find guideline URL/PMID from search results
2. NICE URL → NICE_Guideline_Full_Text
3. AHA/ACC PMID → AHA_ACC_get_guideline
4. WHO URL → WHO_Guideline_Full_Text
5. NCCN patient guideline URL → NCCN_get_patient_guideline

Fallback strategy:

• If NICE returns empty → try TRIP or GIN
• If ADA returns 0 results → broaden query terms (e.g., 'pharmacologic approaches' instead of 'metformin first-line')
• If WHO returns irrelevant results → skip WHO, use GIN or EuropePMC instead
• If CPIC returns no recommendations → list gene-drug pairs with CPIC levels as a proxy

Critical Parameter Notes (Verified by Testing)

Response Format Reference

Known Limitations

• WHO_Guidelines_Search: Returns recently-published WHO docs regardless of query topic — results may be irrelevant for specific diseases. Supplement with GIN for international guidelines.
• NCI_search_cancer_resources: Catalogs research tools/datasets, NOT clinical practice guidelines.
• NICE_Guideline_Full_Text: Retrieves overview page only; recommendation sub-pages (.../chapter/Recommendations) may need direct URL
• SIGN: No full-text tool; guideline text only available as PDFs
• ADA_get_standards_section: Returns abstract only, not full PMC text
• CPIC_get_recommendations: Returns many duplicate records per allele combination; deduplicate by phenotype
• NCCN_search_guidelines: Returns PubMed/JNCCN abstracts, not proprietary NCCN guideline text
• TRIP content: Some TRIP results link to PDF-gated URLs; content extraction may fail with 403

Missing Sources (Potential Future Tools)

• USPSTF (US Preventive Services Task Force) — primary US screening recommendations
• ACG (American College of Gastroenterology) — gastroenterology guidelines
• AGA (American Gastroenterological Association)
• Cochrane Reviews — systematic reviews on clinical interventions
• AHRQ — Agency for Healthcare Research and Quality