bc_search_drugs_by_therapeutic_class
Search FDA-approved drugs by therapeutic or pharmacologic class to identify medications for specific treatment approaches. Retrieve drug details including application information, products, and sponsor names.
Instructions
Search for drugs by therapeutic or pharmacologic class. Use get_available_pharmacologic_classes() first for exact terms.
Returns: dict: FDA drug results array with application info, products, sponsor names or error message.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| therapeutic_class | Yes | Exact therapeutic/pharmacologic class term from FDA (use get_available_pharmacologic_classes first) | |
| class_type | No | Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure) | epc |
| limit | No | Number of results to return |
Implementation Reference
- Main handler function for the tool, decorated as @core_mcp.tool(). Queries OpenFDA API using the specified therapeutic class and class_type (default 'epc'). Includes input schema via Annotated Fields.@core_mcp.tool() def search_drugs_by_therapeutic_class( therapeutic_class: Annotated[ str, Field( description="Exact therapeutic/pharmacologic class term from FDA (use get_available_pharmacologic_classes first)" ), ], class_type: Annotated[ str, Field( description="Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure)" ), ] = "epc", limit: Annotated[int, Field(description="Number of results to return", ge=1, le=1000)] = 25, ) -> dict: """Search for drugs by therapeutic or pharmacologic class. Use get_available_pharmacologic_classes() first for exact terms. Returns: dict: FDA drug results array with application info, products, sponsor names or error message. """ # Map class type to the appropriate OpenFDA field class_field_mapping = { "epc": "openfda.pharm_class_epc", # Established Pharmacologic Class "moa": "openfda.pharm_class_moa", # Mechanism of Action "pe": "openfda.pharm_class_pe", # Physiologic Effect "cs": "openfda.pharm_class_cs", # Chemical Structure } if class_type.lower() not in class_field_mapping: return {"error": "class_type must be one of: epc, moa, pe, cs"} field = class_field_mapping[class_type.lower()] # Use exact term as provided - no mapping since user should get this from get_available_pharmacologic_classes query = f'{field}:"{therapeutic_class}"' base_url = "https://api.fda.gov/drug/drugsfda.json" params: Any = {"search": query, "limit": limit} try: response = requests.get(base_url, params=params) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch drugs by therapeutic class: {e!s}"}
- src/biocontext_kb/app.py:35-40 (registration)Main registration point where core_mcp (containing the tool) is imported into the top-level mcp_app with prefix 'bc' (from slugify('BC')), exposing the tool as 'bc_search_drugs_by_therapeutic_class'.for mcp in [core_mcp, *(await get_openapi_mcps())]: await mcp_app.import_server( mcp, slugify(mcp.name), ) logger.info("MCP server setup complete.")
- src/biocontext_kb/core/_server.py:3-7 (registration)Definition of the core_mcp FastMCP instance named 'BC', on which the tool is registered via @core_mcp.tool() decorator.core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", )
- Supporting helper tool to retrieve available therapeutic/pharmacologic classes from OpenFDA, recommended to call first for exact terms.@core_mcp.tool() def get_available_pharmacologic_classes( class_type: Annotated[ str, Field( description="Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure)" ), ] = "epc", limit: Annotated[int, Field(description="Number of unique classes to return", ge=1, le=1000)] = 100, ) -> dict: """Get available pharmacologic classes from FDA database. Call this first to see available options. Returns: dict: Class type, field, available_classes array with term/count, total_found or error message. """ # Map class type to the appropriate OpenFDA field class_field_mapping = { "epc": "openfda.pharm_class_epc", # Established Pharmacologic Class "moa": "openfda.pharm_class_moa", # Mechanism of Action "pe": "openfda.pharm_class_pe", # Physiologic Effect "cs": "openfda.pharm_class_cs", # Chemical Structure } if class_type.lower() not in class_field_mapping: return {"error": "class_type must be one of: epc, moa, pe, cs"} field = class_field_mapping[class_type.lower()] # Use the count endpoint to get unique values base_url = "https://api.fda.gov/drug/drugsfda.json" params: Any = {"count": field, "limit": limit} try: response = requests.get(base_url, params=params) response.raise_for_status() data = response.json() return { "class_type": class_type, "field": field, "available_classes": data.get("results", []), "total_found": len(data.get("results", [])), } except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch available pharmacologic classes: {e!s}"}
- Pydantic schema definitions for tool inputs via Annotated and Field.def search_drugs_by_therapeutic_class( therapeutic_class: Annotated[ str, Field( description="Exact therapeutic/pharmacologic class term from FDA (use get_available_pharmacologic_classes first)" ), ], class_type: Annotated[ str, Field( description="Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure)" ), ] = "epc", limit: Annotated[int, Field(description="Number of results to return", ge=1, le=1000)] = 25, ) -> dict: """Search for drugs by therapeutic or pharmacologic class. Use get_available_pharmacologic_classes() first for exact terms. Returns: dict: FDA drug results array with application info, products, sponsor names or error message. """ # Map class type to the appropriate OpenFDA field class_field_mapping = { "epc": "openfda.pharm_class_epc", # Established Pharmacologic Class "moa": "openfda.pharm_class_moa", # Mechanism of Action "pe": "openfda.pharm_class_pe", # Physiologic Effect "cs": "openfda.pharm_class_cs", # Chemical Structure } if class_type.lower() not in class_field_mapping: return {"error": "class_type must be one of: epc, moa, pe, cs"} field = class_field_mapping[class_type.lower()] # Use exact term as provided - no mapping since user should get this from get_available_pharmacologic_classes query = f'{field}:"{therapeutic_class}"' base_url = "https://api.fda.gov/drug/drugsfda.json" params: Any = {"search": query, "limit": limit} try: response = requests.get(base_url, params=params) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch drugs by therapeutic class: {e!s}"}