First-class tool transformation

[jlowin]

Add support for Tool Transformation (Tool.from_tool) to create enhanced tool variants

This release introduces a powerful new feature: tool transformation, enabling developers to generate customized variants of existing tools without duplicating logic.

Using Tool.from_tool(), you can now:
• Modify a tool’s name, description, tags, and annotations
• Rename or hide arguments, add descriptions, change types, and inject default values (including via factories)
• Add runtime validation or modify behavior with a custom transform_fn while preserving access to the parent tool via forward() and forward_raw()

This allows more intuitive schemas for LLMs, seamless adaptation of external tools (e.g. from OpenAPI or proxies), and layering of transformations across contexts. See the new TransformedTool and ArgTransform classes for details.

---

Intended to supersede #599 (following offline discussions with @strawgate) - though this PR may not fully replace all #599 functionality, such as YAML, which will come in subsequent PR once core machinery is in place. Decorators may come in subsequent PR as well.

[strawgate]

Very straightforward to implement, draft PR here strawgate/fastmcp-agents#37

I ended up quickly implementing constant parameter overrides via a wrapper and it was super easy

[Copilot]

Pull Request Overview

This PR introduces support for tool transformation by adding a new API (Tool.from_tool) that generates enhanced tool variants while removing legacy handling of exclude_args.

• Introduces the from_tool class method and a ParsedFunction helper to enable transformation features.
• Removes the exclude_args attribute from Tool and updates related tests and OpenAPI initialization accordingly.
• Adjusts configuration in authentication providers and updates documentation to include tool transformation patterns.

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/utilities/test_types.py	Added tests for handling ellipsis annotations.
tests/server/test_tool_exclude_args.py	Updated tests to verify that excluded arguments are removed from parameters.
src/fastmcp/tools/tool.py	Added the from_tool method and ParsedFunction; removed exclude_args attribute and legacy logic.
src/fastmcp/server/openapi.py	Removed exclude_args parameter from initialization.
src/fastmcp/server/server.py	Added a new get_tool method to retrieve individual tools.
src/fastmcp/server/auth/providers/bearer_env.py	Updated sentinel defaults to use EllipsisType.
docs/docs.json	Added a new documentation page for tool transformation.

Comments suppressed due to low confidence (5)

src/fastmcp/tools/tool.py:47

• The removal of the 'exclude_args' field from the Tool model is a breaking change; ensure that all dependent modules and documentation are updated to reflect this design change.

exclude_args: list[str] | None = Field(

src/fastmcp/tools/tool.py:99

• [nitpick] Consider expanding the docstring for the new from_tool method to clearly describe the purpose of each parameter, especially the transform_fn and transform_args, to improve code clarity for API users.

def from_tool(

src/fastmcp/server/openapi.py:226

• The removal of the exclude_args parameter from the OpenAPI init method should be verified to ensure it aligns with the updated tool transformation design; update the documentation or migration notes accordingly.

-        exclude_args: list[str] | None = None,

src/fastmcp/server/auth/providers/bearer_env.py:33

• [nitpick] Switching to EllipsisType as a sentinel value is a valid new pattern; please ensure that the configuration loading mechanism properly handles these Ellipsis defaults in all environments.

public_key: str | None | EllipsisType = ...,

tests/server/test_tool_exclude_args.py:24

• [nitpick] Verifying the absence of 'state' in the tool's parameters is a clear test of the transformation behavior; ensure that similar validation is added wherever exclude_args functionality is migrated or transformed.

assert "state" not in echo.parameters["properties"]