feat: enhance docstring rendering with detailed parameter and return descriptions

Author: a-klos

infrastructure/rag/values.yaml

@@ -22,13 +22,40 @@ backend:
     host: "0.0.0.0"
 
     # Chat simple tool configuration
+    # The following configuration for the chat_simple tool will render as follows:
+    # """Send a message to the RAG system and get a simple text response.
+
+    # This is the simplest way to interact with the RAG system - just provide a message and get back the answer as plain text.
+    #
+    # Parameters
+    # ----------
+    # session_id : str
+    #     Unique identifier for the chat session.
+    # message : str
+    #     The message/question to ask the RAG system.
+    #
+    # Returns
+    # -------
+    # str
+    #     The answer from the RAG system as plain text.
+    # """
     chatSimpleDescription: "Send a message to the RAG system and get a simple text response.\n\nThis is the simplest way to interact with the RAG system - just provide a message and get back the answer as plain text."
     chatSimpleParameterDescriptions:
       session_id: "Unique identifier for the chat session."
       message: "The message/question to ask the RAG system."
     chatSimpleReturns: "The answer from the RAG system as plain text."
     chatSimpleNotes: ""
+    # If you add a Value to chatSimpleNotes e.g. "This tool is best for simple questions that don't require conversation context."
+    # it will render to:
+    # Notes
+    # -----
+    # This tool is best for simple questions that don't require conversation context.
     chatSimpleExamples: ""
+    # If you add a Value to chatSimpleExamples e.g. "chat_simple(session_id='my-session', message='What is the main topic of the document?')"
+    # it will render to:
+    # Examples
+    # --------
+    # chat_simple(session_id='my-session', message='What is the main topic of the document?')
 
     # Chat with history tool configuration
     chatWithHistoryDescription: "Send a message with conversation history and get structured response.\n\nProvide conversation history as a simple list of dictionaries.\nEach history item should have 'role' (either 'user' or 'assistant') and 'message' keys."

services/mcp-server/src/docstring_system.py

@@ -22,8 +22,21 @@ def __init__(self, settings: BaseSettings):
         self.settings = settings
         self._setup_templates()
 
-    def render_docstring(self, template_name: str, **kwargs) -> str:
-        """Render a docstring using the template."""
+    def render_docstring(self, template_name: str, **kwargs: dict) -> str:
+        """Render a docstring using the template.
+
+        Parameters
+        ----------
+        template_name : str
+            Name of the template to render
+        **kwargs : dict
+            Keyword arguments to pass to the render function of the template
+
+        Returns
+        -------
+        str
+            Rendered docstring
+        """
         return self.template.render(**kwargs)
 
     def _setup_templates(self):