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.

```bash
uv run scripts/clinical_trials_api.py search \
  --condition "<disease>" \
  --intervention "<drug_or_treatment>" \
  --status "<status>" \
  --phase "<phase>" \
  --age-group "<a