Lifesciences Clinical

Clinical & Translational API Skills

Query clinical databases via MCP tools (primary) or curl (fallback).

Grounding Rule

All target-disease associations, drug names, trial IDs, and clinical data MUST come from API results. Do NOT provide NCT IDs, trial statuses, or drug-disease associations from training knowledge. If a query returns no results, report "No results found."

MCP Token Budgeting (slim Parameter)

All MCP tools in this skill support a slim parameter for token-efficient queries:

When to use slim=true:

• LOCATE phase: Fast candidate lists (returns ~20 tokens/entity vs ~115-300 tokens)
• Batch operations: Resolving multiple entities in a single turn
• Exploration: Quick overviews without full metadata

When to use slim=false (default):

• RETRIEVE phase: Need full metadata with cross-references
• Validation: Verifying detailed properties
• Graph persistence: Collecting complete entity records

Example:

# LOCATE: Find top 10 gene candidates (slim=true for speed)
Call `hgnc_search_genes` with: {"query": "TNF", "slim": true, "page_size": 10}
→ Returns minimal fields: ID, symbol, name only (~20 tokens each)

# RETRIEVE: Get full record for validation (slim=false, default)
Call `hgnc_get_gene` with: {"hgnc_id": "HGNC:11892"}
→ Returns complete metadata with cross-references (~115 tokens)

Impact: Using slim=true during LOCATE enables 5-10x more entities per LLM turn without context overflow.

Reference: This token budgeting pattern is detailed in reference/prior-art-api-patterns.md (Section 7.1).

LOCATE → RETRIEVE Patterns

Open Targets: Target-Disease Associations

LOCATE: Search for target or disease

PRIMARY (MCP tool):

Call `opentargets_search_targets` with: {"query": "breast cancer"}
→ Returns: target/disease IDs and names

FALLBACK (curl):

curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ search(queryString: \"breast cancer\", entityNames: [\"disease\"]) { hits { id name } } }"}' \
  | jq '.data.search.hits[:3]'

RETRIEVE: Get diseases associated with target

PRIMARY (MCP tool):

Call `opentargets_get_associations` with: {"ensembl_id": "ENSG00000141510"}
→ Returns: associated diseases with scores and evidence types

FALLBACK (curl):

curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ target(ensemblId: \"ENSG00000141510\") { approvedSymbol associatedDiseases(page: {index: 0, size: 5}) { rows { disease { id name } score } } } }"}' \
  | jq '.data.target.associatedDiseases.rows[] | {disease: .disease.name, id: .disease.id, score}'

Open Targets: Target Tractability — curl only

RETRIEVE: Get druggability assessment

curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ target(ensemblId: \"ENSG00000141510\") { approvedSymbol biotype tractability { label modality value } } }"}' \
  | jq '.data.target | {symbol: .approvedSymbol, tractability}'

Open Targets: Known Drugs for Target

LOCATE: Find approved drugs targeting a protein

PRIMARY (MCP tool):

Call `opentargets_get_target` with: {"ensembl_id": "ENSG00000171791"}
→ Returns: knownDrugs with drug name, phase, mechanismOfAction

FALLBACK (curl):

curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ target(ensemblId: \"ENSG00000171791\") { approvedSymbol knownDrugs(page: {index: 0, size: 5}) { rows { drug { name id } phase mechanismOfAction } } } }"}' \
  | jq '.data.target.knownDrugs.rows[] | {drug: .drug.name, phase, mechanism: .mechanismOfAction}'

Note: Always include index: 0 in pagination — omitting it causes errors.

Open Targets: All-in-One Nested Query — curl only

RETRIEVE: Get target + diseases + drugs + tractability in single call

curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{
      target(ensemblId: \"ENSG00000141510\") {
        approvedSymbol
        biotype
        tractability { label value }
        knownDrugs(page: {index: 0, size: 3}) {
          rows { drug { name } phase mechanismOfAction }
        }
        associatedDiseases(page: {index: 0, size: 3}) {
          rows { disease { name id } score }
        }
      }
    }"
  }' | jq '.data.target'

Open Targets: Disease-Centric Queries — curl only

RETRIEVE: Get targets associated with disease

curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ disease(efoId: \"EFO_0000305\") { name associatedTargets(page: {index: 0, size: 5}) { rows { target { approvedSymbol } score } } } }"}' \
  | jq '.data.disease.associatedTargets.rows[] | {target: .target.approvedSymbol, score}'

ClinicalTrials.gov API v2

LOCATE: Search Clinical Trials

By condition:

PRIMARY (MCP tool):

Call `clinicaltrials_search_trials` with: {"query": "breast cancer"}
→ Returns: NCT IDs, titles, phases, statuses

