bc_count_drugs_by_field

Count unique values in FDA-approved drug fields for statistical analysis. Specify a field like 'sponsor_name' or 'dosage_form' to get term frequencies.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`field`	Yes	Field to count (e.g., 'sponsor_name', 'products.dosage_form', 'products.route', 'openfda.pharm_class_epc')
`search_filter`	No	Optional search filter to apply before counting
`limit`	No	Maximum number of count results to return

Implementation Reference

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

The primary handler function for the bc_count_drugs_by_field tool. It uses the @core_mcp.tool() decorator for registration and includes inline Pydantic schema validation via Annotated Fields. Queries the OpenFDA API to count unique values in specified drug fields.

@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/app.py:35-39 (registration)
Registers the core_mcp server (containing the tool) into the main BioContextAI MCP application under the prefixed namespace 'bc' (from slugify('BC')), making the tool available as 'bc_count_drugs_by_field'.
```
for mcp in [core_mcp, *(await get_openapi_mcps())]:
    await mcp_app.import_server(
        mcp,
        slugify(mcp.name),
    )
```
src/biocontext_kb/core/_server.py:3-7 (registration)
Defines the core_mcp FastMCP instance named 'BC' where individual tools like count_drugs_by_field are registered via decorators. This MCP is later imported into the main app with 'bc' prefix.
```
core_mcp = FastMCP(  # type: ignore
    "BC",
    instructions="Provides access to biomedical knowledge bases.",
)
```
src/biocontext_kb/core/__init__.py:13-13 (helper)
Imports the openfda module, which triggers the loading and decorator-based registration of the count_drugs_by_field tool into core_mcp.
```
from .openfda import *
```
src/biocontext_kb/core/openfda/__init__.py:6-6 (registration)
Exposes the count_drugs_by_field function for import, facilitating its registration when the openfda module is imported.
```
from ._count_drugs import count_drugs_by_field, get_drug_statistics
```

BioContextAI Knowledgebase MCP