Add detailed instructions to MCP tool descriptions

[Copilot]

Add Detailed Instructions to MCP Tools ✅

• Review current MCP tool descriptions in the codebase
• Enhance McpSearchService tool descriptions with detailed instructions
  • Improve 'search' tool description - added comprehensive details about parameters, return values, and usage
  • Improve 'fetch' tool description - updated with exact field types and structure from code analysis
• Enhance McpClassService tool descriptions with detailed instructions
  • Improve 'searchClasses' tool description - added examples, parameter details, and pagination info
  • Improve 'getAncestors' tool description - explained hierarchical relationships and use cases
  • Improve 'getDescendants' tool description - explained subtypes and practical applications
• Enhance McpOntologyService tool descriptions with detailed instructions
  • Improve 'listOntologies' tool description - added comprehensive information about ontologies and examples
• Build and validate changes - Maven build successful
• Run security checks - No vulnerabilities detected
• Address feedback - Updated fetch description with exact field types from code

Summary

Enhanced the MCP (Model Context Protocol) tool descriptions in the OLS4 backend with detailed, comprehensive instructions. All 6 MCP tools now include:

Enhanced Tools:

1. search - Full-text search across all ontologies with clear parameter and return format documentation
2. fetch - Retrieve detailed term information with exact field types (String vs List), structure of metadata object including McpEntityReference fields
3. searchClasses - Search ontology classes with filtering options and pagination
4. getAncestors - Get parent classes in hierarchy with practical use cases
5. getDescendants - Get child classes with subtypes examples
6. listOntologies - List all available ontologies with common examples

Improvements Made:

• Added detailed parameter descriptions with examples
• Documented return value structures accurately based on actual implementation code
• Specified exact field types (String, List, List) from McpFetchResult, McpClass, and McpEntityReference classes
• Included practical use cases and workflow guidance
• Added examples of common ontologies (GO, EFO, HP, MONDO, etc.)
• Explained relationships between tools (e.g., use 'search' then 'fetch')
• Clarified data formats and expected inputs

Files Modified:

• backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpSearchService.java
• backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpClassService.java
• backend/src/main/java/uk/ac/ebi/spot/ols/controller/mcp/McpOntologyService.java

Validation:
✅ Maven build successful (1:38 min)
✅ CodeQL security check passed (0 vulnerabilities)
✅ No breaking changes to API contracts

Security Summary

No security vulnerabilities were introduced or discovered during the implementation. The changes are purely documentation enhancements to existing @Tool annotations.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add detailed instructions to the MCP tools</issue_title>
<issue_description></issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1016

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[jamesamcl]

@copilot your description of fetch is wrong

[Copilot]

@copilot your description of fetch is wrong

Fixed in 9a043da. The description now accurately reflects that the text field contains only the definition, and the detailed hierarchical information is in the metadata field.

[jamesamcl]

@copilot can you read the code and work out exactly what fetch returns, and update the instructions from that?

[Copilot]

@copilot can you read the code and work out exactly what fetch returns, and update the instructions from that?

Updated in 5102ce4. The description now precisely matches the code structure:

• Top-level fields with exact types (id: String, title: String, text: String, url: String, metadata: Object)
• For class entities, metadata contains McpClass with all fields including type: List, label: List, definition: List
• Parent relationships (directAncestor, directParent, hierarchicalParent) as List with McpEntityReference structure (iri: String, definedBy: List, label: List)
• For non-class entities, metadata is just {"type": "property"} or similar