<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# NCI Tools Example Prompts

This guide provides example prompts for AI assistants to effectively use the NCI (National Cancer Institute) Clinical Trials Search API tools in BioMCP.

## Overview of NCI Tools

BioMCP integrates with the NCI Clinical Trials Search API to provide:

- **Organization Search & Lookup** - Find cancer research centers, hospitals, and trial sponsors
- **Intervention Search & Lookup** - Search for drugs, devices, procedures, and other interventions

These tools require an NCI API key from: https://clinicaltrialsapi.cancer.gov/

## Best Practices

### API Key Required

All example prompts in this guide should include your NCI API key. Add this to the end of each prompt:

```
"... my NCI API key is YOUR_API_KEY"
```

### Location Searches

**ALWAYS use city AND state together** when searching organizations by location. The NCI API has Elasticsearch limitations that cause errors with broad searches.

✅ **Good**: `nci_organization_searcher(city="Cleveland", state="OH")`
❌ **Bad**: `nci_organization_searcher(city="Cleveland")` or `nci_organization_searcher(state="OH")`

### API Parameter Notes

- The NCI APIs do not support offset-based pagination (`from` parameter)
- Organization location parameters use `org_` prefix (e.g., `org_city`, `org_state_or_province`)
- When using `size` parameter, the API may not return a `total` count

### Avoiding API Errors

- Use specific organization names when possible
- Combine multiple filters (name + type, city + state)
- Start with more specific searches, then broaden if needed

## Organization Tools

### Organization Search

#### Basic Organization Search

```
"Find cancer centers in California, my NCI API key is YOUR_API_KEY"
"Search for MD Anderson Cancer Center, my NCI API key is YOUR_API_KEY"
"List academic cancer research centers in New York, my NCI API key is YOUR_API_KEY"
"Find all NCI-designated cancer centers, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_organization_searcher(state="CA", organization_type="Academic")`

#### Organization by Location

**IMPORTANT**: Always use city AND state together to avoid API errors!

```
"Show me cancer treatment centers in Boston, MA, my NCI API key is YOUR_API_KEY"
"Find clinical trial sites in Houston, Texas, my NCI API key is YOUR_API_KEY"
"List all cancer research organizations in Cleveland, OH, my NCI API key is YOUR_API_KEY"
"Search for industry sponsors in San Francisco, CA, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_organization_searcher(city="Boston", state="MA")` ✓
**Never use**: `nci_organization_searcher(city="Boston")` ✗ or `nci_organization_searcher(state="MA")` ✗

#### Organization by Type

```
"Find all government cancer research facilities, my NCI API key is YOUR_API_KEY"
"List pharmaceutical companies running cancer trials, my NCI API key is YOUR_API_KEY"
"Show me academic medical centers conducting trials, my NCI API key is YOUR_API_KEY"
"Find community hospitals participating in cancer research, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_organization_searcher(organization_type="Industry")`

### Organization Details

```
"Get details about organization NCI-2011-03337, my NCI API key is YOUR_API_KEY"
"Show me contact information for this cancer center, my NCI API key is YOUR_API_KEY"
"What trials is this organization conducting? My NCI API key is YOUR_API_KEY"
"Give me the full profile of this research institution, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `organization_getter(organization_id="NCI-2011-03337")`

## Intervention Tools

### Intervention Search

#### Drug Search

```
"Find all trials using pembrolizumab, my NCI API key is YOUR_API_KEY"
"Search for PD-1 inhibitor drugs in trials, my NCI API key is YOUR_API_KEY"
"List all immunotherapy drugs being tested, my NCI API key is YOUR_API_KEY"
"Find trials using Keytruda or similar drugs, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_intervention_searcher(name="pembrolizumab", intervention_type="Drug")`

#### Device Search

```
"Search for medical devices in cancer trials, my NCI API key is YOUR_API_KEY"
"Find trials using surgical robots, my NCI API key is YOUR_API_KEY"
"List radiation therapy devices being tested, my NCI API key is YOUR_API_KEY"
"Show me trials with diagnostic devices, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_intervention_searcher(intervention_type="Device")`

#### Procedure Search

```
"Find surgical procedures in cancer trials, my NCI API key is YOUR_API_KEY"
"Search for minimally invasive surgery trials, my NCI API key is YOUR_API_KEY"
"List trials with radiation therapy procedures, my NCI API key is YOUR_API_KEY"
"Show me trials testing new biopsy techniques, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_intervention_searcher(intervention_type="Procedure")`

#### Other Interventions

```
"Find behavioral interventions for cancer patients, my NCI API key is YOUR_API_KEY"
"Search for dietary interventions in trials, my NCI API key is YOUR_API_KEY"
"List genetic therapy trials, my NCI API key is YOUR_API_KEY"
"Show me trials with exercise interventions, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_intervention_searcher(intervention_type="Behavioral")`

