TransformedTool: output_schema=False documented but not implemented

[strawgate]

The TransformedTool.from_tool() docstring previously claimed output_schema=False would "disable output schema and structured outputs," but this was never implemented. Passing False would either raise a Pydantic validation error (on the Tool model) or get converted to None which is indistinguishable from "inherit from parent."

A proper implementation needs a way to distinguish "no schema was specified" (NotSet → inherit) from "explicitly disable structured output" (False → strip structured_content from results). This requires either a sentinel value that survives Pydantic model storage or a separate boolean field.

The false documentation was removed in #3823 to avoid misleading users.

🤖 Generated with Claude Code

[marvin-context-protocol]

Claude finished @strawgate's task in 6m 46s —— View job

---

Triage: output_schema=False not implemented in TransformedTool

• Gather repository context
• Investigate TransformedTool and output_schema handling
• Understand current NotSet / None semantics
• Trace what actually happens with output_schema=False today
• Write recommendation and action plan

Recommendation

Add a _disable_structured_output: bool field to TransformedTool and accept Literal[False] in from_tool(). This is the cleanest path because Tool.output_schema is typed dict[str, Any] | None and cannot store False, so a separate boolean is needed to carry the "explicitly disabled" signal into run().

Findings

The three-state problem. TransformedTool.from_tool() currently has two output_schema states:

• NotSet (default) → inherit from transform_fn or parent tool
• None → set output_schema=None, but still auto-detect structured content from dict results at runtime (fallback logic at tool_transform.py:346-352)

There's no way to say "disable structured output entirely" — None doesn't do it because the run() method still tries to serialize dict results as structured_content.

What happens today with output_schema=False. Tracing the code path:

1. from_tool() reaches line 503: final_output_schema = cast(dict | None, output_schema) — cast() is a no-op at runtime, so False passes through
2. Line 589: cls(... output_schema=False ...) attempts to construct a TransformedTool
3. Pydantic validates False against Tool.output_schema: dict[str, Any] | None → ValidationError, since False is neither a dict nor None

The docstring at tool_transform.py:395-398 still claims False is supported (the issue says #3823 removed it, but that PR hasn't been merged into main yet).

The run() method needs changes. Currently in TransformedTool.run():

• When output_schema is None and result is a ToolResult: returns it unchanged, preserving any structured_content (line 317-318)
• When output_schema is None and result is a raw value: attempts to serialize dicts as structured_content (lines 346-352)
• A "disable" mode should strip structured_content in both cases.

ToolTransformConfig (the declarative config path at line 922) doesn't currently expose output_schema at all, so it doesn't need changes for this issue.

Detailed Action Plan

1. Add _disable_structured_output field to TransformedTool

In src/fastmcp/tools/tool_transform.py, add a new field to the TransformedTool class (after transform_args on line 264):

from pydantic.json_schema import SkipJsonSchema

# Inside TransformedTool class:
_disable_structured_output: SkipJsonSchema[bool] = False

Using SkipJsonSchema keeps it out of any JSON schema generation. The underscore prefix signals it's internal.

2. Update from_tool() type signature

Change the output_schema parameter type on TransformedTool.from_tool() (line 373) from:

output_schema: dict[str, Any] | NotSetT | None = NotSet,

to:

output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,

Add Literal to the imports from typing at line 9.

3. Handle False in from_tool() logic

After the existing output schema handling block (around line 486-503), add a check for False:

# Handle output schema
disable_structured_output = False
if output_schema is False:
    final_output_schema = None
    disable_structured_output = True
elif output_schema is NotSet:
    # ... existing inherit logic (lines 487-499) ...
else:
    final_output_schema = cast(dict | None, output_schema)

Then pass _disable_structured_output=disable_structured_output to the cls(...) constructor call at line 589.

4. Update run() to respect _disable_structured_output

In TransformedTool.run(), add an early check after getting the result (after line 313):

result = await self.fn(**arguments)

# If structured output is explicitly disabled, strip it
if self._disable_structured_output:
    if isinstance(result, ToolResult):
        return ToolResult(
            content=result.content,
            structured_content=None,
        )
    return ToolResult(
        content=_convert_to_content(result, serializer=self.serializer),
        structured_content=None,
    )

# ... rest of existing run() logic ...

5. Update Tool.from_tool() delegate

In src/fastmcp/tools/base.py line 414, update the type signature to match:

output_schema: dict[str, Any] | Literal[False] | NotSetT | None = NotSet,

6. Update the docstring

Fix the docstring in from_tool() (lines 395-398). The False option should be documented accurately:

output_schema: Control output schema for structured outputs:
    - NotSet (default): Inherit from transform_fn if available, then parent tool
    - dict: Use custom output schema
    - None: Remove output schema but still auto-detect structured content
    - False: Disable output schema and strip all structured content from results

7. Add tests

In tests/tools/tool_transform/test_schemas.py, add tests:

1. test_transform_output_schema_false_disables_structured_content — verify output_schema=False sets output_schema to None on the tool and returns structured_content=None for dict results
2. test_transform_output_schema_false_strips_tool_result_structured_content — verify that when transform_fn returns a ToolResult with structured_content, output_schema=False strips it
3. test_transform_output_schema_false_vs_none — verify the difference: None still auto-detects dict structured content, False does not
4. test_transform_output_schema_false_mcp_tool — verify to_mcp_tool().outputSchema is None when output_schema=False

Related Files

File	Relevance	Key Lines
src/fastmcp/tools/tool_transform.py	Primary implementation: TransformedTool class, from_tool(), and run()	237-360, 486-503
src/fastmcp/tools/base.py	Tool.from_tool() delegate and output_schema field definition	148-149, 404-436
src/fastmcp/utilities/types.py	NotSet / NotSetT sentinel definitions	29-31
tests/tools/tool_transform/test_schemas.py	Existing output schema tests for TransformedTool	33-309

---

Marvin Context Protocol | Type /marvin to interact further

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