BioMCP

Instructions

Retrieves detailed outcome information including:
- Primary outcome measures
- Secondary outcome measures
- Results data (if available)
- Adverse events (if reported)

Note: Results are only available for completed trials that have posted data.

Implementation Reference

• src/biomcp/individual_tools.py:407-429 (handler)

  MCP tool handler function 'trial_outcomes_getter'. This is the main entrypoint registered with the MCP server. It defines the tool schema via Annotated parameters, handles the tool call, passes a call_benefit, and delegates to the core _trial_outcomes implementation.

  @mcp_app.tool()
  @track_performance("biomcp.trial_outcomes_getter")
  async def trial_outcomes_getter(
      nct_id: Annotated[
          str,
          Field(description="NCT ID (e.g., 'NCT06524388')"),
      ],
  ) -> str:
      """Fetch outcome measures and results for a clinical trial.
  
      Retrieves detailed outcome information including:
      - Primary outcome measures
      - Secondary outcome measures
      - Results data (if available)
      - Adverse events (if reported)
  
      Note: Results are only available for completed trials that have posted data.
      """
      return await _trial_outcomes(
          call_benefit="Fetch trial outcome measures and results for efficacy assessment",
          nct_id=nct_id,
      )

• src/biomcp/trials/getter.py:176-198 (helper)

  Core helper function _trial_outcomes that fetches outcomes data from ClinicalTrials.gov API using the shared get_trial function with Outcomes module. This contains the domain-specific logic invoked by the tool handler.

  async def _trial_outcomes(
      call_benefit: Annotated[
          str,
          "Define and summarize why this function is being called and the intended benefit",
      ],
      nct_id: str,
  ) -> str:
      """
      Retrieves outcome measures, results (if available), and
      adverse event data for a single clinical trial.
  
      Parameters:
      - call_benefit: Define and summarize why this function is being called and the intended benefit
      - nct_id: A single NCT ID (string, e.g., "NCT04280705")
  
      Process: Fetches the `OutcomesModule` and `ResultsSection`
               from the ClinicalTrials.gov v2 API for the NCT ID.
      Output: A Markdown formatted string detailing primary/secondary
              outcomes, participant flow, results tables (if posted),
              and adverse event summaries. Returns an error if invalid.
      """
      return await get_trial(nct_id, Module.OUTCOMES)

• src/biomcp/trials/getter.py:52-125 (helper)

  Shared helper function get_trial that performs the actual HTTP request to ClinicalTrials.gov API, parses the response, handles errors, and renders to Markdown. Used by all trial section getters including outcomes.

  async def get_trial(
      nct_id: str,
      module: Module = Module.PROTOCOL,
      output_json: bool = False,
  ) -> str:
      """Get details of a clinical trial by module."""
      fields = ",".join(modules[module])
      params = {"fields": fields}
      url = f"{CLINICAL_TRIALS_BASE_URL}/{nct_id}"
  
      logger.debug(f"Fetching trial {nct_id} with module {module.value}")
      logger.debug(f"URL: {url}, Params: {params}")
  
      parsed_data: dict[str, Any] | None
      error_obj: http_client.RequestError | None
      parsed_data, error_obj = await http_client.request_api(
          url=url,
          request=params,
          method="GET",
          tls_version=TLSVersion.TLSv1_2,
          response_model_type=None,
          domain="clinicaltrials",
      )
  
      data_to_return: dict[str, Any]
  
      if error_obj:
          logger.error(
              f"API Error for {nct_id}: {error_obj.code} - {error_obj.message}"
          )
          data_to_return = {
              "error": f"API Error {error_obj.code}",
              "details": error_obj.message,
          }
      elif parsed_data:
          # ClinicalTrials.gov API returns data wrapped in a "studies" array
          # Extract the first study if it exists
          if isinstance(parsed_data, dict) and "studies" in parsed_data:
              studies = parsed_data.get("studies", [])
              if studies and len(studies) > 0:
                  data_to_return = studies[0]
                  data_to_return["URL"] = (
                      f"https://clinicaltrials.gov/study/{nct_id}"
                  )
              else:
                  logger.warning(f"No studies found in response for {nct_id}")
                  data_to_return = {
                      "error": f"No studies found for {nct_id}",
                      "details": "API returned empty studies array",
                  }
          else:
              # Handle case where API returns data in unexpected format
              logger.debug(
                  f"Unexpected response format for {nct_id}: {type(parsed_data)}"
              )
              data_to_return = parsed_data
              data_to_return["URL"] = (
                  f"https://clinicaltrials.gov/study/{nct_id}"
              )
      else:
          logger.warning(
              f"No data received for {nct_id} with module {module.value}"
          )
          data_to_return = {
              "error": f"No data found for {nct_id} with module {module.value}",
              "details": "API returned no data",
          }
  
      if output_json:
          return json.dumps(data_to_return, indent=2)
      else:
          return render.to_markdown(data_to_return)

• src/biomcp/individual_tools.py:24-30 (registration)

  Import statement that brings in the core trial getter functions, including _trial_outcomes, for use by the MCP tool handlers.

  from biomcp.trials.getter import (
      _trial_locations,
      _trial_outcomes,
      _trial_protocol,
      _trial_references,
  )
  from biomcp.trials.search import _trial_searcher

• src/biomcp/individual_tools.py:410-412 (schema)

  Pydantic schema definition for the tool input parameter 'nct_id' via Annotated Field.

  nct_id: Annotated[
      str,
      Field(description="NCT ID (e.g., 'NCT06524388')"),