bc_count_drugs_by_field
Count unique values in FDA-approved drug fields like sponsor, dosage form, or administration route for statistical analysis. Filter and limit results for precise insights into drug database characteristics.
Instructions
Count unique values in a specific field across FDA-approved drugs.
This function is useful for statistical analysis and getting overviews of the drug database. Common fields to count include:
sponsor_name: Count drugs by pharmaceutical company
products.dosage_form: Count by dosage forms (tablet, injection, etc.)
products.route: Count by administration routes (oral, injection, etc.)
products.marketing_status: Count by marketing status
openfda.pharm_class_epc: Count by pharmacologic class
Args: field (str): The field to count unique values for. search_filter (str, optional): Search filter to apply before counting. limit (int): Maximum number of count results to return.
Returns: dict: Count results showing terms and their frequencies.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | Field to count by (e.g., 'sponsor_name', 'products.dosage_form', 'products.route', 'products.marketing_status', 'openfda.pharm_class_epc') | |
| limit | No | Maximum number of count results to return | |
| search_filter | No | Optional search filter to apply before counting |
Implementation Reference
- Handler function for the 'count_drugs_by_field' tool (likely 'bc_count_drugs_by_field' in prefixed namespace). Implements counting unique values in specified FDA drug fields via OpenFDA API.@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}"}
- Input schema defined using Pydantic Annotated and Field for field, search_filter, and limit parameters.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:
- src/biocontext_kb/core/openfda/__init__.py:6-6 (registration)Imports the tool handler for exposure via openfda module.from ._count_drugs import count_drugs_by_field, get_drug_statistics
- src/biocontext_kb/core/__init__.py:13-13 (registration)Imports all openfda tools into core namespace for registration in core_mcp.from .openfda import *
- The decorator @core_mcp.tool() registers this function as an MCP tool.@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}"}