TransformedTool: sync transform_fn crash, shallow copy mutation, str/None shorthand broken

[strawgate]

TransformedTool has four related issues in src/fastmcp/tools/tool_transform.py:

1. run() crashes on sync transform_fn (line 313)

run() unconditionally does await self.fn(**arguments). When transform_fn is a sync function, this raises TypeError: object str can't be used in 'await' expression. FunctionTool.run() handles this correctly with is_coroutine_function + call_sync_fn_in_threadpool — TransformedTool.run() should do the same.

from fastmcp.tools.function_tool import FunctionTool
from fastmcp.tools.tool_transform import TransformedTool

def greet(name: str) -> str:
    return f"Hello, {name}!"

def upper_greet(name: str) -> str:
    return f"HELLO, {name}!"

parent = FunctionTool.from_function(greet)
transformed = TransformedTool.from_tool(parent, transform_fn=upper_greet)

import asyncio
asyncio.run(transformed.run({"name": "World"}))
# TypeError: object str can't be used in 'await' expression

2. from_tool() shallow-copies property schemas (line 634)

parent_props = parent_tool.parameters.get("properties", {}).copy() is a shallow copy. Nested schema dicts (like {"items": {"type": "string"}} inside an array property) are shared references between parent and transformed tool. Mutating the transformed schema corrupts the parent.

from fastmcp.tools.function_tool import FunctionTool
from fastmcp.tools.tool_transform import TransformedTool, ArgTransform

def my_tool(items: list[str], count: int = 5) -> str:
    return f"{items[:count]}"

parent = FunctionTool.from_function(my_tool)
transformed = TransformedTool.from_tool(
    parent, transform_args={"items": ArgTransform(name="data")}
)

# Nested schemas are shared
print(parent.parameters["properties"]["items"]["items"]
      is transformed.parameters["properties"]["data"]["items"])  # True

# Mutating transformed corrupts parent
transformed.parameters["properties"]["data"]["items"]["type"] = "integer"
print(parent.parameters["properties"]["items"]["items"]["type"])  # "integer" — corrupted

$defs is already deepcopy'd (line 633) but properties is not.

3. from_tool() crashes with str/None in transform_args (line 644–651)

The docstring (lines 388–391) documents that transform_args values can be str (simple rename) or None (drop argument), but line 645 assigns the raw value to transform and line 651 calls transform.hide, which crashes with AttributeError: 'str' object has no attribute 'hide'.

from fastmcp.tools.function_tool import FunctionTool
from fastmcp.tools.tool_transform import TransformedTool

def greet(name: str, greeting: str = "Hello") -> str:
    return f"{greeting}, {name}!"

parent = FunctionTool.from_function(greet)
TransformedTool.from_tool(parent, transform_args={"name": "username"})
# AttributeError: 'str' object has no attribute 'hide'

TransformedTool.from_tool(parent, transform_args={"greeting": None})
# AttributeError: 'NoneType' object has no attribute 'hide'

Needs normalization: str → ArgTransform(name=value), None → ArgTransform(hide=True).

4. output_schema=False rejected despite being documented (line 398)

The docstring says output_schema=False disables output schema and structured outputs, but passing it raises a Pydantic validation error because the model only accepts dict | None.

🤖 Generated with Claude Code

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 27s —— View job

---

Triage: All four bugs confirmed

All four reported bugs are verified and reproducible. Here's the analysis, recommended fixes, and a detailed action plan.

---

Recommendation

All four fixes are straightforward, isolated to src/fastmcp/tools/tool_transform.py (with a minor type annotation change needed in src/fastmcp/tools/base.py for Bug 4), and can be shipped in a single PR. None require design decisions — the existing codebase already has the correct patterns elsewhere.

---

Findings

Bug 1: run() crashes on sync transform_fn (line 313)
Line 313 does result = await self.fn(**arguments). When transform_fn is a plain sync function, self.fn returns a non-awaitable, causing TypeError. FunctionTool.run() at function_tool.py:272-279 already handles this correctly using is_coroutine_function + call_sync_fn_in_threadpool from fastmcp.utilities.async_utils.

Bug 2: from_tool() shallow-copies property schemas (line 634)
parent_props = parent_tool.parameters.get("properties", {}).copy() is a shallow copy. Nested schema dicts (e.g. {"items": {"type": "string"}} inside an array property) are shared references. $defs is already deep-copied on line 633, but properties is not. Mutating the transformed schema corrupts the parent.

