Tool return type handling: generators, None, bytes, non-dict output_schema

[strawgate]

The tool result conversion pipeline in base.py and function_tool.py mishandles several return value patterns, causing crashes or silent data loss.

1. Async generator tools return repr string instead of data

When a tool is an async generator (async def tool() -> AsyncIterator[str]: yield ...), FunctionTool.run() never consumes the generator. The async generator object itself is passed to _convert_to_content, which calls str() on it, producing "<async_generator object ... at 0x...>" as the tool output. No error is raised.

@mcp.tool
async def stream_data(count: int) -> AsyncIterator[str]:
    for i in range(count):
        yield f"item {i}"

result = await client.call_tool("stream_data", {"count": 3})
print(result.data)     # None
print(result.content)  # "<async_generator object ...>"

The fix: detect inspect.isasyncgen(result) after calling the function, and consume into a list.

2. Sync generator text/structured content inconsistency

Sync generators are consumed correctly for text content (Pydantic iterates them) but the resulting list produces inconsistent structured content — result.data is None while text content has the values.

@mcp.tool
def gen_tool() -> list:
    return (x for x in [1, 2, 3])

r = await client.call_tool_mcp("gen_tool", {})
print(r.content[0].text)       # "[1,2,3]"
print(r.structuredContent)     # {"result": []}  — empty!

The generator is consumed during text serialization and exhausted by the time structured content is built. Fix: materialize generators before the dual processing pipeline.

3. Non-UTF8 bytes crash serialization

Tools returning bytes with non-UTF8 content crash with PydanticSerializationError: invalid utf-8 sequence. The tool returns an error response instead of encoding the binary data.

@mcp.tool()
def get_binary() -> bytes:
    return bytes(range(256))
# PydanticSerializationError: invalid utf-8 sequence of 1 bytes from index 128

Fix: catch PydanticSerializationError in default_serializer for bytes and fall back to base64 encoding, or handle bytes specially in _convert_to_content.

4. None return with typed annotation crashes client

When a tool declares -> str but returns None at runtime, the server wraps None into structuredContent as {"result": null}. The MCP SDK client rejects this because null doesn't match the string output schema.

@mcp.tool()
def lookup(key: str) -> str:
    return {"name": "Alice"}.get(key)  # None for missing keys
# Client: RuntimeError: Invalid structured content returned by tool

5. Custom output_schema with non-dict return crashes

When a tool specifies a custom output_schema dict but returns a non-dict value (string, int, list), convert_result raises ValueError: structured_content must be a dict or None at runtime. The auto-generated output_schema auto-wraps via x-fastmcp-wrap-result, but custom schemas don't.

@mcp.tool(output_schema={"type": "object", "properties": {"msg": {"type": "string"}}})
def broken() -> str:
    return "hello"
# ValueError: structured_content must be a dict or None

🤖 Generated with Claude Code

[marvin-context-protocol]

Claude finished @strawgate's task in 5m 8s —— View job

---

Triage: Tool return type handling

All five reported bugs are confirmed via reproduction. However, Issue 5 is intentional behavior — there's an existing test explicitly asserting that error (test_explicit_object_schema_with_non_dict_return_fails). Issues 1–3 are genuine bugs. Issue 4 is a real edge case but involves a type mismatch at runtime (-> str returning None), which is arguably a user error that the framework should handle gracefully rather than crash the client.

Recommendation

