diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpClassService.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpClassService.java index f9da4b072..ce0ffcd3f 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpClassService.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpClassService.java @@ -28,7 +28,35 @@ public class McpClassService { @Autowired ClassRepository classRepository; - @Tool(description = "Search all classes in OLS for a query string") + @Tool(description = """ + Search for ontology classes in OLS matching a query string. + + This tool searches specifically for classes (types/concepts) across ontologies, filtering out properties and individuals. + Classes represent the main conceptual entities in ontologies (e.g., diseases, anatomical structures, cell types). + + Parameters: + - query: Search term or phrase (required, e.g., "heart disease", "neuron", "protein binding") + - ontologyId: Limit search to a specific ontology (optional, e.g., "go" for Gene Ontology, "efo" for Experimental Factor Ontology) + - pageNum: Page number for pagination, starting from 0 (optional, default: 0) + - pageSize: Number of results per page (optional, default: 20, max recommended: 100) + - lang: Language code for labels (optional, default: "en" for English) + + Returns: A paginated list of classes with: + - content: Array of class objects, each containing: + * iri: The full IRI/URL identifier of the class + * label: Primary name/label of the class + * description: Definition and description + * ontology_name: Name of the ontology containing this class + * ontology_id: Short identifier of the ontology + * synonyms: Alternative names for the class + - page: Current page number + - pageSize: Number of results per page + - totalElements: Total number of matching results + - totalPages: Total number of pages available + + Use this tool when you need to find specific types/classes in ontologies, optionally restricted to a particular ontology. + For hierarchical information about a class, use 'getAncestors' or 'getDescendants' tools. + """) McpPage searchClasses( String query, @ToolParam(required=false) String ontologyId, @@ -77,7 +105,35 @@ McpPage searchClasses( } - @Tool(description = "Get all ancestors for a class in OLS") + @Tool(description = """ + Get all ancestor (parent) classes of a specific class in the ontology hierarchy. + + This tool retrieves all classes that are hierarchically above (more general than) the specified class. + Ancestors represent broader, more general concepts. For example, ancestors of "heart" might include + "organ", "anatomical structure", "entity". + + Parameters: + - ontologyId: The ontology identifier (required, e.g., "go", "efo", "uberon", "hp") + - classIri: The full IRI/URL of the class (required, e.g., "http://purl.obolibrary.org/obo/GO_0008150") + - pageNum: Page number for pagination, starting from 0 (optional, default: 0) + - pageSize: Number of results per page (optional, default: 20) + - lang: Language code for labels (optional, default: "en") + + Returns: A paginated list of ancestor classes with: + - content: Array of ancestor class objects, each containing: + * iri: The full IRI/URL of the ancestor class + * label: Name of the ancestor class + * description: Definition of the ancestor class + * ontology_name: Name of the ontology + * ontology_id: Ontology identifier + - page: Current page number + - pageSize: Results per page + - totalElements: Total number of ancestors + - totalPages: Total pages available + + Use this tool to understand the broader context and classification of a class by exploring its parent classes. + This helps answer questions like "What is this a type of?" or "What broader categories does this belong to?" + """) McpPage getAncestors( String ontologyId, String classIri, @@ -110,7 +166,35 @@ McpPage getAncestors( ); } - @Tool(description = "Get all descendants of a class in OLS") + @Tool(description = """ + Get all descendant (child) classes of a specific class in the ontology hierarchy. + + This tool retrieves all classes that are hierarchically below (more specific than) the specified class. + Descendants represent narrower, more specific concepts. For example, descendants of "disease" might include + "genetic disease", "infectious disease", "cardiovascular disease", and all their subtypes. + + Parameters: + - ontologyId: The ontology identifier (required, e.g., "go", "efo", "uberon", "mondo") + - classIri: The full IRI/URL of the class (required, e.g., "http://purl.obolibrary.org/obo/MONDO_0000001") + - pageNum: Page number for pagination, starting from 0 (optional, default: 0) + - pageSize: Number of results per page (optional, default: 20) + - lang: Language code for labels (optional, default: "en") + + Returns: A paginated list of descendant classes with: + - content: Array of descendant class objects, each containing: + * iri: The full IRI/URL of the descendant class + * label: Name of the descendant class + * description: Definition of the descendant class + * ontology_name: Name of the ontology + * ontology_id: Ontology identifier + - page: Current page number + - pageSize: Results per page + - totalElements: Total number of descendants + - totalPages: Total pages available + + Use this tool to explore the subtypes and more specific instances within a category. + This helps answer questions like "What are the specific types of X?" or "What subcategories exist under this concept?" + """) McpPage getDescendants( String ontologyId, String classIri, diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpOntologyService.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpOntologyService.java index 2d5fb6063..0677109a3 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpOntologyService.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpOntologyService.java @@ -21,7 +21,36 @@ public class McpOntologyService { @Autowired OntologyRepository ontologyRepository; - @Tool(description = "Get all ontologies from OLS") + @Tool(description = """ + List all available ontologies in the Ontology Lookup Service (OLS). + + This tool retrieves metadata about all ontologies currently loaded in OLS, providing an overview + of available biomedical and scientific knowledge resources. + + Parameters: + - lang: Language code for ontology titles and descriptions (optional, default: "en" for English) + + Returns: A list of ontology objects, each containing: + - ontology_id: Short identifier for the ontology (e.g., "go", "efo", "hp", "mondo") + - title: Full name of the ontology (e.g., "Gene Ontology", "Experimental Factor Ontology") + - description: Detailed description of the ontology's scope and purpose + - namespace: The namespace/prefix used in the ontology + - homepage: URL to the ontology's homepage or documentation + - version: Current version of the ontology loaded in OLS + - number_of_terms: Count of terms/classes in the ontology + - status: Status of the ontology (e.g., "LOADED", "LOADING", "FAILED") + + Common ontologies include: + - GO (Gene Ontology): Biological processes, cellular components, molecular functions + - EFO (Experimental Factor Ontology): Experimental variables and factors + - HP (Human Phenotype Ontology): Human phenotypic abnormalities + - MONDO (Monarch Disease Ontology): Diseases and medical conditions + - UBERON: Anatomical structures across species + - CL (Cell Ontology): Cell types + - CHEBI: Chemical entities of biological interest + + Use this tool to discover what ontologies are available before searching for specific terms. + """) List listOntologies( @ToolParam(required=false) String lang ) throws IOException { diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpSearchService.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpSearchService.java index 82c9a5455..b9297bed8 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpSearchService.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpSearchService.java @@ -28,7 +28,23 @@ public class McpSearchService { // Specific params and result format to match OpenAI requirements: // https://platform.openai.com/docs/mcp#create-an-mcp-server - @Tool(description = "OpenAI compliant tool to search OLS for a query string") + @Tool(description = """ + Search the Ontology Lookup Service (OLS) for ontology terms matching a query string. + + This tool performs a full-text search across all ontologies in OLS to find matching terms, classes, properties, and individuals. + + Parameters: + - query: The search term or phrase (e.g., "cell", "diabetes", "mitochondrion") + + Returns: A JSON array of search results, each containing: + - id: Unique identifier in format "ontologyId+entityIri" (e.g., "go+http://purl.obolibrary.org/obo/GO_0008150") + - title: The primary label/name of the term + - text: Description and additional information about the term + - score: Relevance score for the search result + + Use this tool to discover relevant ontology terms when you need to find concepts related to your query. + After finding relevant terms, use the 'fetch' tool to retrieve detailed information about a specific term. + """) String search( String query ) throws IOException { @@ -53,7 +69,36 @@ String search( return gson.toJson( res.getContent().stream().map(McpSearchResult::fromJson).toList() ); } - @Tool(description = "OpenAI compliant tool to retrieve an entity from OLS by ID returned from the search tool. The ID must be of the format ontologyid+entityIri, e.g. go+http://purl.obolibrary.org/obo/GO_0008150. IDs in this format are returned by the OpenAI compliant 'search' tool.") + @Tool(description = """ + Retrieve detailed information about a specific ontology term by its ID. + + This tool fetches complete metadata for an ontology entity including its definition, labels, and hierarchical relationships. + + Parameters: + - id: The unique identifier in format "ontologyId+entityIri" (e.g., "go+http://purl.obolibrary.org/obo/GO_0008150") + This ID format is returned by the 'search' tool results. The ontologyId is the short identifier like "go", "efo", "uberon", + and the entityIri is the full IRI/URL of the term. + + Returns: A JSON object with the following fields: + - id: String - The identifier in "ontologyId+entityIri" format (e.g., "go+http://purl.obolibrary.org/obo/GO_0008150") + - title: String - The CURIE and primary label concatenated (e.g., "GO:0008150 biological_process") + - text: String - The definition of the term (single string, not a list) + - url: String - The full IRI of the term (e.g., "http://purl.obolibrary.org/obo/GO_0008150") + - metadata: Object - For class entities, this is an object with the following fields: + * ontologyId: String - The ontology identifier (e.g., "go") + * type: List - The entity types (e.g., ["class"]) + * iri: String - The full IRI + * curie: String - The compact URI (e.g., "GO:0008150") + * label: List - All labels for the term + * definition: List - All definitions for the term + * directAncestor: List - Direct ancestors, each with fields: iri (String), definedBy (List), label (List) + * directParent: List - Direct parents, each with fields: iri (String), definedBy (List), label (List) + * hierarchicalParent: List - Hierarchical parents, each with fields: iri (String), definedBy (List), label (List) + For non-class entities, metadata contains only: {"type": "property"} or similar. + + Use this tool after using 'search' to get comprehensive information about a specific term. + The metadata field contains structured information about the term's hierarchical relationships within the ontology. + """) String fetch( String id ) throws IOException {