Bug 3: from_tool() crashes with str/None in transform_args (line 644–651)
The docstring (lines 388–391) documents that transform_args values can be str (simple rename) or None (drop argument), but no normalization happens. Line 645 assigns the raw value to transform, and line 651 calls transform.hide, which crashes with AttributeError.

Bug 4: output_schema=False rejected
The docstring at line 398 says output_schema=False disables output schema. However, the Tool base class defines output_schema: dict[str, Any] | None (line 148-150 of base.py), and Pydantic rightfully rejects False. The from_tool method needs to convert False → None before passing it to the constructor.

Verification

All four bugs were reproduced against the current main (commit faf5f86):

Bug 1 CONFIRMED: TypeError: object str can't be used in 'await' expression
Bug 2 CONFIRMED: Nested schemas are shared references (parent corrupted after mutation)
Bug 3a CONFIRMED: AttributeError: 'str' object has no attribute 'hide'
Bug 3b CONFIRMED: AttributeError: 'NoneType' object has no attribute 'hide'
Bug 4 CONFIRMED: ValidationError: Input should be a valid dictionary [type=dict_type, input_value=False, input_type=bool]

Detailed Action Plan

All changes are in src/fastmcp/tools/tool_transform.py unless noted.

Fix 1: Support sync transform_fn in run() (line 313)

Replace:

result = await self.fn(**arguments)

With the same pattern used in FunctionTool.run():

from fastmcp.utilities.async_utils import call_sync_fn_in_threadpool, is_coroutine_function

if is_coroutine_function(self.fn):
    result = await self.fn(**arguments)
else:
    result = await call_sync_fn_in_threadpool(self.fn, **arguments)

The imports for is_coroutine_function and call_sync_fn_in_threadpool need to be added at the top of the file (they're already available in fastmcp.utilities.async_utils).

Fix 2: Deep-copy properties (line 634)

Change:

parent_props = parent_tool.parameters.get("properties", {}).copy()

To:

parent_props = deepcopy(parent_tool.parameters.get("properties", {}))

deepcopy is already imported in this file (line 7).

Fix 3: Normalize str/None in transform_args (after line 466)

Add normalization after transform_args = transform_args or {} on line 466. Normalize the dict values:

transform_args = {
    k: (
        ArgTransform(name=v) if isinstance(v, str)
        else ArgTransform(hide=True) if v is None
        else v
    )
    for k, v in transform_args.items()
}

Update the type signatures to accept the broader types:

• TransformedTool.from_tool() line 371: dict[str, ArgTransform | str | None] | None
• Tool.from_tool() in base.py line 417: dict[str, ArgTransform | str | None] | None
• _create_forwarding_transform() line 613 stays as dict[str, ArgTransform] | None (receives already-normalized data)

Fix 4: Handle output_schema=False (line 486 area)

In from_tool(), before the output_schema logic, add:

if output_schema is False:
    output_schema = None

Update the output_schema parameter type on TransformedTool.from_tool() (line 373) and Tool.from_tool() in base.py (line 414) to: dict[str, Any] | NotSetT | None | Literal[False].

Note: The docstring says False disables output schema, and None already means "no output schema" internally, so False → None is the correct mapping. output_schema=None is already handled at line 503 (final_output_schema = cast(dict | None, output_schema)).

Tests to add

Add tests in tests/tools/tool_transform/test_tool_transform.py:

1. test_sync_transform_fn_runs — sync transform_fn executes without error
2. test_deep_copy_properties — mutating transformed schema doesn't corrupt parent
3. test_str_shorthand_transform_args — {"name": "username"} renames correctly
4. test_none_shorthand_transform_args — {"greeting": None} hides the arg
5. test_output_schema_false — output_schema=False disables output schema

Related Files

File	Relevance	Key Lines
src/fastmcp/tools/tool_transform.py	Primary file with all four bugs	313 (Bug 1), 634 (Bug 2), 644-651 (Bug 3), 486 area (Bug 4)
src/fastmcp/tools/base.py	Type annotations for output_schema and transform_args on Tool.from_tool()	148-150, 414, 417
src/fastmcp/tools/function_tool.py	Reference implementation for sync/async handling in FunctionTool.run()	271-279
src/fastmcp/utilities/async_utils.py	is_coroutine_function and call_sync_fn_in_threadpool utilities	14-34
tests/tools/tool_transform/test_tool_transform.py	Existing tests for TransformedTool	—

---

Marvin Context Protocol | Type /marvin to interact further

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