From b111d40baaaec31e9b5c7903b652bae50fe6db4e Mon Sep 17 00:00:00 2001
From: Brian Krabach <brkrabac@microsoft.com>
Date: Wed, 19 Feb 2025 16:41:23 +0000
Subject: [PATCH] improved comments within mcp-extensions files

---
 .../mcp-extensions/mcp_extensions/__init__.py |  3 +++
 .../mcp-extensions/mcp_extensions/_model.py   |  9 +++++++++
 .../mcp_extensions/_tool_utils.py             | 19 +++++++++++--------
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/libraries/python/mcp-extensions/mcp_extensions/__init__.py b/libraries/python/mcp-extensions/mcp_extensions/__init__.py
index 19afc661..a67d0dd5 100644
--- a/libraries/python/mcp-extensions/mcp_extensions/__init__.py
+++ b/libraries/python/mcp-extensions/mcp_extensions/__init__.py
@@ -1,6 +1,9 @@
 from ._model import ServerNotificationHandler, ToolCallFunction, ToolCallProgressMessage
 from ._tool_utils import convert_tools_to_openai_tools, execute_tool_with_notifications, send_tool_call_progress
 
+# Exported utilities and models for external use.
+# These components enhance interactions with MCP workflows by providing utilities for notifications,
+# progress updates, and tool conversion specific to the MCP ecosystem.
 __all__ = [
     "convert_tools_to_openai_tools",
     "execute_tool_with_notifications",
diff --git a/libraries/python/mcp-extensions/mcp_extensions/_model.py b/libraries/python/mcp-extensions/mcp_extensions/_model.py
index 474723ae..3373bcc7 100644
--- a/libraries/python/mcp-extensions/mcp_extensions/_model.py
+++ b/libraries/python/mcp-extensions/mcp_extensions/_model.py
@@ -9,5 +9,14 @@
 
 
 class ToolCallProgressMessage(BaseModel):
+    """
+    Represents a progress message for an active tool call.
+
+    Attributes:
+        message (str): A brief textual update describing the current tool execution state.
+        data (dict[str, Any] | None): Optional dictionary containing structured data relevant
+            to the progress update.
+    """
+
     message: str
     data: dict[str, Any] | None
diff --git a/libraries/python/mcp-extensions/mcp_extensions/_tool_utils.py b/libraries/python/mcp-extensions/mcp_extensions/_tool_utils.py
index aa68706b..08db3892 100644
--- a/libraries/python/mcp-extensions/mcp_extensions/_tool_utils.py
+++ b/libraries/python/mcp-extensions/mcp_extensions/_tool_utils.py
@@ -21,7 +21,8 @@ async def send_tool_call_progress(
     fastmcp_server_context: Context, message: str, data: dict[str, Any] | None = None
 ) -> None:
     """
-    Send a progress update message for a tool call to the FastMCP server.
+    Sends a progress update message for a tool call to the FastMCP server. This is useful for providing
+    real-time feedback to clients regarding task status.
     """
 
     await fastmcp_server_context.session.send_log_message(
@@ -48,15 +49,16 @@ async def execute_tool_with_notifications(
     notification_handler: ServerNotificationHandler,
 ) -> CallToolResult:
     """
-    Execute a tool call while handling notifications that may arrive during execution.
+    Executes a tool call while concurrently processing incoming notifications from the MCP server. This ensures
+    smooth handling of asynchronous updates during execution.
 
     Args:
-        session: The MCP client session
-        tool_call: Async function that performs the actual tool call
-        notification_handler: Async function to handle notifications during execution
+        session: The MCP client session facilitating communication with the server.
+        tool_call_function: The asynchronous tool call function to execute.
+        notification_handler: Asynchronous callback to process server notifications during execution.
 
     Returns:
-        The result of the tool call
+        The result of the tool call, typically wrapped as a protocol-compliant response.
     """
 
     # Create a task for listening to incoming messages
@@ -87,8 +89,9 @@ def convert_tools_to_openai_tools(
     mcp_tools: List[Tool] | None, extra_properties: dict[str, Any] | None = None
 ) -> List[ChatCompletionToolParam] | None:
     """
-    Convert MCP tools to OpenAI tools. Use the extra properties to add additional parameters,
-    such as a custom property to allow the model to explain the reason for the tool call.
+    Converts MCP tools into OpenAI-compatible tool schemas to facilitate interoperability.
+    Extra properties can be appended to the generated schema, enabling richer descriptions
+    or added functionality (e.g., custom fields for user context or explanations).
     """
 
     if not mcp_tools: