tool

fastmcp.tools.tool

Functions

default_serializer

default_serializer(data: Any) -> str

tool

tool(name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool]

Standalone decorator to create a tool without registering it to a server.

This decorator creates a FunctionTool object from a function. Unlike @server.tool(), this does NOT register the tool with any server - you must explicitly add it using server.add_tool().

This is useful for:

• Creating tools that will be transformed before registration
• Defining tools in modules that are discovered by FileSystemProvider
• Creating reusable tool definitions

This decorator supports multiple calling patterns:

• @tool (without parentheses)
• @tool() (with empty parentheses)
• @tool(“custom_name”) (with name as first argument)
• @tool(name=“custom_name”) (with name as keyword argument)

Args:

• name_or_fn: Either a function (when used as @tool), a string name, or None
• name: Optional name for the tool (keyword-only, alternative to name_or_fn)
• title: Optional title for the tool
• description: Optional description of what the tool does
• icons: Optional icons for the tool
• tags: Optional set of tags for categorizing the tool
• output_schema: Optional JSON schema for the tool’s output
• annotations: Optional annotations about the tool’s behavior
• meta: Optional meta information about the tool
• task: Optional task configuration for background execution (default False)

Returns:

• A FunctionTool when decorating a function, or a decorator function when
• called with parameters.

Classes

ToolResult

Methods:

to_mcp_result

to_mcp_result(self) -> list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult

Tool

Internal tool registration info.

Methods:

to_mcp_tool

to_mcp_tool(self, **overrides: Any) -> MCPTool

Convert the FastMCP tool to an MCP tool.

from_function

from_function(fn: Callable[..., Any], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: ToolResultSerializerType | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionTool

Create a Tool from a function.

run

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

Run the tool with arguments.

This method is not implemented in the base Tool class and must be implemented by subclasses.

run() can EITHER return a list of ContentBlocks, or a tuple of (list of ContentBlocks, dict of structured output).

convert_result

convert_result(self, raw_value: Any) -> ToolResult

Convert a raw result to ToolResult.

Handles ToolResult passthrough and converts raw values using the tool’s attributes (serializer, output_schema) for proper conversion.

register_with_docket

register_with_docket(self, docket: Docket) -> None

Register this tool with docket for background execution.

add_to_docket

add_to_docket(self, docket: Docket, arguments: dict[str, Any], **kwargs: Any) -> Execution

Schedule this tool for background execution via docket.

Args:

• docket: The Docket instance
• arguments: Tool arguments
• fn_key: Function lookup key in Docket registry (defaults to self.key)
• task_key: Redis storage key for the result
• **kwargs: Additional kwargs passed to docket.add()

from_tool

from_tool(cls, tool: Tool) -> TransformedTool

FunctionTool

Methods:

to_mcp_tool

to_mcp_tool(self, **overrides: Any) -> MCPTool

Convert the FastMCP tool to an MCP tool.

Extends the base implementation to add task execution mode if enabled.

from_function

from_function(cls, fn: Callable[..., Any], name: str | None = None, title: str | None = None, description: str | None = None, icons: list[Icon] | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, output_schema: dict[str, Any] | NotSetT | None = NotSet, serializer: ToolResultSerializerType | None = None, meta: dict[str, Any] | None = None, task: bool | TaskConfig | None = None) -> FunctionTool

Create a Tool from a function.

run

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

Run the tool with arguments.

register_with_docket

register_with_docket(self, docket: Docket) -> None

Register this tool with docket for background execution.

FunctionTool registers the underlying function, which has the user’s Depends parameters for docket to resolve.

add_to_docket

add_to_docket(self, docket: Docket, arguments: dict[str, Any], **kwargs: Any) -> Execution

Schedule this tool for background execution via docket.

FunctionTool splats the arguments dict since .fn expects **kwargs.

Args:

• docket: The Docket instance
• arguments: Tool arguments
• fn_key: Function lookup key in Docket registry (defaults to self.key)
• task_key: Redis storage key for the result
• **kwargs: Additional kwargs passed to docket.add()

ParsedFunction

Methods:

from_function

from_function(cls, fn: Callable[..., Any], exclude_args: list[str] | None = None, validate: bool = True, wrap_non_object_output_schema: bool = True) -> ParsedFunction