Add detailed instructions to MCP tool descriptions

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<McpClass> searchClasses(
         String query,
         @ToolParam(required=false) String ontologyId,
@@ -77,7 +105,35 @@ McpPage<McpClass> 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<McpClass> getAncestors(
         String ontologyId,
         String classIri,
@@ -110,7 +166,35 @@ McpPage<McpClass> 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<McpClass> getDescendants(
         String ontologyId,
         String classIri,

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<McpOntology> listOntologies(
         @ToolParam(required=false) String lang
     ) throws IOException {

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<String> - The entity types (e.g., ["class"])
+          * iri: String - The full IRI
+          * curie: String - The compact URI (e.g., "GO:0008150")
+          * label: List<String> - All labels for the term
+          * definition: List<String> - All definitions for the term
+          * directAncestor: List<Object> - Direct ancestors, each with fields: iri (String), definedBy (List<String>), label (List<String>)
+          * directParent: List<Object> - Direct parents, each with fields: iri (String), definedBy (List<String>), label (List<String>)
+          * hierarchicalParent: List<Object> - Hierarchical parents, each with fields: iri (String), definedBy (List<String>), label (List<String>)
+          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 {