bc_get_term_hierarchical_children
Retrieve hierarchical children of a specific ontology term, including subclasses and 'part of' relationships, from the Ontology Lookup Service (OLS). Useful for exploring term dependencies and structure in biomedical ontologies.
Instructions
Query the Ontology Lookup Service (OLS) for hierarchical children of a term.
This function retrieves the hierarchical children of a specific ontology term, including subclasses and terms related via hierarchical properties like 'part of'.
Args: term_id (str): The term ID in CURIE format (e.g., "EFO:0000001"). ontology_id (str): The ontology ID (e.g., "efo"). size (int): Maximum number of children to return (default: 20).
Returns: dict: Dictionary containing hierarchical children or error message
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ontology_id | Yes | The ontology ID where the term is defined (e.g., 'efo', 'go', 'chebi') | |
| size | No | The maximum number of children to return | |
| term_id | Yes | The term ID (CURIE) to get children for (e.g., 'EFO:0000001', 'GO:0008150') |
Implementation Reference
- The handler function implementing the tool logic. It queries the OLS API for hierarchical children of a given ontology term ID, processes the response, and returns structured data including parent term, children details, and pagination info. The tool is registered via @core_mcp.tool() decorator, and in the main app, core_mcp is imported under 'bc' namespace, making the full tool name 'bc_get_term_hierarchical_children'.@core_mcp.tool() def get_term_hierarchical_children( term_id: Annotated[str, Field(description="Term ID in CURIE format (e.g., 'EFO:0000001', 'GO:0008150')")], ontology_id: Annotated[str, Field(description="Ontology ID (e.g., 'efo', 'go', 'chebi')")], size: Annotated[ int, Field(description="Maximum number of children to return"), ] = 20, ) -> Dict[str, Any]: """Get hierarchical children of an ontology term from OLS. Includes subclasses and hierarchical properties. Returns: dict: Parent term, hierarchical_children array with id/label/definition, total_children, page_info or error message. """ if not term_id: return {"error": "term_id must be provided"} if not ontology_id: return {"error": "ontology_id must be provided"} # Double URL encode the term IRI import urllib.parse term_iri = f"http://purl.obolibrary.org/obo/{term_id.replace(':', '_')}" encoded_iri = urllib.parse.quote(urllib.parse.quote(term_iri, safe=""), safe="") url = f"https://www.ebi.ac.uk/ols4/api/v2/ontologies/{ontology_id}/classes/{encoded_iri}/hierarchicalChildren" params = { "size": str(size), "page": "0", } try: response = requests.get(url, params=params) response.raise_for_status() data = response.json() if not data.get("elements"): return {"error": "No hierarchical children found"} # Extract children information children = [ { "id": element.get("curie", "").replace(":", "_"), "curie": element.get("curie", ""), "label": element.get("label", ""), "definition": element.get("definition", ""), "ontology_name": element.get("ontologyName", ""), "has_hierarchical_children": element.get("hasHierarchicalChildren", False), "num_descendants": element.get("numDescendants", 0), } for element in data["elements"] ] return { "parent_term": term_id, "hierarchical_children": children, "total_children": data.get("totalElements", len(children)), "page_info": { "page": data.get("page", 0), "total_pages": data.get("totalPages", 1), "num_elements": data.get("numElements", len(children)), }, } except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch hierarchical children: {e!s}"}
- Pydantic-based input schema defined using Annotated and Field for term_id (str), ontology_id (str), and optional size (int=20). Output is Dict[str, Any] with structure for children or error.def get_term_hierarchical_children( term_id: Annotated[str, Field(description="Term ID in CURIE format (e.g., 'EFO:0000001', 'GO:0008150')")], ontology_id: Annotated[str, Field(description="Ontology ID (e.g., 'efo', 'go', 'chebi')")], size: Annotated[ int, Field(description="Maximum number of children to return"), ] = 20, ) -> Dict[str, Any]:
- src/biocontext_kb/core/_server.py:3-6 (registration)Defines the core_mcp FastMCP server named 'BC', to which the tool is registered via decorator. Later imported into main app under slugified name 'bc', prefixing tool names with 'bc_'.core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", )
- src/biocontext_kb/app.py:36-39 (registration)Imports the core_mcp server into the main mcp_app under the slugified name ('bc' for 'BC'), which namespaces all core tools with 'bc_' prefix, making this tool 'bc_get_term_hierarchical_children'.await mcp_app.import_server( mcp, slugify(mcp.name), )