Review nits: Annotated recursion looks at the type only; drop Iterable from content origins; prompt() docstring

- Annotated[X, meta...]: only X is a type, so recurse into it alone (and cover the
  nested-Annotated shape with a test).
- Iterable[...] values are typically generators, which _convert_to_content does not
  unroll, so the annotation no longer counts as content; Sequence stays because its
  runtime value is a list or tuple.
- @mcp.prompt() docstring lists the bare content forms render() now accepts.

Author: maxisbey

src/mcp/server/mcpserver/server.py

@@ -918,8 +918,8 @@ def prompt(
     ) -> Callable[[_CallableT], _CallableT]:
         """Decorator to register a prompt.
 
-        The function returns the prompt messages (a string, `Message`, dict,
-        or a sequence of these), or an `InputRequiredResult` to request
+        The function returns the prompt messages (a string, content block, `Image`/`Audio`,
+        `Message`, dict, or a sequence of these), or an `InputRequiredResult` to request
         client input first (the 2026-07-28 multi-round-trip flow — read
         `ctx.input_responses` on the retry).
 

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

@@ -1,7 +1,7 @@
 import functools
 import inspect
 import json
-from collections.abc import Awaitable, Callable, Iterable, Sequence
+from collections.abc import Awaitable, Callable, Sequence
 from itertools import chain
 from types import GenericAlias
 from typing import Annotated, Any, Union, cast, get_args, get_origin, get_type_hints
@@ -34,7 +34,8 @@ def _is_input_required_type(obj: Any) -> bool:
 
 
 _CONTENT_TYPES = (*get_args(ContentBlock), Image, Audio)
-_CONTENT_SEQUENCE_ORIGINS = (list, tuple, Sequence, Iterable)
+# `_convert_to_content` unrolls list/tuple values; a `Sequence[...]` annotation is one of those at runtime.
+_CONTENT_SEQUENCE_ORIGINS = (list, tuple, Sequence)
 
 
 def _returns_content(annotation: Any) -> bool:
@@ -44,7 +45,9 @@ def _returns_content(annotation: Any) -> bool:
     origin = get_origin(annotation)
     if origin is None:
         return isinstance(annotation, type) and issubclass(annotation, _CONTENT_TYPES)
-    if origin is Annotated or is_union_origin(origin) or origin in _CONTENT_SEQUENCE_ORIGINS:
+    if origin is Annotated:
+        return _returns_content(get_args(annotation)[0])
+    if is_union_origin(origin) or origin in _CONTENT_SEQUENCE_ORIGINS:
         return any(_returns_content(arg) for arg in get_args(annotation))
     return False
 

tests/server/mcpserver/test_func_metadata.py

@@ -871,6 +871,10 @@ def _returns_audio_clips() -> tuple[Audio, ...]:
     raise NotImplementedError
 
 
+def _returns_described_blocks() -> list[Annotated[TextContent, Field(description="one line each")]]:
+    raise NotImplementedError
+
+
 def _returns_call_tool_result_annotated_with_blocks() -> Annotated[CallToolResult, list[TextContent]]:
     raise NotImplementedError
 
@@ -882,6 +886,7 @@ def _returns_call_tool_result_annotated_with_blocks() -> Annotated[CallToolResul
         _returns_blocks,
         _returns_strings_and_images,
         _returns_audio_clips,
+        _returns_described_blocks,
         _returns_call_tool_result_annotated_with_blocks,
     ],
 )