fastmcp/docs/python-sdk/fastmcp-tools-tool_transform.mdx

---
title: tool_transform
sidebarTitle: tool_transform
---

# `fastmcp.tools.tool_transform`

## Functions

### `forward` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forward(**kwargs: Any) -> ToolResult
```


Forward to parent tool with argument transformation applied.

This function can only be called from within a transformed tool's custom
function. It applies argument transformation (renaming, validation) before
calling the parent tool.

For example, if the parent tool has args `x` and `y`, but the transformed
tool has args `a` and `b`, and an `transform_args` was provided that maps `x` to
`a` and `y` to `b`, then `forward(a=1, b=2)` will call the parent tool with
`x=1` and `y=2`.

**Args:**
- `**kwargs`: Arguments to forward to the parent tool (using transformed names).

**Returns:**
- The ToolResult from the parent tool execution.

**Raises:**
- `RuntimeError`: If called outside a transformed tool context.
- `TypeError`: If provided arguments don't match the transformed schema.


### `forward_raw` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
forward_raw(**kwargs: Any) -> ToolResult
```


Forward directly to parent tool without transformation.

This function bypasses all argument transformation and validation, calling the parent
tool directly with the provided arguments. Use this when you need to call the parent
with its original parameter names and structure.

For example, if the parent tool has args `x` and `y`, then `forward_raw(x=1,
y=2)` will call the parent tool with `x=1` and `y=2`.

**Args:**
- `**kwargs`: Arguments to pass directly to the parent tool (using original names).

**Returns:**
- The ToolResult from the parent tool execution.

**Raises:**
- `RuntimeError`: If called outside a transformed tool context.


### `apply_transformations_to_tools` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L976" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apply_transformations_to_tools(tools: dict[str, Tool], transformations: dict[str, ToolTransformConfig]) -> dict[str, Tool]
```


Apply a list of transformations to a list of tools. Tools that do not have any transformations
are left unchanged.

Note: tools dict is keyed by prefixed key (e.g., "tool:my_tool"),
but transformations are keyed by tool name (e.g., "my_tool").


## Classes

### `ArgTransform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Configuration for transforming a parent tool's argument.

This class allows fine-grained control over how individual arguments are transformed
when creating a new tool from an existing one. You can rename arguments, change their
descriptions, add default values, or hide them from clients while passing constants.

**Attributes:**
- `name`: New name for the argument. Use None to keep original name, or ... for no change.
- `description`: New description for the argument. Use None to remove description, or ... for no change.
- `default`: New default value for the argument. Use ... for no change.
- `default_factory`: Callable that returns a default value. Cannot be used with default.
- `type`: New type for the argument. Use ... for no change.
- `hide`: If True, hide this argument from clients but pass a constant value to parent.
- `required`: If True, make argument required (remove default). Use ... for no change.
- `examples`: Examples for the argument. Use ... for no change.

**Examples:**

Rename argument 'old_name' to 'new_name'
```python
ArgTransform(name="new_name")
```

Change description only
```python
ArgTransform(description="Updated description")
```

Add a default value (makes argument optional)
```python
ArgTransform(default=42)
```

Add a default factory (makes argument optional)
```python
ArgTransform(default_factory=lambda: time.time())
```

Change the type
```python
ArgTransform(type=str)
```

Hide the argument entirely from clients
```python
ArgTransform(hide=True)
```

Hide argument but pass a constant value to parent
```python
ArgTransform(hide=True, default="constant_value")
```

Hide argument but pass a factory-generated value to parent
```python
ArgTransform(hide=True, default_factory=lambda: uuid.uuid4().hex)
```

Make an optional parameter required (removes any default)
```python
ArgTransform(required=True)
```

Combine multiple transformations
```python
ArgTransform(name="new_name", description="New desc", default=None, type=int)
```


### `ArgTransformConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A model for requesting a single argument transform.


**Methods:**

#### `to_arg_transform` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_arg_transform(self) -> ArgTransform
```

Convert the argument transform to a FastMCP argument transform.


### `TransformedTool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A tool that is transformed from another tool.

This class represents a tool that has been created by transforming another tool.
It supports argument renaming, schema modification, custom function injection,
structured output control, and provides context for the forward() and forward_raw() functions.

