Skip to main content
New in version 3.0.0 Tool transformation lets you modify tool schemas - renaming tools, changing descriptions, adjusting tags, and reshaping argument schemas. FastMCP provides two mechanisms that differ in timing and in the options they accept. Deferred transformation with ToolTransform applies modifications when tools flow through a transform chain. Use this for tools from mounted servers, proxies, or other providers where you don’t control the source directly. Immediate transformation with Tool.from_tool() creates a modified tool object right away. Use this when you have direct access to a tool and want to transform it before registration.

ToolTransform

The ToolTransform class is a transform that modifies tools as they flow through a provider. Provide a dictionary mapping original tool names to their transformation configuration.
ToolTransform is useful when you want to modify tools from mounted or proxied servers without changing the original source. A ToolTransform is checked against each tool when the tool reaches it, since a mounted or proxied tool may not exist yet when you add the transform. If a configuration can’t apply to its tool (for example, it hides a required argument that has no default, or names an argument the tool doesn’t have), FastMCP logs an error and leaves that one tool out. Every other tool keeps working, and clients calling the hidden tool get an unknown-tool error.

Tool.from_tool()

Use Tool.from_tool() when you have the tool object and want to create a transformed version for registration.
The standalone @tool decorator (from fastmcp.tools) attaches tool metadata to a function without registering it to any server; Tool.from_tool() accepts the decorated function directly. This separates creation from registration, letting you transform tools before deciding where they go.

Modification Options

The two mechanisms overlap but are not identical. Only ToolTransformConfig sets version and enabled; only Tool.from_tool() accepts annotations, output schemas, and a custom function. Tool-level options: Argument transforms go in arguments on ToolTransformConfig (as ArgTransformConfig) and in transform_args on Tool.from_tool() (as ArgTransform). Argument-level options:

Hiding Arguments

Hide arguments to simplify the interface or inject values the client shouldn’t control.
Hidden arguments disappear from the tool’s schema. The client never sees them, but the underlying function receives the configured value.
default_factory requires hide=True. Visible arguments need static defaults that can be represented in JSON Schema. A hidden argument also cannot be required, and required=True cannot be combined with a default.

Renaming Arguments

Rename arguments to make them more intuitive for LLMs or match your API conventions.

Custom Transform Functions

For advanced scenarios, provide a transform_fn that intercepts tool execution. The function can validate inputs, modify outputs, or add custom logic while still calling the original tool via forward().
The forward() function handles argument mapping automatically. Call it with the transformed argument names, and it maps them back to the original function’s parameters. For direct access to the original function without mapping, use forward_raw() with the original parameter names.

Context-Aware Tool Factories

You can write functions that act as “factories,” generating specialized versions of a tool for different contexts. For example, create a get_my_data tool for the current user by hiding the user_id parameter and providing it automatically.
This pattern is useful for multi-tenant servers where each connection gets tools pre-configured with their identity, or for wrapping generic tools with environment-specific defaults.