### Intervention Details

```
"Get full details about intervention INT123456, my NCI API key is YOUR_API_KEY"
"Show me the mechanism of action for this drug, my NCI API key is YOUR_API_KEY"
"Is this intervention FDA approved? My NCI API key is YOUR_API_KEY"
"What trials are using this intervention? My NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `intervention_getter(intervention_id="INT123456")`

## Biomarker Tools

### Biomarker Search

#### Basic Biomarker Search

```
"Find PD-L1 expression biomarkers, my NCI API key is YOUR_API_KEY"
"Search for EGFR mutations used in trials, my NCI API key is YOUR_API_KEY"
"List biomarkers tested by IHC, my NCI API key is YOUR_API_KEY"
"Find HER2 positive biomarkers, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_biomarker_searcher(name="PD-L1")`

#### Biomarker by Type

```
"Show me all reference gene biomarkers, my NCI API key is YOUR_API_KEY"
"Find branch biomarkers, my NCI API key is YOUR_API_KEY"
"List all biomarkers of type reference_gene, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_biomarker_searcher(biomarker_type="reference_gene")`

#### Important Note on Biomarker Types

The NCI API only supports two biomarker types:

- `reference_gene`: Gene-based biomarkers
- `branch`: Branch/pathway biomarkers

Note: The API does NOT support searching by gene symbol or assay type directly.

## NCI Disease Tools

### Disease Search

#### Basic Disease Search

```
"Find melanoma in NCI vocabulary, my NCI API key is YOUR_API_KEY"
"Search for lung cancer types, my NCI API key is YOUR_API_KEY"
"List breast cancer subtypes, my NCI API key is YOUR_API_KEY"
"Find official name for GIST, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_disease_searcher(name="melanoma")`

#### Disease with Synonyms

```
"Find all names for gastrointestinal stromal tumor, my NCI API key is YOUR_API_KEY"
"Search for NSCLC and all its synonyms, my NCI API key is YOUR_API_KEY"
"List all terms for triple-negative breast cancer, my NCI API key is YOUR_API_KEY"
"Find alternative names for melanoma, my NCI API key is YOUR_API_KEY"
```

**Expected tool usage**: `nci_disease_searcher(name="GIST", include_synonyms=True)`

## Combined Workflows

### Finding Trials at Specific Centers

```
"First find cancer centers in California, then show me their trials, my NCI API key is YOUR_API_KEY"
```

**Expected workflow**:

1. `nci_organization_searcher(state="CA")`
2. For each organization, search trials with that sponsor

### Drug Development Pipeline

```
"Search for CAR-T cell therapies and show me which organizations are developing them, my NCI API key is YOUR_API_KEY"
```

**Expected workflow**:

1. `nci_intervention_searcher(name="CAR-T", intervention_type="Biological")`
2. For each intervention, get details to see associated trials
3. Extract organization information from trial data

### Regional Cancer Research

```
"What cancer drugs are being tested in Boston area hospitals? My NCI API key is YOUR_API_KEY"
```

**Expected workflow**:

1. `nci_organization_searcher(city="Boston", state="MA")`
2. `trial_searcher(location="Boston, MA", source="nci")` with organization filters
3. Extract intervention information from trials

## Important Notes

### API Key Handling

All NCI tools require an API key. The tools will check for:

1. API key provided in the function call
2. `NCI_API_KEY` environment variable
3. User-provided key in their message (e.g., "my NCI API key is...")

### Synonym Support

The intervention searcher includes a `synonyms` parameter (default: True) that will search for:

- Drug trade names (e.g., "Keytruda" finds "pembrolizumab")
- Alternative spellings
- Related terms

### Pagination

Both search tools support pagination:

- `page`: Page number (1-based)
- `page_size`: Results per page (max 100)

### Organization Types

Valid organization types include:

- Academic
- Industry
- Government
- Community
- Network
- Other

### Intervention Types

Valid intervention types include:

- Drug
- Device
- Biological
- Procedure
- Radiation
- Behavioral
- Genetic
- Dietary
- Other

## Error Handling

Common errors and solutions:

1. **"NCI API key required"**: User needs to provide an API key
2. **"No results found"**: Try broader search terms or remove filters
3. **"Invalid organization/intervention ID"**: Verify the ID format
4. **Rate limiting**: The API has rate limits; wait before retrying
5. **"Search Too Broad" (Elasticsearch error)**: The search returns too many results
   - This happens when searching with broad criteria
   - **Prevention**: Always use city AND state together for location searches
   - Add organization name (even partial) to narrow results
   - Avoid searching by state alone or organization type alone


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->