FALLBACK (curl):

curl -s "https://clinicaltrials.gov/api/v2/studies?query.cond=breast+cancer&pageSize=3&format=json" \
  | jq '.studies[] | {nct: .protocolSection.identificationModule.nctId, title: .protocolSection.identificationModule.briefTitle, status: .protocolSection.statusModule.overallStatus}'

By intervention (drug):

PRIMARY (MCP tool):

Call `clinicaltrials_search_trials` with: {"query": "venetoclax"}

FALLBACK (curl):

curl -s "https://clinicaltrials.gov/api/v2/studies?query.intr=venetoclax&pageSize=3&format=json" \
  | jq '.studies[] | {nct: .protocolSection.identificationModule.nctId, phase: .protocolSection.designModule.phases, status: .protocolSection.statusModule.overallStatus}'

By status (curl only — more parameter control):

curl -s "https://clinicaltrials.gov/api/v2/studies?filter.overallStatus=RECRUITING&query.cond=leukemia&pageSize=3&format=json" \
  | jq '.studies[] | {nct: .protocolSection.identificationModule.nctId, title: .protocolSection.identificationModule.briefTitle}'

By study type (use query.term with AREA syntax — filter.studyType is NOT valid in v2):

curl -s "https://clinicaltrials.gov/api/v2/studies?query.term=AREA[StudyType]INTERVENTIONAL&query.cond=cancer&pageSize=3&format=json" \
  | jq '.studies[] | {nct: .protocolSection.identificationModule.nctId}'

RETRIEVE: Get Trial Details

By NCT ID:

PRIMARY (MCP tool):

Call `clinicaltrials_get_trial` with: {"nct_id": "NCT00461032"}
→ Returns: title, status, phase, conditions, interventions

FALLBACK (curl):

curl -s "https://clinicaltrials.gov/api/v2/studies/NCT00461032?format=json" \
  | jq '{
    nct: .protocolSection.identificationModule.nctId,
    title: .protocolSection.identificationModule.briefTitle,
    status: .protocolSection.statusModule.overallStatus,
    phase: .protocolSection.designModule.phases,
    conditions: .protocolSection.conditionsModule.conditions,
    interventions: [.protocolSection.armsInterventionsModule.interventions[]?.name]
  }'

RETRIEVE: Get Trial Locations

PRIMARY (MCP tool):

Call `clinicaltrials_get_trial_locations` with: {"nct_id": "NCT00461032"}
→ Returns: trial site locations

FALLBACK (curl):

curl -s "https://clinicaltrials.gov/api/v2/studies/NCT00461032?format=json" \
  | jq '.protocolSection.contactsLocationsModule.locations[:5]'

Quick Reference

ClinicalTrials.gov v2 Valid Parameters

Invalid: filter.studyType does NOT exist in v2 API.

ID Format Reference

Common Workflows

Drug Target Validation Pipeline

# Step 1: RETRIEVE — Get target-disease association score (MCP)
Call `opentargets_get_associations` with: {"ensembl_id": "ENSG00000171791"}

# Step 2: RETRIEVE — Check tractability (curl — no MCP tool for this)
curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ target(ensemblId: \"ENSG00000171791\") { tractability { label modality value } } }"}' \
  | jq '.data.target.tractability'

# Step 3: LOCATE — Find clinical trials (MCP)
Call `clinicaltrials_search_trials` with: {"query": "BCL2 RECRUITING"}

Disease → Targets → Drugs → Trials (Full Chain)

# Step 1: LOCATE — Find top targets for disease (curl — disease-centric query)
curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ disease(efoId: \"EFO_0000574\") { name associatedTargets(page: {index: 0, size: 3}) { rows { target { approvedSymbol ensemblId: id } score } } } }"}'

# Step 2: LOCATE — Get drugs for top target (MCP)
Call `opentargets_get_target` with: {"ensembl_id": "ENSG00000171791"}

# Step 3: LOCATE — Find trials for drug (MCP)
Call `clinicaltrials_search_trials` with: {"query": "venetoclax leukemia RECRUITING"}

Fallback Patterns

Rate Limits

Pitfalls

• Open Targets requires Ensembl Gene IDs (ENSG*) for target queries; use EFO IDs for disease queries.
• Always include index: 0 in Open Targets pagination: page: {index: 0, size: N}.
• ClinicalTrials.gov uses Cloudflare protection that may block Python httpx clients. Use curl for reliable access.
• filter.studyType is NOT valid in v2 API. Use query.term=AREA[StudyType]INTERVENTIONAL.

See Also

• lifesciences-graph-builder: Orchestrator for full Fuzzy-to-Fact protocol
• lifesciences-pharmacology: ChEMBL, PubChem drug endpoints