bc_count_drugs_by_field

Instructions

Implementation Reference

• src/biocontext_kb/core/openfda/_count_drugs.py:9-53 (handler)

  The handler function decorated with @core_mcp.tool() that executes the bc_count_drugs_by_field tool logic. It calls the FDA Drugs@FDA API with count parameter to get unique value counts for a given field, with support for search filtering and limit control.

  @core_mcp.tool()
  def count_drugs_by_field(
      field: Annotated[
          str,
          Field(
              description="Field to count (e.g., 'sponsor_name', 'products.dosage_form', 'products.route', 'openfda.pharm_class_epc')"
          ),
      ],
      search_filter: Annotated[
          Optional[str], Field(description="Optional search filter to apply before counting")
      ] = None,
      limit: Annotated[int, Field(description="Maximum number of count results to return", ge=1, le=1000)] = 100,
  ) -> dict:
      """Count unique values in a field across FDA-approved drugs. Useful for statistical analysis.
  
      Returns:
          dict: Results array with term and count for each unique value or error message.
      """
      # If field is an array, use .exact for correct counting
      array_fields = [
          "openfda.brand_name",
          "openfda.generic_name",
          "openfda.manufacturer_name",
          "openfda.pharm_class_epc",
          "openfda.pharm_class_moa",
          "openfda.pharm_class_pe",
          "openfda.pharm_class_cs",
          "products.brand_name",
      ]
      count_field = field + ".exact" if field in array_fields and not field.endswith(".exact") else field
      url_params = {"count": count_field, "limit": limit}
  
      # Add search filter if provided
      if search_filter:
          url_params["search"] = search_filter
  
      # Build the complete URL
      base_url = "https://api.fda.gov/drug/drugsfda.json"
  
      try:
          response = requests.get(base_url, params=url_params)  # type: ignore
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch FDA drug count data: {e!s}"}

• src/biocontext_kb/core/openfda/_count_drugs.py:11-20 (schema)

  Input schema/type definitions for the count_drugs_by_field tool: field (str, required), search_filter (Optional[str], optional), limit (int, optional, 1-1000, default 100).

  field: Annotated[
      str,
      Field(
          description="Field to count (e.g., 'sponsor_name', 'products.dosage_form', 'products.route', 'openfda.pharm_class_epc')"
      ),
  ],
  search_filter: Annotated[
      Optional[str], Field(description="Optional search filter to apply before counting")
  ] = None,
  limit: Annotated[int, Field(description="Maximum number of count results to return", ge=1, le=1000)] = 100,

• src/biocontext_kb/core/openfda/__init__.py:6-6 (registration)

  Re-export of count_drugs_by_field from the _count_drugs module in the openfda package.

  from ._count_drugs import count_drugs_by_field, get_drug_statistics

• src/biocontext_kb/core/_server.py:3-6 (registration)

  The FastMCP server instance (core_mcp) that the tool is registered on via @core_mcp.tool() decorator.

  core_mcp = FastMCP(  # type: ignore
      "BC",
      instructions="Provides access to biomedical knowledge bases.",
  )

• src/biocontext_kb/core/openfda/_count_drugs.py:28-28 (helper)

  Helper logic for handling array fields by appending '.exact' suffix to ensure correct counting for array-type fields in the FDA API.

  array_fields = [