bc_get_study_details
Retrieve comprehensive clinical trial details including study design, eligibility criteria, outcomes, locations, and contacts using an NCT ID.
Instructions
Get complete trial details by NCT ID. Retrieves study design, eligibility, outcomes, locations, contacts, and metadata.
Returns: dict: Study details with protocol sections including identification, status, sponsors, description, conditions, design, interventions, outcomes, eligibility, locations or error message.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nct_id | Yes | NCT ID (e.g., 'NCT01234567') | |
| fields | No | Comma-separated fields or 'all' for complete data. Default includes key modules. | IdentificationModule,StatusModule,SponsorCollaboratorsModule,DescriptionModule,ConditionsModule,DesignModule,ArmsInterventionsModule,OutcomesModule,EligibilityModule,ContactsLocationsModule |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The handler function implementing bc_get_study_details (prefixed from get_study_details). Fetches detailed information for a clinical trial by NCT ID from ClinicalTrials.gov API v2, with input validation and error handling.
@core_mcp.tool() def get_study_details( nct_id: Annotated[str, Field(description="NCT ID (e.g., 'NCT01234567')")], fields: Annotated[ str, Field(description="Comma-separated fields or 'all' for complete data. Default includes key modules.") ] = "IdentificationModule,StatusModule,SponsorCollaboratorsModule,DescriptionModule,ConditionsModule,DesignModule,ArmsInterventionsModule,OutcomesModule,EligibilityModule,ContactsLocationsModule", ) -> Union[Dict[str, Any], dict]: """Get complete trial details by NCT ID. Retrieves study design, eligibility, outcomes, locations, contacts, and metadata. Returns: dict: Study details with protocol sections including identification, status, sponsors, description, conditions, design, interventions, outcomes, eligibility, locations or error message. """ if not nct_id: return {"error": "NCT ID must be provided"} # Validate NCT ID format (should start with NCT followed by 8 digits) if not nct_id.upper().startswith("NCT") or len(nct_id) != 11: return {"error": "Invalid NCT ID format. Expected format: NCT12345678"} # Construct URL if fields.lower() == "all": url = f"https://clinicaltrials.gov/api/v2/studies/{nct_id}?format=json" else: url = f"https://clinicaltrials.gov/api/v2/studies/{nct_id}?fields={fields}&format=json" try: response = requests.get(url) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: if response.status_code == 404: return {"error": f"Study with NCT ID '{nct_id}' not found"} return {"error": f"Failed to fetch study details: {e!s}"} - src/biocontext_kb/core/_server.py:1-6 (registration)Defines the core_mcp FastMCP server instance named 'BC'. Tool functions decorated with @core_mcp.tool() are registered here. Later imported into main app with 'bc' prefix.
from fastmcp import FastMCP core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", ) - src/biocontext_kb/core/clinicaltrials/__init__.py:1-13 (registration)Imports the get_study_details function, triggering its @core_mcp.tool() decorator to register the tool in core_mcp.
from ._get_recruiting_studies_by_location import get_recruiting_studies_by_location from ._get_studies_by_condition import get_studies_by_condition from ._get_studies_by_intervention import get_studies_by_intervention from ._get_study_details import get_study_details from ._search_studies import search_studies __all__ = [ "get_recruiting_studies_by_location", "get_studies_by_condition", "get_studies_by_intervention", "get_study_details", "search_studies", ] - src/biocontext_kb/app.py:35-39 (registration)Imports core_mcp into the main mcp_app, prefixing all its tools with 'bc' (slugify('BC')). This creates the 'bc_get_study_details' tool in the final server.
for mcp in [core_mcp, *(await get_openapi_mcps())]: await mcp_app.import_server( mcp, slugify(mcp.name), ) - src/biocontext_kb/core/__init__.py:7-7 (registration)Imports all clinicaltrials tools (including get_study_details) into core namespace, ensuring registration.
from .clinicaltrials import *