refactor: improve structured content handling and code quality

- Change verbose info logging to debug level for tool responses
  to reduce production log noise while maintaining debug capability
- Remove redundant isinstance check in plugin response handling
- Add comprehensive docstring explaining structured content return
  types and MCP SDK behavior in call_tool function
- Add test case for structured content validation with tuple returns
- Improve code maintainability and documentation clarity

These changes enhance code quality without altering functionality,
improving pylint score from 9.64 to 9.77.

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

mcpgateway/services/tool_service.py

@@ -1240,7 +1240,7 @@ async def invoke_tool(self, db: Session, name: str, arguments: Dict[str, Any], r
                         # Don't mark as successful for error responses - success remains False
                     else:
                         result = response.json()
-                        logger.info(f" Rest API Tool response: {result}")
+                        logger.debug(f"REST API tool response: {result}")
                         filtered_response = extract_using_jq(result, tool.jsonpath_filter)
                         tool_result = ToolResult(content=[TextContent(type="text", text=json.dumps(filtered_response, indent=2))])
                         success = True
@@ -1405,7 +1405,7 @@ async def connect_to_streamablehttp_server(server_url: str, headers: dict = head
                     elif transport == "streamablehttp":
                         tool_call_result = await connect_to_streamablehttp_server(tool_gateway.url, headers=headers)
                     dump = tool_call_result.model_dump(by_alias=True)
-                    logger.info(f"Tool call result dump: {dump}")
+                    logger.debug(f"Tool call result dump: {dump}")
                     content = dump.get("content", [])
                     # Accept both alias and pythonic names for structured content
                     structured = dump.get("structuredContent") or dump.get("structured_content")
@@ -1415,7 +1415,7 @@ async def connect_to_streamablehttp_server(server_url: str, headers: dict = head
                     if is_err is None:
                         is_err = getattr(tool_call_result, "isError", False)
                     tool_result = ToolResult(content=filtered_response, structured_content=structured, is_error=is_err, meta=getattr(tool_call_result, "meta", None))
-                    logger.info(f"Final tool_result: {tool_result}")
+                    logger.debug(f"Final tool_result: {tool_result}")
                 else:
                     tool_result = ToolResult(content=[TextContent(type="text", text="Invalid tool type")])
 
@@ -1435,14 +1435,9 @@ async def connect_to_streamablehttp_server(server_url: str, headers: dict = head
                         if isinstance(modified_result, dict) and "content" in modified_result:
                             # Safely obtain structured content using .get() to avoid KeyError when
                             # plugins provide only the content without structured content fields.
-                            structured = None
-                            if isinstance(modified_result, dict):
-                                structured = modified_result.get("structuredContent") if "structuredContent" in modified_result else modified_result.get("structured_content")
-
-                            tool_result = ToolResult(
-                                content=modified_result["content"],
-                                structured_content=structured
-                            )
+                            structured = modified_result.get("structuredContent") if "structuredContent" in modified_result else modified_result.get("structured_content")
+
+                            tool_result = ToolResult(content=modified_result["content"], structured_content=structured)
                         else:
                             # If result is not in expected format, convert it to text content
                             tool_result = ToolResult(content=[TextContent(type="text", text=str(modified_result))])

mcpgateway/transports/streamablehttp_transport.py

@@ -359,12 +359,25 @@ async def call_tool(name: str, arguments: dict) -> List[Union[types.TextContent,
     """
     Handles tool invocation via the MCP Server.
 
+    This function supports the MCP protocol's tool calling with structured content validation.
+    It can return either unstructured content only, or both unstructured and structured content
+    when the tool defines an outputSchema.
+
     Args:
         name (str): The name of the tool to invoke.
         arguments (dict): A dictionary of arguments to pass to the tool.
 
     Returns:
-        List of content (TextContent, ImageContent, or EmbeddedResource) from the tool response.
+        Union[List[ContentBlock], Tuple[List[ContentBlock], Dict[str, Any]]]:
+            - If structured content is not present: Returns a list of content blocks
+              (TextContent, ImageContent, or EmbeddedResource)
+            - If structured content is present: Returns a tuple of (unstructured_content, structured_content)
+              where structured_content is a dictionary that will be validated against the tool's outputSchema
+
+        The MCP SDK's call_tool decorator automatically handles both return types:
+        - List return → CallToolResult with content only
+        - Tuple return → CallToolResult with both content and structuredContent fields
+
         Logs and returns an empty list on failure.
 
     Examples:

tests/unit/mcpgateway/transports/test_streamablehttp_transport.py

@@ -211,6 +211,54 @@ async def fake_get_db():
     assert result[0].text == "hello"
 
 
+@pytest.mark.asyncio
+async def test_call_tool_with_structured_content(monkeypatch):
+    """Test call_tool returns tuple with both unstructured and structured content."""
+    # First-Party
+    from mcpgateway.transports.streamablehttp_transport import call_tool, tool_service, types
+
+    mock_db = MagicMock()
+    mock_result = MagicMock()
+    mock_content = MagicMock()
+    mock_content.type = "text"
+    mock_content.text = '{"result": "success"}'
+    mock_result.content = [mock_content]
+
+    # Simulate structured content being present
+    mock_structured = {"status": "ok", "data": {"value": 42}}
+    mock_result.structured_content = mock_structured
+    mock_result.model_dump = lambda by_alias=True: {
+        "content": [{"type": "text", "text": '{"result": "success"}'}],
+        "structuredContent": mock_structured
+    }
+
+    @asynccontextmanager
+    async def fake_get_db():
+        yield mock_db
+
+    monkeypatch.setattr("mcpgateway.transports.streamablehttp_transport.get_db", fake_get_db)
+    monkeypatch.setattr(tool_service, "invoke_tool", AsyncMock(return_value=mock_result))
+
+    result = await call_tool("mytool", {"foo": "bar"})
+
+    # When structured content is present, result should be a tuple
+    assert isinstance(result, tuple)
+    assert len(result) == 2
+
+    # First element should be the unstructured content list
+    unstructured, structured = result
+    assert isinstance(unstructured, list)
+    assert len(unstructured) == 1
+    assert isinstance(unstructured[0], types.TextContent)
+    assert unstructured[0].text == '{"result": "success"}'
+
+    # Second element should be the structured content dict
+    assert isinstance(structured, dict)
+    assert structured == mock_structured
+    assert structured["status"] == "ok"
+    assert structured["data"]["value"] == 42
+
+
 @pytest.mark.asyncio
 async def test_call_tool_no_content(monkeypatch, caplog):
     """Test call_tool returns [] and logs warning if no content."""