Calling Tools

Execute server-side tools and handle structured results.

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.

async with client:
    tools = await client.list_tools()
    for tool in tools:
        print(tool.name, tool.description)
        print(tool.input_schema)

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.

async with client:
    page = await client.list_tools_mcp()
    while page.next_cursor:
        page = await client.list_tools_mcp(cursor=page.next_cursor)

Both methods accept a cache_mode argument when the client was built with a response cache.

Basic Execution

async with client:
    result = await client.call_tool("add", {"a": 5, "b": 3})
    # result -> CallToolResult with structured and unstructured data

    # Access structured data (automatically deserialized)
    print(result.data)  # 8

    # Access traditional content blocks
    print(result.content[0].text)  # "8"

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:

async with client:
    # With timeout (aborts if execution takes longer than 2 seconds)
    result = await client.call_tool(
        "long_running_task",
        {"param": "value"},
        timeout=2.0
    )

    # With progress handler
    result = await client.call_tool(
        "long_running_task",
        {"param": "value"},
        progress_handler=my_progress_handler
    )

Structured Results

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.

from datetime import datetime
from uuid import UUID

async with client:
    result = await client.call_tool("get_weather", {"city": "London"})

    # FastMCP reconstructs complete Python objects
    weather = result.data
    print(f"Temperature: {weather.temperature}C at {weather.timestamp}")

    # Complex types are properly deserialized
    assert isinstance(weather.timestamp, datetime)
    assert isinstance(weather.station_id, UUID)

    # Raw structured JSON is also available
    print(f"Raw JSON: {result.structured_content}")

CallToolResult Properties

.data · Any

Fully hydrated Python objects with complex type support (datetimes, UUIDs, custom classes). FastMCP exclusive.

.content · list[mcp_types.ContentBlock]

Standard MCP content blocks (TextContent, ImageContent, AudioContent, etc.).

.structured_content · dict[str, Any] | None

Standard MCP structured JSON data as sent by the server.

.is_error · bool

Boolean indicating if the tool execution failed.

For tools without output schemas or when deserialization fails, .data will be None. Fall back to content blocks in that case:

async with client:
    result = await client.call_tool("legacy_tool", {"param": "value"})

    if result.data is not None:
        print(f"Structured: {result.data}")
    else:
        for content in result.content:
            if hasattr(content, 'text'):
                print(f"Text result: {content.text}")

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:

from fastmcp.exceptions import ToolError

async with client:
    try:
        result = await client.call_tool("potentially_failing_tool", {"param": "value"})
        print("Tool succeeded:", result.data)
    except ToolError as e:
        print(f"Tool failed: {e}")

To handle errors manually instead of catching exceptions, disable automatic error raising:

async with client:
    result = await client.call_tool(
        "potentially_failing_tool",
        {"param": "value"},
        raise_on_error=False
    )

    if result.is_error:
        print(f"Tool failed: {result.content[0].text}")
    else:
        print(f"Tool succeeded: {result.data}")

Sending Metadata

The meta parameter sends ancillary information alongside tool calls for observability, debugging, or client identification:

async with client:
    result = await client.call_tool(
        name="send_email",
        arguments={
            "to": "[e-mail]",
            "subject": "Hello",
            "body": "Welcome!"
        },
        meta={
            "trace_id": "abc-123",
            "request_source": "mobile_app"
        }
    )

See Client Metadata to learn how servers access this data.

Raw Protocol Access

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

async with client:
    result = await client.call_tool_mcp("my_tool", {"param": "value"})
    # result -> mcp_types.CallToolResult

    if result.is_error:
        print(f"Tool failed: {result.content}")
    else:
        print(f"Tool succeeded: {result.content}")
        # Note: No automatic deserialization with call_tool_mcp()