Fix Issues 1, 2, and 3 as they represent clear framework bugs. Issue 4 deserves a graceful handling (drop structuredContent when the value is None and the schema doesn't allow it). Issue 5 should be closed as working-as-intended (or at minimum documented better) — the existing test at tests/tools/tool/test_output_schema.py:418 explicitly asserts this behavior.

The fixes are localized to two files:

• src/fastmcp/tools/function_tool.py — FunctionTool.run() (Issues 1 & 2)
• src/fastmcp/tools/base.py — default_serializer() and convert_result() (Issues 3 & 4)

Findings

Issue 1: Async generator — confirmed bug

FunctionTool.run() checks is_coroutine_function(wrapper_fn) (line 248/272), but inspect.iscoroutinefunction() returns False for async generator functions. The async gen function runs through the sync threadpool path, which returns the raw async generator object (never consumed). _convert_to_content then calls str() on it via the fallback serializer, producing "<async_generator object ...>".

Root cause: FunctionTool.run() at function_tool.py:238-281 doesn't check for or handle async generator results.

Issue 2: Sync generator exhaustion — confirmed bug

A sync generator returned by a tool is consumed during _convert_to_content() (line 291 in base.py) when Pydantic iterates it for JSON serialization. By the time pydantic_core.to_jsonable_python(raw_value) is called (line 305), the generator is exhausted, yielding an empty list for structuredContent.

Root cause: convert_result() at base.py:270-321 calls _convert_to_content(raw_value) first (consuming the generator), then to_jsonable_python(raw_value) second (on the exhausted generator).

Issue 3: Non-UTF8 bytes — confirmed bug

default_serializer() calls pydantic_core.to_json(data, fallback=str) which attempts UTF-8 decoding of bytes. Non-UTF8 bytes raise PydanticSerializationError. The crash happens in _convert_to_content → _serialize_with_fallback → default_serializer before structured content is even attempted.

Root cause: default_serializer() at base.py:65-67 has no special handling for bytes.

Issue 4: None return with typed annotation — real edge case

When -> str tool returns None, convert_result() produces structuredContent: {"result": null}. The tool's auto-generated output schema says {"properties": {"result": {"type": "string"}}, "required": ["result"]}. The MCP SDK client validates structuredContent against the output schema and rejects null for a string type.

Root cause: convert_result() at base.py:315-320 doesn't validate that the wrapped value matches the declared schema.

Issue 5: Custom output_schema with non-dict return — intentional behavior

The existing test at test_output_schema.py:418-433 (test_explicit_object_schema_with_non_dict_return_fails) explicitly asserts this ValueError. When a user provides a custom output_schema dict (which must be an object type per MCP spec), they are responsible for returning a dict that matches it. Auto-generated schemas handle wrapping via x-fastmcp-wrap-result, but custom schemas are the user's contract.

Verification

All five bugs reproduced with a standalone script:

=== Issue 1: Async generator tools ===
  BUG CONFIRMED: Got async_generator repr instead of data

=== Issue 2: Sync generator inconsistency ===
  content: [TextContent(text='[1,2,3]')]
  structured_content: {'result': []}
  BUG CONFIRMED: structured_content has empty list, generator exhausted

=== Issue 3: Non-UTF8 bytes crash ===
  BUG CONFIRMED: PydanticSerializationError: invalid utf-8 sequence of 1 bytes from index 128

=== Issue 4: None return with typed annotation ===
  structured_content: {'result': None}
  BUG CONFIRMED: structured_content={'result': null} but output_schema says string

=== Issue 5: Custom output_schema with non-dict return ===
  BUG CONFIRMED: ValueError: structured_content must be a dict or None

Issue 5 is confirmed as intentional — the test test_explicit_object_schema_with_non_dict_return_fails at tests/tools/tool/test_output_schema.py:418 explicitly asserts this error.

Detailed Action Plan

Fix 1: Async generator consumption — function_tool.py:238-281

After calling the function in FunctionTool.run(), add an inspect.isasyncgen(result) check to consume the async generator into a list:

# After line 279 (both timeout and non-timeout paths):
if inspect.isasyncgen(result):
    result = [item async for item in result]

This should be added right before return self.convert_result(result) (line 281). Also consider adding inspect.isgenerator(result) check to materialize sync generators here too (addresses Issue 2 partially).

Fix 2: Sync generator materialization — base.py:270 or function_tool.py:281

The cleanest fix is to materialize generators early, in FunctionTool.run() before calling convert_result():

# In FunctionTool.run(), before self.convert_result(result):
import types
if isinstance(result, types.GeneratorType):
    result = list(result)

Alternatively, materialize in convert_result() at base.py:270 before the dual-use of raw_value, but FunctionTool.run() is the better location since it's the entry point that knows the function was just called.

Fix 3: Non-UTF8 bytes handling — base.py:65-67

Update default_serializer() to handle bytes with non-UTF8 content:

def default_serializer(data: Any) -> str:
    if isinstance(data, bytes):
        try:
            return pydantic_core.to_json(data, fallback=str).decode()
        except pydantic_core.PydanticSerializationError:
            import base64
            return base64.b64encode(data).decode()
    return pydantic_core.to_json(data, fallback=str).decode()

Also need to handle bytes in convert_result() at line 304-306 since to_jsonable_python() also fails for non-UTF8 bytes. The existing except PydanticSerializationError catch at line 306 covers this — it falls back to content-only (no structured_content), which is reasonable.

Fix 4: None return with typed annotation — base.py:315-320

When raw_value is None and there's an output schema, either:

• Option A (simpler): Skip structured_content when raw_value is None — return content-only:

  if raw_value is None:
      return ToolResult(content=content)

• Option B (more nuanced): Only skip when the schema wouldn't allow null. This is more complex and requires JSON Schema validation.

Option A is recommended — it's simple, safe, and None returns already produce empty content lists anyway.

Issue 5: No code change needed

This is intentional behavior. The error message at base.py:115-118 is already clear. If anything, the documentation could mention that custom output_schema requires returning a dict.

Test additions

Each fix needs corresponding tests in tests/tools/tool/test_output_schema.py or a new test file:

• Async generator tool returning multiple items → verify all items collected
• Sync generator → verify structured_content matches text content
• Non-UTF8 bytes → verify base64 fallback (no crash)
• -> str returning None → verify graceful handling (no client crash)

Related Files

File	Relevance	Key Lines
src/fastmcp/tools/function_tool.py	FunctionTool.run() — where async/sync generators are produced but not consumed	238-281
src/fastmcp/tools/base.py	convert_result() — dual pipeline (content + structured) that exhausts generators; default_serializer() — bytes crash	65-67, 270-321
src/fastmcp/utilities/async_utils.py	is_coroutine_function() — returns False for async generators	14-22
src/fastmcp/tools/function_parsing.py	ParsedFunction.from_function() — generates output_schema with x-fastmcp-wrap-result	117-275
tests/tools/tool/test_output_schema.py	Existing test asserting Issue 5 is intentional (test_explicit_object_schema_with_non_dict_return_fails)	418-433

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[marvin-context-protocol]

Thanks for the report. This issue goes beyond what our contributor guidelines ask for — we just need a short problem description and an MRE. Please see our contributing guidelines and condense this issue. We'll triage it once it's trimmed down.