Opt out only a top-level bare list or tuple from structured output

Author: Kludex

docs/servers/structured-output.md

@@ -212,7 +212,7 @@ The opposite, `structured_output=True`, turns the automatic detection into a req
 
 Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, on their own, as the items of a `list`, `tuple` or `Sequence`, or as the arms of a union) are opted out for you: they are for the model to read, so auto-detection derives no schema from them (**[Images, audio & icons](media.md)** covers `Image` and `Audio`). `structured_output=True` still forces one for the content-block classes.
 
-A bare `list` or `tuple` is opted out too. Nothing in the annotation says its items aren't blocks, and a schema would send any image it holds twice: once as a block for the model, and again as base64 in `structured_content`. Write the item type (`list[str]`, `tuple[int, ...]`) to get a schema, or pass `structured_output=True` to wrap it as a list of anything.
+A bare `list` or `tuple` is opted out too. Nothing in the annotation says its items aren't blocks, and a schema would send any image it holds twice: once as a block for the model, and again as base64 in `structured_content`. Write the item type (`list[str]`, `tuple[int, ...]`) to get a schema, or pass `structured_output=True` to wrap it as a list of anything. The forced wrapper still has to serialize every item as JSON, so an `Image` or `Audio` in it makes the call fail. Only a bare `list` or `tuple` as the whole annotation is opted out: `list | None` is wrapped like any other union.
 
 ## A class without type hints
 
@@ -243,7 +243,7 @@ There is one way to end up unstructured without asking for it: return a class th
 ## Recap
 
 * The **return type annotation** is the output schema. It's published in `tools/list` as `output_schema`.
