Create enhanced tool variants with modified schemas, argument mappings, and custom behavior.
New in version: 2.8.0
Tool transformation allows you to create new, enhanced tools from existing ones. This powerful feature enables you to adapt tools for different contexts, simplify complex interfaces, or add custom logic without duplicating code.
q
instead of query
).Tool.from_tool()
class method. At its simplest, you can use it to change a tool’s top-level metadata like its name
, description
, or tags
.
In the following simple example, we take a generic search
tool and adjust its name and description to help an LLM client better understand its purpose.
find_products
with a clear, domain-specific purpose and relevant tags, even though it still uses the original generic search
function’s logic.
Tool.from_tool()
class method is the primary way to create a transformed tool. It takes the following parameters:
tool
: The tool to transform. This is the only required argument.name
: An optional name for the new tool.description
: An optional description for the new tool.transform_args
: A dictionary of ArgTransform
objects, one for each argument you want to modify.transform_fn
: An optional function that will be called instead of the parent tool’s logic.output_schema
: Control output schema and structured outputs (see Output Schema Control).tags
: An optional set of tags for the new tool.annotations
: An optional set of ToolAnnotations
for the new tool.serializer
: An optional function that will be called to serialize the result of the new tool.TransformedTool
object that wraps the parent tool and applies the transformations you specify. You can add this tool to your MCP server using its add_tool()
method.
ArgTransform
objects to the transform_args
parameter of Tool.from_tool()
. Each key is the name of the original argument you want to modify.
transform_args
entry for arguments you want to modify. All other arguments will be passed through unchanged.ArgTransform
object. This object has the following parameters:
name
: The new name for the argument.description
: The new description for the argument.default
: The new default value for the argument.default_factory
: A function that will be called to generate a default value for the argument. This is useful for arguments that need to be generated for each tool call, such as timestamps or unique IDs.hide
: Whether to hide the argument from the LLM.required
: Whether the argument is required, usually used to make an optional argument be required instead.type
: The new type for the argument.default_factory
with hide=True
, because dynamic defaults cannot be represented in a JSON schema for the client. You can only set required=True for arguments that do not declare a default value.user_id
argument:
q
argument and expand it to search_query
:
default
parameter. Here, we change the default value of the y
argument to 10:
hide=True
. Note that you can only hide arguments that have a default value (or for which you provide a new default), because the LLM can’t provide a value at call time.
hide=True
with default=<value>
.to
, subject
, and body
parameters. The api_key
is supplied automatically from an environment variable.
For values that must be generated for each tool call (like timestamps or unique IDs), use default_factory
, which is called with no arguments every time the tool is called. For example,
default_factory
can only be used with hide=True
. This is because visible parameters need static defaults that can be represented in a JSON schema for the client.required=True
. This has no effect if the argument was already required.
from_tool()
method takes a transform_fn
parameter, which is an async function that replaces the parent tool’s logic and gives you complete control over the tool’s execution.
transform_fn
is an async function that completely replaces the parent tool’s logic.
Critically, the transform function’s arguments are used to determine the new tool’s final schema. Any arguments that are not already present in the parent tool schema OR the transform_args
will be added to the new tool’s schema. Note that when transform_args
and your function have the same argument name, the transform_args
metadata will take precedence, if provided.
transform_fn
are ignored. Only its arguments are used to determine the final schema.forward()
and forward_raw()
functions.
Both forward()
and forward_raw()
are async functions that let you call the parent tool from within your transform_fn
:
forward()
(recommended): Automatically handles argument mapping based on your ArgTransform
configurations. Call it with the transformed argument names.forward_raw()
: Bypasses all transformation and calls the parent tool directly with its original argument names. This is rarely needed unless you’re doing complex argument manipulation, perhaps without arg_transforms
.x
and y
are positive before calling the parent tool:
forward()
with the same argument names as the parent tool:transform_fn
includes **kwargs
in its signature, it will receive all arguments from the parent tool after ArgTransform
configurations have been applied. This is powerful for creating flexible validation functions that don’t require you to add every argument to the function signature.
In the following example, we wrap a parent tool that accepts two arguments x
and y
. These are renamed to a
and b
in the transformed tool, and the transform only validates a
, passing the other argument through as **kwargs
.
**kwargs
receives the renamed argument b
, not the original argument y
. It is therefore recommended to use with forward()
, not forward_raw()
.MCPConfig
, you can also apply a subset of tool transformations
directly in the MCPConfig json file.
tools
section is a dictionary of tool names to tool configurations. Each tool configuration is a
dictionary of tool properties.
See the MCPConfigTransport documentation for more details.
New in version: 2.10.0
Transformed tools inherit output schemas from their parent by default, but you can control this behavior:
Inherit from Parent (Default)
ToolResult
for complete control over both content blocks and structured outputs.
get_my_data
tool that is specific to the currently logged-in user by hiding the user_id
parameter and providing it automatically.