1. uv

   : Read the

   uv

   skill and follow its Setup instructions to ensure

   uv

   is installed and on PATH.
2. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill 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.

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

--fields

[!TIP] Use

references/studies_schema.md

to identify exact field paths for

--fields

.

studies[]

protocolSection

resultsSection

[!Tip] Use the shorthand aliases below with the

--fields

parameter to request specific data and keep responses small.

• totalCount

  — Total studies matching query (integer)

• studies[]

  — Array of study objects

• nextPageToken

  — cursor string for pagination

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

references/studies_schema.md

--fields

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

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

  nextPageToken

  field in a previous search response. Do not construct this string yourself; always copy it verbatim from the API response. See the Pagination section below.

• --advanced

  — Raw Essie filter expression for structured queries beyond the dedicated flags (e.g.

  "AREA[LocationCountry]United States"

  ). Combined with other flags via AND. See

  references/clinical_trials_api.md

  for syntax.

• --output

  — (Required) File path where the JSON response is written.

uv run scripts/clinical_trials_api.py search \
  --condition "cystic fibrosis" \
  --status RECRUITING \
  --phase PHASE3 \
  --age-group CHILD \
  --fields "NCTId,BriefTitle,OverallStatus,Phase" \
  --limit 10 \
  --output /tmp/cf_trials.json

uv run scripts/clinical_trials_api.py search \
  --condition "esophageal cancer" \
  --intervention "Atezolizumab" \
  --status RECRUITING \
  --fields "NCTId,BriefTitle,Phase" \
  --limit 10 \
  --output /tmp/atezolizumab_trials.json

--advanced

• AREA[Field]Value

  : Targets a specific field.

  • AREA[LocationCountry]United States

  • AREA[Phase]PHASE3

• Boolean operators: Combine with

  AND

  ,

  OR

  ,

  NOT

  .

• RANGE[min, max]

  : For numeric/date fields (e.g.

  RANGE[500, MAX]

  ).

references/clinical_trials_api.md

uv run scripts/clinical_trials_api.py search \
  --condition "diabetes" \
  --advanced "AREA[LocationCountry]United States \
    AND AREA[EnrollmentCount]RANGE[500, MAX]" \
  --fields "NCTId,BriefTitle,EnrollmentCount" \
  --output /tmp/diabetes_us_large.json

• API parameters, enum values, and Essie syntax:

  references/clinical_trials_api.md

• JSON field paths and

  --fields

  recipes:

  references/studies_schema.md