Skip to content

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

"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

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

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

"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

"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

"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
  6. This happens when searching with broad criteria
  7. Prevention: Always use city AND state together for location searches
  8. Add organization name (even partial) to narrow results
  9. Avoid searching by state alone or organization type alone