/clinical_trials_database

name: clinical-trials-database
description: >
  Query ClinicalTrials.gov via APIv2. Use when you want to search for trials by
  condition, drug, location, status, or phase; retrieve trial details by NCT ID;
  check eligibility/inclusion criteria; count trials across conditions or time
  periods; identify a sponsor's trial portfolio; find recruiting trials for
  patient matching.

Clinical Trials Database

Prerequisites

1. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure `uv` is installed and on PATH. 2. **User Notification**: If .licenses/clinical_trials_database_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://clinicaltrials.gov/, then (2) create the file recording the notification text and timestamp.

Overview

Access worldwide clinical trial data from ClinicalTrials.gov via the REST API v2. The CLI script at `scripts/clinical_trials_api.py` wraps the API with dedicated flags for common filters (phase, age group, status, intervention, sponsor, etc.) so you rarely need to construct raw queries.

Core Rules

• **Use the Wrapper**: ALWAYS execute the provided helper scripts to query the

database rather than accessing the database directly. The scripts automatically enforce the required rate limit gracefully.

• **Always use `--fields`** — trial JSON records can be very large; restrict

to the data points you need.

• **Use `--count-total` first** — check result volume before fetching all

records.

• **Paginate large result sets** — use `--limit` with `--page-token` to

iterate.

• **Trust Search Filters**: Do not manually re-filter results unless

explicitly asked to verify detailed eligibility.

• **Notification**: If this skill is used, ensure this is mentioned in the

output.

Context Efficiency Warning

Trial JSON records can be very large. **Always** use the `--fields` parameter to restrict the response to only the data points you need. After writing to file, read only the fields you need rather than the entire file.

> [!TIP] Use `references/studies_schema.md` to identify exact field paths for > `--fields`.

Response Layout Summary

API responses contain a list of studies (usually in a `studies[]` array). Each study is split into `protocolSection` and optional `resultsSection`.

> [!Tip] Use the **shorthand aliases** below with the `--fields` parameter to > request specific data and keep responses small.

Top-Level Fields

• `totalCount` — Total studies matching query (integer)
• `studies[]` — Array of study objects
• `nextPageToken` — cursor string for pagination

Common Study Fields (and shorthand alias)

• **Identification**
• `protocolSection.identificationModule.nctId` (`NCTId`) — Unique trial ID
• `protocolSection.identificationModule.briefTitle` (`BriefTitle`) — Short

title

• **Status**
• `protocolSection.statusModule.overallStatus` (`OverallStatus`) —

Recruitment status

• **Description**
• `protocolSection.descriptionModule.briefSummary` (`BriefSummary`) —

Short description

• **Arms & Interventions**
• `protocolSection.armsInterventionsModule.interventions`

(`ArmsInterventionsModule`)

• **Eligibility**
• `protocolSection.eligibilityModule.eligibilityCriteria`

(`EligibilityCriteria`) — Inclusion/Exclusion

• `protocolSection.eligibilityModule.stdAges` (`StdAge`) — CHILD, ADULT,

etc.

Consult `references/studies_schema.md` for full paths (Locations, Outcomes, Results) and common `--fields` recipes.

Commands

Search for studies

Use for: finding trials by disease, drug, phase, status, age group, or any combination of these filters.

uv run scripts/clinical_trials_api.py search \
  --condition "<disease>" \
  --intervention "<drug_or_treatment>" \
  --status "<status>" \
  --phase "<phase>" \
  --age-group "<age_group>" \
  --study-type "<study_type>" \
  --sponsor "<sponsor_name>" \
  --has-results \
  --sort "<field>:<asc|desc>" \
  --fields "<fields>" \
  --limit <N> \
  --count-total \
  --page-token "<token>" \
  --output /tmp/search_results.json

All flags are optional and combine via AND logic.

**Flag reference:**

• `--condition` — Disease or condition to search for (e.g. `"cystic

fibrosis"`).

• `--intervention` — Drug, device, or treatment name (e.g. `"pembrolizumab"`).
• `--status` — Recruitment status filter. Values: RECRUITING, COMPLETED,

NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION, TERMINATED, SUSPENDED, WITHDRAWN.

• `--phase` — Trial phase filter. Values: PHASE1, PHASE2, PHASE3, PHASE4,

EARLY_PHASE1, NA.

• `--age-group` — Patient age group filter. Values: CHILD (0–17), ADULT

(18–64), OLDER_ADULT (65+).

• `--study-type` — Type of study. Values: INTERVENTIONAL, OBSERVATIONAL,

EXPANDED_ACCESS.

• `--sponsor` — Lead sponsor or institution name (e.g. `"National Cancer

Institute"`).

• `--has-results` — Boolean flag (no value needed). When present, filters for

studies that have results available on ClinicalTrials.gov.

• `--sort` — Sort order as `FieldName:asc` or `FieldName:desc`. Common fields:

`LastUpdatePostDate`, `EnrollmentCount`, `StudyFirstPostDate`, `StartDate`.

• `--fields` — Comma-separated list of JSON field names to include in the

response. Use this to keep responses small (e.g. `"NCTId,BriefTitle,OverallStatus,Phase"`). See `references/studies_schema.md` for available field paths.

• `--limit` — Maximum number of studies to return per request (1–1000, default

10).

• `--count-total` — Boolean flag (no value needed). When present, the response

includes a `totalCount` field showing the total number of matching studies across all pages.

• `--page-token` — An opaque cursor string used to fetch the next page of

results. Obtain this value from