-* Scalars, lists, tuples and unions are wrapped in `{"result": ...}`. Models, `TypedDict`s, dataclasses, annotated classes, `dict[str, ...]` and a bare `dict` are objects already and stay as they are.
+* Scalars, `list[...]`, `tuple[...]`, sets and unions are wrapped in `{"result": ...}`. Models, `TypedDict`s, dataclasses, annotated classes, `dict[str, ...]` and a bare `dict` are objects already and stay as they are.
 * Every result carries `content` (text, for the model) **and** `structured_content` (data, for the application).
 * What you return is validated against the schema. A mismatch is a tool error, not a corrupt result.
 * `structured_output=False` opts a tool out. Content blocks, `Image`, `Audio` and a bare `list` or `tuple` opt out by default; a class without type hints opts out silently, so watch for it.

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -51,10 +51,10 @@ def _is_input_required_type(obj: Any) -> bool:
 def _returns_content(annotation: Any) -> bool:
     """Whether a return annotation declares content blocks or the `Image`/`Audio` helpers, bare or as
     the items of a list/tuple or the arms of a union: the values `_convert_to_content` renders as blocks
-    rather than dumping as data. Keep the two in sync. A bare `list`/`tuple` may hold blocks too."""
+    rather than dumping as data. Keep the two in sync."""
     origin = get_origin(annotation)
     if origin is None:
-        return annotation in (list, tuple) or (isinstance(annotation, type) and issubclass(annotation, _CONTENT_TYPES))
+        return isinstance(annotation, type) and issubclass(annotation, _CONTENT_TYPES)
     if origin is Annotated:
         return _returns_content(get_args(annotation)[0])
     if is_union_origin(origin) or origin in _CONTENT_SEQUENCE_ORIGINS:
@@ -446,10 +446,11 @@ def func_metadata(
     else:
         original_annotation = effective_annotation
 
-    if structured_output is None and _returns_content(return_type_expr):
+    if structured_output is None and (return_type_expr in (list, tuple) or _returns_content(return_type_expr)):
         # Content blocks and the Image/Audio helpers are what the model reads, not data for the
         # application: a derived schema would advertise the block's own model as output_schema (and,
         # unless the tool builds its own CallToolResult, echo every block into structured_content).
+        # A bare list/tuple says nothing about its items, so it may hold blocks too.
         # structured_output=True still forces one.
         return FuncMetadata(arg_model=arguments_model)
 

tests/server/mcpserver/test_func_metadata.py

@@ -1046,44 +1046,96 @@ def test_structured_output_true_overrides_the_content_block_rule():
 
 
 def test_structured_output_true_wraps_a_bare_list():
+    """SDK-defined: the explicit flag wraps a bare list as a list of anything instead of rejecting it."""
     meta = func_metadata(_returns_bare_list, structured_output=True)
 
     assert meta.output_schema == snapshot(
         {"properties": {"result": {"items": {}, "type": "array"}}, "required": ["result"], "type": "object"}
     )
-    result = meta.convert_result(_returns_bare_list())
-    assert isinstance(result, CallToolResult)
-    assert result.structured_content == {"result": [1, "a"]}
+    assert meta.convert_result(_returns_bare_list()) == snapshot(
+        CallToolResult(content=[TextContent(text="1"), TextContent(text="a")], structured_content={"result": [1, "a"]})
+    )
 
 
-def test_bare_dict_set_and_frozenset_returns_are_structured():
-    def bare_dict() -> dict:
-        return {"id": 1}
+def _returns_optional_bare_list() -> list | None:
+    return [1]
 
-    def bare_set() -> set:
-        return {1}
 
-    def bare_frozenset() -> frozenset:
-        return frozenset({1})
+def test_a_bare_list_inside_a_union_keeps_its_schema():
+    """SDK-defined: only a bare list/tuple as the whole annotation is opted out; nested ones stay wrapped."""
+    meta = func_metadata(_returns_optional_bare_list)
+
+    assert meta.output_schema == snapshot(
+        {
+            "properties": {"result": {"anyOf": [{"items": {}, "type": "array"}, {"type": "null"}]}},
+            "required": ["result"],
+            "type": "object",
+        }
+    )
+    assert meta.convert_result(_returns_optional_bare_list()) == snapshot(
+        CallToolResult(content=[TextContent(text="1")], structured_content={"result": [1]})
+    )
+
+
+def _returns_bare_dict() -> dict:
+    return {"id": 1}
+
+
+def test_a_bare_dict_is_structured_like_dict_str_any():
+    """SDK-defined: a bare dict is a JSON object already, so it gets an object schema and is not wrapped."""
+    meta = func_metadata(_returns_bare_dict)
 
-    meta = func_metadata(bare_dict)
     assert meta.output_schema == snapshot({"additionalProperties": True, "type": "object"})
-    result = meta.convert_result(bare_dict())
-    assert isinstance(result, CallToolResult)
-    assert result.structured_content == {"id": 1}
+    assert meta.convert_result(_returns_bare_dict()) == snapshot(
+        CallToolResult(
+            content=[
+                TextContent(
+                    text="""\
+{
+  "id": 1
+}\
+"""
+                )
+            ],
+            structured_content={"id": 1},
+        )
+    )
 
-    for func in (bare_set, bare_frozenset):
-        meta = func_metadata(func)
-        assert meta.output_schema == snapshot(
-            {
-                "properties": {"result": {"items": {}, "type": "array", "uniqueItems": True}},
-                "required": ["result"],
-                "type": "object",
-            }
+
+def _returns_bare_set() -> set:
+    return {1}
+
+
+def _returns_bare_frozenset() -> frozenset:
+    return frozenset({1})
+
+
+@pytest.mark.parametrize("tool", [_returns_bare_set, _returns_bare_frozenset])
+def test_a_bare_set_is_wrapped(tool: Callable[..., Any]):
+    """SDK-defined: a bare set/frozenset is wrapped like its parameterized form; it cannot hold content blocks."""
+    meta = func_metadata(tool)
+
+    assert meta.output_schema == snapshot(
+        {
+            "properties": {"result": {"items": {}, "type": "array", "uniqueItems": True}},
+            "required": ["result"],
+            "type": "object",
+        }
+    )
+    assert meta.convert_result(tool()) == snapshot(
+        CallToolResult(
+            content=[
+                TextContent(
+                    text="""\
+[
+  1
+]\
+"""
+                )
+            ],
+            structured_content={"result": [1]},
         )
-        result = meta.convert_result(func())
-        assert isinstance(result, CallToolResult)
-        assert result.structured_content == {"result": [1]}
+    )
 
 
 class _Report(BaseModel):