Clinical Guidelines Search & Retrieval

Search and retrieve evidence-based clinical practice guidelines from 12+ authoritative sources spanning 41 tools. Covers disease management guidelines, society recommendations, pharmacogenomics guidance, and patient resources.

KEY PRINCIPLES:

1. Multi-source search — Search ≥3 databases in parallel for comprehensive coverage
2. Source-appropriate queries — Match query style to each database's strengths
3. Condition + society specific — When user names a disease or society, use targeted tools
4. English queries first — Use English medical terms in all tool calls; respond in user's language
5. Cite sources — Every guideline result must include source organization and URL

When to Use

Apply when user asks:

• "What are the guidelines for [condition]?"
• "What does [ADA/AHA/NCCN/NICE/WHO] say about [topic]?"
• "Standard of care for [disease]?"
• "Drug-gene interactions for [drug/gene]?" (pharmacogenomics)
• "Screening recommendations for [condition]?"
• "Is there a guideline for [clinical question]?"
• "What do guidelines say about [treatment/drug]?"
• "Clinical recommendations for [oncology topic]?"

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()

• Returns list of section titles with PMIDs

ADA_search_standards(query, limit)

• 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)

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

AHA/ACC Cardiology

AHA_ACC_search_guidelines(query, limit)

• Returns: list directly —

  [{title, ...}]

• Example:

  AHA_ACC_search_guidelines(query='heart failure management', limit=5)

AHA_list_guidelines(limit)

ACC_list_guidelines(limit)

AHA_ACC_get_guideline(pmid)

• Returns dict with full text
• Example:

  AHA_ACC_get_guideline(pmid='37952199')

NCCN Oncology

NCCN_list_patient_guidelines(limit)

• 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)

• Returns: list directly —

  [{title, ...}]

• Note: Returns PubMed abstracts of NCCN articles (JNCCN), not proprietary guideline text

NCCN_get_patient_guideline(url)

• 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)

• 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)

MAGICapp_get_recommendations(guideline_id)

MAGICapp_get_sections(guideline_id)

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

NCI_search_cancer_resources(q, size)

• ⚠️ 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', [])

CPIC_get_gene_info(genesymbol)

• Example:

  CPIC_get_gene_info(genesymbol='CYP2D6')

CPIC_get_gene_drug_pairs(genesymbol, limit)

• Returns:

  data

  = list of

  {genesymbol, drugid, cpiclevel, pgkbcalevel, usedforrecommendation, ...}

• cpiclevel

  A/B/C/D: A = strongest evidence

CPIC_list_guidelines(limit)

• 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)

• ⚠️ 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)

• Use

  clinicalfunctionalstatus

  field (NOT

  functionalstatus

  which is always null)
• Example:

  CPIC_get_alleles(genesymbol='CYP2D6', limit=10)

CPIC_get_drug_info(drugname)

• Example:

  CPIC_get_drug_info(drugname='codeine')

CPIC_search_gene_drug_pairs(genesymbol, limit)

• ⚠️ 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)

• 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)

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

AHA_ACC_get_guideline(pmid)

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)

query='...'

limit=N

q='...'

search_type='guidelines'

year_from

year_to

api_key

''

limit=N

limit=N

query='...'

q

q='...'

query='...'

q

q='...'

q='...'

size=N

limit

query=...

limit=N

cancer_type

title

.get('title')

url='https://...'

r.get('data', [])

r

name

title

.get('title')

r.get('data', [])

r

guideline_id=N

genesymbol='CYP2D6'

genesymbol='eq.CYP2D6'

genesymbol='CYP2D6'

clinicalfunctionalstatus

functionalstatus

r.get('data',{}).get('results',[])

r.get('data', [])

Response Format Reference

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['title']

result[0]['cancer_type']

result[0]['title']

data

r.get('data', [])[0]['name']

data

r.get('data', [])[0]['genesymbol']

data

r.get('data', [])[0]

data

r.get('data', {})

data

r.get('data', [])[0]['name']

r.get('data',{}).get('results',[])[0]['title']

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