Skip to main content
New in version 2.0.0 Use this when you need to execute server-side functions and process their results. Tools are executable functions exposed by MCP servers. The client’s list_tools() method discovers what a server offers, and call_tool() executes a tool by name with arguments and returns structured results.

Discovering Tools

list_tools() returns every tool the server advertises as a list of mcp_types.Tool objects, each carrying the tool’s name, description, and JSON input_schema. It follows pagination automatically, so the result is the complete catalog.
Servers can change their catalog while the connection is open and notify the client with a notifications/tools/list_changed notification; a fresh list_tools() call reflects the new set. See Notifications for reacting to that notification. For page-by-page control over large catalogs, list_tools_mcp() returns one raw ListToolsResult at a time and accepts the cursor from the previous page’s next_cursor.
Both methods accept a cache_mode argument when the client was built with a response cache.

Basic Execution

Arguments are passed as a dictionary. For multi-server clients, tool names are automatically prefixed with the server name (e.g., weather_get_forecast for a tool named get_forecast on the weather server).

Execution Options

The call_tool() method supports timeout control and progress monitoring:

Structured Results

New in version 2.10.0 Tool execution returns a CallToolResult object. The .data property provides fully hydrated Python objects including complex types like datetimes and UUIDs, reconstructed from the server’s output schema. Pydantic models can combine named fields with typed additional properties. The client retains those additional fields in .data and hydrates their values using the advertised schema, including inside nested objects and lists.

CallToolResult Properties

Any
Fully hydrated Python objects with complex type support (datetimes, UUIDs, custom classes). FastMCP exclusive.
list[mcp_types.ContentBlock]
Standard MCP content blocks (TextContent, ImageContent, AudioContent, etc.).
dict[str, Any] | None
Standard MCP structured JSON data as sent by the server.
bool
Boolean indicating if the tool execution failed.
dict[str, Any] | None
The _meta object the server attached to the result, if any.
Structured content without an output schema is returned as a dictionary in .data, including an empty object ({}). When structured content is absent or deserialization fails, .data is None. Fall back to content blocks in that case:
FastMCP servers automatically wrap primitive results (like int, str, bool) in a {"result": value} structure. FastMCP clients automatically unwrap this, so you get the original value in .data.

Error Handling

By default, call_tool() raises a ToolError if the tool execution fails:
To handle errors manually instead of catching exceptions, disable automatic error raising:

Sending Metadata

New in version 2.13.1 The meta parameter sends ancillary information alongside tool calls for observability, debugging, or client identification:
See Client Metadata to learn how servers access this data.

Version Selection

New in version 3.0.0 When a server exposes multiple versions of a tool, call_tool() runs the highest by default. Pass version to call a specific one:
See Version Discovery for how to discover available versions.

Raw Protocol Access

For complete control, use call_tool_mcp() which returns the raw MCP protocol object: