[Draft] Introduce a module for rewriting Tools

[strawgate]

In this PR, I've collected some of my thoughts on tool re-writing.

The tool_transform function in this PR offers the ability to:

• Modify top-level arguments of an existing tool (e.g., setting constant values, providing new defaults, changing descriptions).
• Add new primitive parameters that are not passed to the original tool but are available to custom hook functions.
• Execute custom logic before a tool call (e.g., logging, input validation, conditional logic via pre_call_hook).
• Process the response from a tool before returning it (e.g., filtering, transforming, logging, rejecting via post_call_hook).

It does it entirely within the existing tool infrastructure without any changes to FastMCP.

Simple transformations look like this (update name):

  proxy_tool(
    proxied_tools["convert_time"],
    server=frontend_server,
    name="transformed_convert_time",
  )
``

As Code:

    proxied_mcp_server = FastMCP.as_proxy(remote_mcp_client)

    proxied_tools = await proxied_mcp_server.get_tools()

    frontend_server = FastMCP("Frontend Server")

    proxy_tool(
        proxied_tools["convert_time"],
        server=frontend_server,
        name="transformed_convert_time",
        description="Converts a time from New York to another timezone.",
        parameter_overrides=[
            ToolParameter[str](
                name="source_timezone",
                description="The timezone of the time to convert.",
                constant="America/New_York",  # Source Timezone is now required to be America/New_York
            ),
            ToolParameter[str](
                name="time",
                description="The time to convert. Must be in the format HH:MM. Default is 3:00.",
                default="3:00",  # Time now defaults to 3:00
            ),
            # No override of the override the target_timezone parameter
        ],
    )

With a Loader class for loading basic transformations from yaml and `proxy_mcp_server_with_overrides` for one-shot mcp server + proxy

[Copilot]

Pull Request Overview

This PR introduces a new module for rewriting and transforming existing FastMCP tools by allowing modifications to tool arguments, hooking pre- and post-call logic, and loading transformation configurations via YAML.

• Introduces new types and protocols for extra parameters and hooks in tools.
• Implements core functions to transform tools and apply parameter overrides.
• Provides loader utilities and example scripts demonstrating programmatic and YAML-based tool transformations.

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/fastmcp/contrib/tool_transformer/types.py	Adds new extra parameter types and hook protocols.
src/fastmcp/contrib/tool_transformer/tool_transformer.py	Implements the tool transformation logic and transformed tool creation.
src/fastmcp/contrib/tool_transformer/loader.py	Provides YAML parsing for tool overrides and tooling to reconfigure tools from a server.
src/fastmcp/contrib/tool_transformer/example-*.py	Example scripts demonstrating various usages of tool transformation.
src/fastmcp/contrib/tool_transformer/base.py	Defines base classes for parameter overrides and extra parameters.
src/fastmcp/contrib/tool_transformer/README.md	Documents the module’s purpose, structure, and usage.
pyproject.toml	Updates dependencies with jsonschema.

[strawgate]

@jlowin I have cleaned this up a bunch

[strawgate]

The latest version of this is vendored into here https://github.com/strawgate/fastmcp-agents/tree/main/src/fastmcp_agents/vendored/tool_transformer

The new setup is to either call transform_tool as before or build the Tool Override model:

tool_override = ToolOverride(
        name="transformed_convert_time",
        description="Converts a time from New York to another timezone.",
        parameter_overrides=[
            ToolParameter[str](
                name="source_timezone",
                description="The timezone of the time to convert.",
                constant="America/New_York",  # Source Timezone is now required to be America/New_York
            ),
            ToolParameter[str](
                name="time",
                description="The time to convert. Must be in the format HH:MM. Default is 3:00.",
                default="3:00",  # Time now defaults to 3:00
            ),
            # No override of the override the target_timezone parameter
        ]
)

And then you can apply it to any FastMCP Tool:

wrapped_tool = tool_override.apply_to_tool(tool)

[strawgate]

Closed via #745 (comment)