The transformation can be purely schema-based (argument renaming, dropping, etc.)
or can include a custom function that uses forward() to call the parent tool
with transformed arguments. Output schemas and structured outputs are automatically
inherited from the parent tool but can be overridden or disabled.

**Attributes:**
- `parent_tool`: The original tool that this tool was transformed from.
- `fn`: The function to execute when this tool is called (either the forwarding
function for pure transformations or a custom user function).
- `forwarding_fn`: Internal function that handles argument transformation and
validation when forward() is called from custom functions.


**Methods:**

#### `run` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L266" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run(self, arguments: dict[str, Any]) -> ToolResult
```

Run the tool with context set for forward() functions.

This method executes the tool's function while setting up the context
that allows forward() and forward_raw() to work correctly within custom
functions.

**Args:**
- `arguments`: Dictionary of arguments to pass to the tool's function.

**Returns:**
- ToolResult object containing content and optional structured output.


#### `from_tool` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L362" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_tool(cls, tool: Tool | Callable[..., Any], name: str | None = None, version: str | NotSetT | None = NotSet, title: str | NotSetT | None = NotSet, description: str | NotSetT | None = NotSet, tags: set[str] | None = None, transform_fn: Callable[..., Any] | None = None, transform_args: dict[str, ArgTransform] | None = None, annotations: ToolAnnotations | NotSetT | None = NotSet, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: Callable[[Any], str] | NotSetT | None = NotSet, meta: dict[str, Any] | NotSetT | None = NotSet) -> TransformedTool
```

Create a transformed tool from a parent tool.

**Args:**
- `tool`: The parent tool to transform.
- `transform_fn`: Optional custom function. Can use forward() and forward_raw()
to call the parent tool. Functions with **kwargs receive transformed
argument names.
- `name`: New name for the tool. Defaults to parent tool's name.
- `version`: New version for the tool. Defaults to parent tool's version.
- `title`: New title for the tool. Defaults to parent tool's title.
- `transform_args`: Optional transformations for parent tool arguments.
Only specified arguments are transformed, others pass through unchanged\:
- Simple rename (str)
- Complex transformation (rename/description/default/drop) (ArgTransform)
- Drop the argument (None)
- `description`: New description. Defaults to parent's description.
- `tags`: New tags. Defaults to parent's tags.
- `annotations`: New annotations. Defaults to parent's annotations.
- `output_schema`: Control output schema for structured outputs\:
- None (default)\: Inherit from transform_fn if available, then parent tool
- dict\: Use custom output schema
- False\: Disable output schema and structured outputs
- `serializer`: Deprecated. Return ToolResult from your tools for full control over serialization.
- `meta`: Control meta information\:
- NotSet (default)\: Inherit from parent tool
- dict\: Use custom meta information
- None\: Remove meta information

**Returns:**
- TransformedTool with the specified transformations.

**Examples:**

# Transform specific arguments only
```python
Tool.from_tool(parent, transform_args={"old": "new"})  # Others unchanged
```

# Custom function with partial transforms
```python
async def custom(x: int, y: int) -> str:
    result = await forward(x=x, y=y)
    return f"Custom: {result}"

Tool.from_tool(parent, transform_fn=custom, transform_args={"a": "x", "b": "y"})
```

# Using **kwargs (gets all args, transformed and untransformed)
```python
async def flexible(**kwargs) -> str:
    result = await forward(**kwargs)
    return f"Got: {kwargs}"

Tool.from_tool(parent, transform_fn=flexible, transform_args={"a": "x"})
```

# Control structured outputs and schemas
```python
# Custom output schema
Tool.from_tool(parent, output_schema={
    "type": "object",
    "properties": {"status": {"type": "string"}}
})

# Disable structured outputs
Tool.from_tool(parent, output_schema=None)

# Return ToolResult for full control
async def custom_output(**kwargs) -> ToolResult:
    result = await forward(**kwargs)
    return ToolResult(
        content=[TextContent(text="Summary")],
        structured_content={"processed": True}
    )
```


### `ToolTransformConfig` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L922" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Provides a way to transform a tool.


**Methods:**

#### `apply` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/tools/tool_transform.py#L955" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apply(self, tool: Tool) -> TransformedTool
```

Create a TransformedTool from a provided tool and this transformation configuration.