Use full "Returns" section when generating the function description (#11772)

* mcp-parse-returns

* func desc

* add changeset

* fix failing test

---------

Co-authored-by: gradio-pr-bot <[email protected]>

Author: abidlabs

.changeset/dark-pets-decide.md

@@ -0,0 +1,5 @@
+---
+"gradio": minor
+---
+
+feat:Use full "Returns" section when generating the function description

.gitignore

@@ -58,6 +58,7 @@ demo/unload_event_test/output_log.txt
 demo/stream_video_out/output_*.ts
 demo/stream_video_out/output_*.mp4
 demo/stream_audio_out/*.mp3
+test-demo/*
 #demo/image_editor_story/*.png
 
 # Etc

gradio/utils.py

@@ -1704,8 +1704,9 @@ def get_function_description(fn: Callable) -> tuple[str, dict[str, str], list[st
     Get the description of a function, its parameters, and return values by parsing the docstring.
     The docstring should be formatted as follows: first lines are the description
     of the function, then a line starts with "Args:", "Parameters:", or "Arguments:",
-    followed by lines of the form "param_name: description", then optionally a line
-    that starts with "Returns:" followed by descriptions of return values.
+    followed by lines of the form "param_name: description", then optionally lines
+    that starts with "Returns:" followed by descriptions of return values. All lines
+    after the "Returns:" line are added in the `returns` list (including e.g. "Examples").
 
     Parameters:
         fn: The function to get the docstring for.
@@ -1782,16 +1783,7 @@ def get_function_description(fn: Callable) -> tuple[str, dict[str, str], list[st
                 if not line:
                     continue
 
-                try:
-                    if line.startswith("-"):
-                        returns.append(line[1:].strip())
-                    elif ":" in line:
-                        _, return_desc = line.split(":", 1)
-                        returns.append(return_desc.strip())
-                    else:
-                        returns.append(line)
-                except Exception:
-                    continue
+                returns.append(line)
 
     except Exception:
         pass

test/test_mcp.py

@@ -185,7 +185,7 @@ def test_mcp_sse_transport(test_mcp_app):
         assert response.json() == [
             {
                 "name": "test_tool",
-                "description": "This is a test tool. Returns: the original value as a string",
+                "description": "This is a test tool. Returns: - the original value as a string",
                 "inputSchema": {
                     "type": "object",
                     "properties": {"x": {"type": "string", "description": ""}},

test/test_utils.py

@@ -785,7 +785,33 @@ def test_func(param1, param2):
         description, parameters, returns = get_function_description(test_func)
         assert description == "This is a test function."
         assert parameters == {"param1": "First parameter", "param2": "Second parameter"}
-        assert returns == ["First return value", "Second return value"]
+        assert returns == ["- First return value", "- Second return value"]
+
+    def test_function_with_extended_returns(self):
+        def test_func(param1, param2):
+            """This is a test function.
+            Args:
+                param1: First parameter
+                param2: Second parameter
+            Returns:
+                - First return value
+                - Second return value
+            Examples:
+                - Example 1
+                - Example 2
+            """
+            pass
+
+        description, parameters, returns = get_function_description(test_func)
+        assert description == "This is a test function."
+        assert parameters == {"param1": "First parameter", "param2": "Second parameter"}
+        assert returns == [
+            "- First return value",
+            "- Second return value",
+            "Examples:",
+            "- Example 1",
+            "- Example 2",
+        ]
 
     def test_function_with_no_docstring(self):
         def test_func():
@@ -835,7 +861,7 @@ def test_func(param1, param2):
         description, parameters, returns = get_function_description(test_func)
         assert description == "This is a test function."
         assert parameters == {"param1": "First parameter", "param2": "Second parameter"}
-        assert returns == ["First return value", "Second return value"]
+        assert returns == ["x: First return value", "y: Second return value"]
 
     def test_function_with_multiline_description(self):
         def test_func(param1, param2):
@@ -874,7 +900,7 @@ def test_func(param1, param2, param3):
             "param2": "",
             "param3": "description3",
         }
-        assert returns == ["First return value", "Second return value"]
+        assert returns == ["- First return value", "- Second return value"]
 
     def test_function_with_nested_colons(self):
         def test_func(param1, param2):