fastmcp.client.mixins.tools

Tool-related methods for FastMCP Client.

Classes

ClientToolsMixin ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Mixin providing tool-related methods for Client.

Methods:

list_tools_mcp ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

list_tools_mcp(self: Client) -> mcp_types.ListToolsResult

Send a tools/list request and return the complete MCP protocol result.

Args:

• cursor: Optional pagination cursor from a previous request's nextCursor.
• cache_mode: Response-cache behavior for this call (only active when the client was built with a cache and the connection is modern). "use" (default) serves and stores; "refresh" stores without serving; "bypass" skips the cache. A cursor page always skips the cache.

Returns:

• mcp_types.ListToolsResult: The complete response object from the protocol, containing the list of tools and any additional metadata.

Raises:

• RuntimeError: If called while the client is not connected.
• MCPError: If the request results in a TimeoutError | JSONRPCError

list_tools ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L90" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

list_tools(self: Client, max_pages: int = AUTO_PAGINATION_MAX_PAGES) -> list[mcp_types.Tool]

Retrieve all tools available on the server.

This method automatically fetches all pages if the server paginates results, returning the complete list. For manual pagination control (e.g., to handle large result sets incrementally), use list_tools_mcp() with the cursor parameter.

Args:

• max_pages: Maximum number of pages to fetch before raising. Defaults to 250.
• cache_mode: Response-cache behavior for the first page (only active when the client was built with a cache and the connection is modern). "use" (default) serves and stores; "refresh" stores without serving; "bypass" skips the cache. Subsequent cursor pages always skip the cache.

Returns:

• list[mcp_types.Tool]: A list of all Tool objects.

Raises:

• RuntimeError: If the page limit is reached before pagination completes.
• MCPError: If the request results in a TimeoutError | JSONRPCError

call_tool_mcp ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

call_tool_mcp(self: Client, name: str, arguments: dict[str, Any], progress_handler: ProgressHandler | None = None, timeout: datetime.timedelta | float | int | None = None, meta: dict[str, Any] | None = None) -> mcp_types.CallToolResult

Send a tools/call request and return the complete MCP protocol result.

This method returns the raw CallToolResult object, which includes an isError flag and other metadata. It does not raise an exception if the tool call results in an error.

Args:

• name: The name of the tool to call.
• arguments: Arguments to pass to the tool.
• timeout: The timeout for the tool call. Defaults to None.
• progress_handler: The progress handler to use for the tool call. Defaults to None.
• meta: Additional metadata to include with the request. This is useful for passing contextual information (like user IDs, trace IDs, or preferences) that shouldn't be tool arguments but may influence server-side processing. The server can access this via context.request_context.meta. Defaults to None.

Returns:

• mcp_types.CallToolResult: The complete response object from the protocol, containing the tool result and any additional metadata.

Raises:

• RuntimeError: If called while the client is not connected.
• MCPError: If the tool call requests results in a TimeoutError | JSONRPCError

call_tool ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/mixins/tools.py#L281" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

call_tool(self: Client, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult

Call a tool on the server.

Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.

Args:

• name: The name of the tool to call.
• arguments: Arguments to pass to the tool. Defaults to None.
• version: Specific tool version to call. If None, calls highest version.
• timeout: The timeout for the tool call. Defaults to None.
• progress_handler: The progress handler to use for the tool call. Defaults to None.
• raise_on_error: Whether to raise an exception if the tool call results in an error. Defaults to True.
• meta: Additional metadata to include with the request. This is useful for passing contextual information (like user IDs, trace IDs, or preferences) that shouldn't be tool arguments but may influence server-side processing. The server can access this via context.request_context.meta. Defaults to None.

Returns:

• The content returned by the tool. If the tool returns structured outputs, they are returned as a dataclass (if an output schema is available) or a dictionary; otherwise, a list of content blocks is returned. Note: to receive both structured and unstructured outputs, use call_tool_mcp instead and access the raw result object.

Raises:

• ToolError: If the tool call results in an error.
• MCPError: If the tool call request results in a TimeoutError | JSONRPCError
• RuntimeError: If called while the client is not connected.