Tools

Tools are the core building blocks that allow your LLM to interact with external systems, execute code, and access data that isn’t in its training data. In FlashMCP, tools are Python functions exposed to LLMs through the MCP protocol.

What Are Tools?

Tools in FlashMCP transform regular Python functions into capabilities that LLMs can invoke during conversations. When an LLM decides to use a tool:

It sends a request with parameters based on the tool’s schema.
FlashMCP validates these parameters against your function’s signature.
Your function executes with the validated inputs.
The result is returned to the LLM, which can use it in its response.

This allows LLMs to perform tasks like querying databases, calling APIs, making calculations, or accessing files—extending their capabilities beyond what’s in their training data.

The `@tool` Decorator

Creating a tool is as simple as decorating a Python function with @mcp.tool():

from FlashMCP import FlashMCP

mcp = FlashMCP(name="CalculatorServer")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Adds two integer numbers together."""
    return a + b

When this tool is registered, FlashMCP automatically:

Uses the function name (add) as the tool name.
Uses the function’s docstring (Adds two integer numbers...) as the tool description.
Generates an input schema based on the function’s parameters and type annotations.
Handles parameter validation and error reporting.

The way you define your Python function dictates how the tool appears and behaves for the LLM client.

Functions with *args or **kwargs are not supported as tools. This restriction exists because FlashMCP needs to generate a complete parameter schema for the MCP protocol, which isn’t possible with variable argument lists.

Parameters

Annotations

Type annotations for parameters are essential for proper tool functionality. They:

Inform the LLM about the expected data types for each parameter
Enable FlashMCP to validate input data from clients
Generate accurate JSON schemas for the MCP protocol

Use standard Python type annotations for parameters:

@mcp.tool()
def analyze_text(
    text: str,
    max_tokens: int = 100,
    language: str | None = None
) -> dict:
    """Analyze the provided text."""
    # Implementation...

Parameter Metadata

You can provide additional metadata about parameters using Pydantic’s Field class with Annotated. This approach is preferred as it’s more modern and keeps type hints separate from validation rules:

from typing import Annotated
from pydantic import Field

@mcp.tool()
def process_image(
    image_url: Annotated[str, Field(description="URL of the image to process")],
    resize: Annotated[bool, Field(description="Whether to resize the image")] = False,
    width: Annotated[int, Field(description="Target width in pixels", ge=1, le=2000)] = 800,
    format: Annotated[
        Literal["jpeg", "png", "webp"], 
        Field(description="Output image format")
    ] = "jpeg"
) -> dict:
    """Process an image with optional resizing."""
    # Implementation...

You can also use the Field as a default value, though the Annotated approach is preferred:

@mcp.tool()
def search_database(
    query: str = Field(description="Search query string"),
    limit: int = Field(10, description="Maximum number of results", ge=1, le=100)
) -> list:
    """Search the database with the provided query."""
    # Implementation...

Field provides several validation and documentation features:

description: Human-readable explanation of the parameter (shown to LLMs)
ge/gt/le/lt: Greater/less than (or equal) constraints
min_length/max_length: String or collection length constraints
pattern: Regex pattern for string validation
default: Default value if parameter is omitted

Supported Types

FlashMCP supports a wide range of type annotations, including all Pydantic types:

Type Annotation	Example	Description
Basic types	`int`, `float`, `str`, `bool`	Simple scalar values - see Built-in Types
Binary data	`bytes`	Binary content - see Binary Data
Date and Time	`datetime`, `date`, `timedelta`	Date and time objects - see Date and Time Types
Collection types	`list[str]`, `dict[str, int]`, `set[int]`	Collections of items - see Collection Types
Optional types	`float \| None`, `Optional[float]`	Parameters that may be null/omitted - see Union and Optional Types
Union types	`str \| int`, `Union[str, int]`	Parameters accepting multiple types - see Union and Optional Types
Constrained types	`Literal["A", "B"]`, `Enum`	Parameters with specific allowed values - see Constrained Types
Paths	`Path`	File system paths - see Paths
UUIDs	`UUID`	Universally unique identifiers - see UUIDs
Pydantic models	`UserData`	Complex structured data - see Pydantic Models

For additional type annotations not listed here, see the Parameter Types section below for more detailed information and examples.

Optional Arguments

FlashMCP follows Python’s standard function parameter conventions. Parameters without default values are required, while those with default values are optional.

@mcp.tool()
def search_products(
    query: str,                   # Required - no default value
    max_results: int = 10,        # Optional - has default value
    sort_by: str = "relevance",   # Optional - has default value
    category: str | None = None   # Optional - can be None
) -> list[dict]:
    """Search the product catalog."""
    # Implementation...

In this example, the LLM must provide a query parameter, while max_results, sort_by, and category will use their default values if not explicitly provided.

Metadata

While FlashMCP infers the name and description from your function, you can override these and add tags using arguments to the @mcp.tool decorator:

@mcp.tool(
    name="find_products",           # Custom tool name for the LLM
    description="Search the product catalog with optional category filtering.", # Custom description
    tags={"catalog", "search"}      # Optional tags for organization/filtering
)
def search_products_implementation(query: str, category: str | None = None) -> list[dict]:
    """Internal function description (ignored if description is provided above)."""
    # Implementation...
    print(f"Searching for '{query}' in category '{category}'")
    return [{"id": 2, "name": "Another Product"}]

name: Sets the explicit tool name exposed via MCP.
description: Provides the description exposed via MCP. If set, the function’s docstring is ignored for this purpose.
tags: A set of strings used to categorize the tool. Clients might use tags to filter or group available tools.

Async Tools

FlashMCP seamlessly supports both standard (def) and asynchronous (async def) functions as tools.

# Synchronous tool (suitable for CPU-bound or quick tasks)
@mcp.tool()
def calculate_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
    """Calculate the distance between two coordinates."""
    # Implementation...
    return 42.5

# Asynchronous tool (ideal for I/O-bound operations)
@mcp.tool()
async def fetch_weather(city: str) -> dict:
    """Retrieve current weather conditions for a city."""
    # Use 'async def' for operations involving network calls, file I/O, etc.
    # This prevents blocking the server while waiting for external operations.
    async with aiohttp.ClientSession() as session:
        async with session.get(f"https://api.example.com/weather/{city}") as response:
            # Check response status before returning
            response.raise_for_status()
            return await response.json()

Use async def when your tool needs to perform operations that might wait for external systems (network requests, database queries, file access) to keep your server responsive.

Return Values

FlashMCP automatically converts the value returned by your function into the appropriate MCP content format for the client:

str: Sent as TextContent.
dict, list, Pydantic BaseModel: Serialized to a JSON string and sent as TextContent.
bytes: Base64 encoded and sent as BlobResourceContents (often within an EmbeddedResource).
FlashMCP.Image: A helper class for easily returning image data. Sent as ImageContent.
None: Results in an empty response (no content is sent back to the client).

FlashMCP will attempt to serialize other types to a string if possible.

At this time, FlashMCP responds only to your tool’s return value, not its return annotation.

from FlashMCP import FlashMCP, Image
import io
try:
    from PIL import Image as PILImage
except ImportError:
    raise ImportError("Please install the `pillow` library to run this example.")

mcp = FlashMCP("Image Demo")

@mcp.tool()
def generate_image(width: int, height: int, color: str) -> Image:
    """Generates a solid color image."""
    # Create image using Pillow
    img = PILImage.new("RGB", (width, height), color=color)

    # Save to a bytes buffer
    buffer = io.BytesIO()
    img.save(buffer, format="PNG")
    img_bytes = buffer.getvalue()

    # Return using FlashMCP's Image helper
    return Image(data=img_bytes, format="png")

@mcp.tool()
def do_nothing() -> None:
    """This tool performs an action but returns no data."""
    print("Performing a side effect...")
    return None

Error Handling

New in version: 2.3.4 If your tool encounters an error, you can raise a standard Python exception (ValueError, TypeError, FileNotFoundError, custom exceptions, etc.) or a FlashMCP ToolError. In all cases, the exception is logged and converted into an MCP error response to be sent back to the client LLM. For security reasons, the error message is not included in the response by default. However, if you raise a ToolError, the contents of the exception are included in the response. This allows you to provide informative error messages to the client LLM on an opt-in basis, which can help the LLM understand failures and react appropriately.

from FlashMCP import FlashMCP
from FlashMCP.exceptions import ToolError

@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide a by b."""

    # Python exceptions raise errors but the contents are not sent to clients
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("Both arguments must be numbers.")

    if b == 0:
        # ToolError contents are sent back to clients
        raise ToolError("Division by zero is not allowed.")
    return a / b

Annotations

New in version: 2.2.7 FlashMCP allows you to add specialized metadata to your tools through annotations. These annotations communicate how tools behave to client applications without consuming token context in LLM prompts. Annotations serve several purposes in client applications:

Adding user-friendly titles for display purposes
Indicating whether tools modify data or systems
Describing the safety profile of tools (destructive vs. non-destructive)
Signaling if tools interact with external systems

You can add annotations to a tool using the annotations parameter in the @mcp.tool() decorator:

@mcp.tool(
    annotations={
        "title": "Calculate Sum",
        "readOnlyHint": True,
        "openWorldHint": False
    }
)
def calculate_sum(a: float, b: float) -> float:
    """Add two numbers together."""
    return a + b

FlashMCP supports these standard annotations:

Annotation	Type	Default	Purpose
`title`	string	-	Display name for user interfaces
`readOnlyHint`	boolean	false	Indicates if the tool only reads without making changes
`destructiveHint`	boolean	true	For non-readonly tools, signals if changes are destructive
`idempotentHint`	boolean	false	Indicates if repeated identical calls have the same effect as a single call
`openWorldHint`	boolean	true	Specifies if the tool interacts with external systems

Remember that annotations help make better user experiences but should be treated as advisory hints. They help client applications present appropriate UI elements and safety controls, but won’t enforce security boundaries on their own. Always focus on making your annotations accurately represent what your tool actually does.

MCP Context

Tools can access MCP features like logging, reading resources, or reporting progress through the Context object. To use it, add a parameter to your tool function with the type hint Context.

from FlashMCP import FlashMCP, Context

mcp = FlashMCP(name="ContextDemo")

@mcp.tool()
async def process_data(data_uri: str, ctx: Context) -> dict:
    """Process data from a resource with progress reporting."""
    await ctx.info(f"Processing data from {data_uri}")
    
    # Read a resource
    resource = await ctx.read_resource(data_uri)
    data = resource[0].content if resource else ""
    
    # Report progress
    await ctx.report_progress(progress=50, total=100)
    
    # Example request to the client's LLM for help
    summary = await ctx.sample(f"Summarize this in 10 words: {data[:200]}")
    
    await ctx.report_progress(progress=100, total=100)
    return {
        "length": len(data),
        "summary": summary.text
    }

The Context object provides access to:

Logging: ctx.debug(), ctx.info(), ctx.warning(), ctx.error()
Progress Reporting: ctx.report_progress(progress, total)
Resource Access: ctx.read_resource(uri)
LLM Sampling: ctx.sample(...)
Request Information: ctx.request_id, ctx.client_id

For full documentation on the Context object and all its capabilities, see the Context documentation.

Parameter Types

FlashMCP supports a wide variety of parameter types to give you flexibility when designing your tools. FlashMCP generally supports all types that Pydantic supports as fields, including all Pydantic custom types. This means you can use any type that can be validated and parsed by Pydantic in your tool parameters. FlashMCP supports type coercion when possible. This means that if a client sends data that doesn’t match the expected type, FlashMCP will attempt to convert it to the appropriate type. For example, if a client sends a string for a parameter annotated as int, FlashMCP will attempt to convert it to an integer. If the conversion is not possible, FlashMCP will return a validation error.

Built-in Types

The most common parameter types are Python’s built-in scalar types:

@mcp.tool()
def process_values(
    name: str,             # Text data
    count: int,            # Integer numbers
    amount: float,         # Floating point numbers
    enabled: bool          # Boolean values (True/False)
):
    """Process various value types."""
    # Implementation...

These types provide clear expectations to the LLM about what values are acceptable and allow FlashMCP to validate inputs properly. Even if a client provides a string like “42”, it will be coerced to an integer for parameters annotated as int.

Date and Time Types

FlashMCP supports various date and time types from the datetime module:

from datetime import datetime, date, timedelta

@mcp.tool()
def process_date_time(
    event_date: date,             # ISO format date string or date object
    event_time: datetime,         # ISO format datetime string or datetime object
    duration: timedelta = timedelta(hours=1)  # Integer seconds or timedelta
) -> str:
    """Process date and time information."""
    # Types are automatically converted from strings
    assert isinstance(event_date, date)  
    assert isinstance(event_time, datetime)
    assert isinstance(duration, timedelta)
    
    return f"Event on {event_date} at {event_time} for {duration}"

datetime - Accepts ISO format strings (e.g., “2023-04-15T14:30:00”)
date - Accepts ISO format date strings (e.g., “2023-04-15”)
timedelta - Accepts integer seconds or timedelta objects

Collection Types

FlashMCP supports all standard Python collection types:

@mcp.tool()
def analyze_data(
    values: list[float],           # List of numbers
    properties: dict[str, str],    # Dictionary with string keys and values
    unique_ids: set[int],          # Set of unique integers
    coordinates: tuple[float, float],  # Tuple with fixed structure
    mixed_data: dict[str, list[int]] # Nested collections
):
    """Analyze collections of data."""
    # Implementation...

All collection types can be used as parameter annotations:

list[T] - Ordered sequence of items
dict[K, V] - Key-value mapping
set[T] - Unordered collection of unique items
tuple[T1, T2, ...] - Fixed-length sequence with potentially different types

Collection types can be nested and combined to represent complex data structures. JSON strings that match the expected structure will be automatically parsed and converted to the appropriate Python collection type.

Union and Optional Types

For parameters that can accept multiple types or may be omitted:

@mcp.tool()
def flexible_search(
    query: str | int,              # Can be either string or integer
    filters: dict[str, str] | None = None,  # Optional dictionary
    sort_field: str | None = None  # Optional string
):
    """Search with flexible parameter types."""
    # Implementation...

Modern Python syntax (str | int) is preferred over older Union[str, int] forms. Similarly, str | None is preferred over Optional[str].

Constrained Types

When a parameter must be one of a predefined set of values, you can use either Literal types or Enums:

Literals

Literals constrain parameters to a specific set of values:

from typing import Literal

@mcp.tool()
def sort_data(
    data: list[float],
    order: Literal["ascending", "descending"] = "ascending",
    algorithm: Literal["quicksort", "mergesort", "heapsort"] = "quicksort"
):
    """Sort data using specific options."""
    # Implementation...

Literal types:

Specify exact allowable values directly in the type annotation
Help LLMs understand exactly which values are acceptable
Provide input validation (errors for invalid values)
Create clear schemas for clients

Enums

For more structured sets of constrained values, use Python’s Enum class:

from enum import Enum

class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

@mcp.tool()
def process_image(
    image_path: str, 
    color_filter: Color = Color.RED
):
    """Process an image with a color filter."""
    # Implementation...
    # color_filter will be a Color enum member

When using Enum types:

Clients should provide the enum’s value (e.g., “red”), not the enum member name (e.g., “RED”)
FlashMCP automatically coerces the string value into the appropriate Enum object
Your function receives the actual Enum member (e.g., Color.RED)
Validation errors are raised for values not in the enum

Binary Data

There are two approaches to handling binary data in tool parameters:

Bytes

@mcp.tool()
def process_binary(data: bytes):
    """Process binary data directly.
    
    The client can send a binary string, which will be 
    converted directly to bytes.
    """
    # Implementation using binary data
    data_length = len(data)
    # ...

When you annotate a parameter as bytes, FlashMCP will:

Convert raw strings directly to bytes
Validate that the input can be properly represented as bytes

FlashMCP does not automatically decode base64-encoded strings for bytes parameters. If you need to accept base64-encoded data, you should handle the decoding manually as shown below.

Base64-encoded strings

from typing import Annotated
from pydantic import Field

@mcp.tool()
def process_image_data(
    image_data: Annotated[str, Field(description="Base64-encoded image data")]
):
    """Process an image from base64-encoded string.
    
    The client is expected to provide base64-encoded data as a string.
    You'll need to decode it manually.
    """
    # Manual base64 decoding
    import base64
    binary_data = base64.b64decode(image_data)
    # Process binary_data...

This approach is recommended when you expect to receive base64-encoded binary data from clients.

Paths

The Path type from the pathlib module can be used for file system paths:

from pathlib import Path

@mcp.tool()
def process_file(path: Path) -> str:
    """Process a file at the given path."""
    assert isinstance(path, Path)  # Path is properly converted
    return f"Processing file at {path}"

When a client sends a string path, FlashMCP automatically converts it to a Path object.

UUIDs

The UUID type from the uuid module can be used for unique identifiers:

import uuid

@mcp.tool()
def process_item(
    item_id: uuid.UUID  # String UUID or UUID object
) -> str:
    """Process an item with the given UUID."""
    assert isinstance(item_id, uuid.UUID)  # Properly converted to UUID
    return f"Processing item {item_id}"

When a client sends a string UUID (e.g., “123e4567-e89b-12d3-a456-426614174000”), FlashMCP automatically converts it to a UUID object.

Pydantic Models

For complex, structured data with nested fields and validation, use Pydantic models:

from pydantic import BaseModel, Field
from typing import Optional

class User(BaseModel):
    username: str
    email: str = Field(description="User's email address")
    age: int | None = None
    is_active: bool = True

@mcp.tool()
def create_user(user: User):
    """Create a new user in the system."""
    # The input is automatically validated against the User model
    # Even if provided as a JSON string or dict
    # Implementation...

Using Pydantic models provides:

Clear, self-documenting structure for complex inputs
Built-in data validation
Automatic generation of detailed JSON schemas for the LLM
Automatic conversion from dict/JSON input

Clients can provide data for Pydantic model parameters as either:

A JSON object (string)
A dictionary with the appropriate structure
Nested parameters in the appropriate format

Pydantic Fields

FlashMCP supports robust parameter validation through Pydantic’s Field class. This is especially useful to ensure that input values meet specific requirements beyond just their type. Note that fields can be used outside Pydantic models to provide metadata and validation constraints. The preferred approach is using Annotated with Field:

from typing import Annotated
from pydantic import Field

@mcp.tool()
def analyze_metrics(
    # Numbers with range constraints
    count: Annotated[int, Field(ge=0, le=100)],         # 0 <= count <= 100
    ratio: Annotated[float, Field(gt=0, lt=1.0)],       # 0 < ratio < 1.0
    
    # String with pattern and length constraints
    user_id: Annotated[str, Field(
        pattern=r"^[A-Z]{2}\d{4}$",                     # Must match regex pattern
        description="User ID in format XX0000"
    )],
    
    # String with length constraints
    comment: Annotated[str, Field(min_length=3, max_length=500)] = "",
    
    # Numeric constraints
    factor: Annotated[int, Field(multiple_of=5)] = 10,  # Must be multiple of 5
):
    """Analyze metrics with validated parameters."""
    # Implementation...

You can also use Field as a default value, though the Annotated approach is preferred:

@mcp.tool()
def validate_data(
    # Value constraints
    age: int = Field(ge=0, lt=120),                     # 0 <= age < 120
    
    # String constraints
    email: str = Field(pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$"),  # Email pattern
    
    # Collection constraints
    tags: list[str] = Field(min_length=1, max_length=10)  # 1-10 tags
):
    """Process data with field validations."""
    # Implementation...

Common validation options include:

Validation	Type	Description
`ge`, `gt`	Number	Greater than (or equal) constraint
`le`, `lt`	Number	Less than (or equal) constraint
`multiple_of`	Number	Value must be a multiple of this number
`min_length`, `max_length`	String, List, etc.	Length constraints
`pattern`	String	Regular expression pattern constraint
`description`	Any	Human-readable description (appears in schema)

When a client sends invalid data, FlashMCP will return a validation error explaining why the parameter failed validation.

Server Behavior

Duplicate Tools

New in version: 2.1.0 You can control how the FlashMCP server behaves if you try to register multiple tools with the same name. This is configured using the on_duplicate_tools argument when creating the FlashMCP instance.

from FlashMCP import FlashMCP

mcp = FlashMCP(
    name="StrictServer",
    # Configure behavior for duplicate tool names
    on_duplicate_tools="error"
)

@mcp.tool()
def my_tool(): return "Version 1"

# This will now raise a ValueError because 'my_tool' already exists
# and on_duplicate_tools is set to "error".
# @mcp.tool()
# def my_tool(): return "Version 2"

The duplicate behavior options are:

"warn" (default): Logs a warning and the new tool replaces the old one.
"error": Raises a ValueError, preventing the duplicate registration.
"replace": Silently replaces the existing tool with the new one.
"ignore": Keeps the original tool and ignores the new registration attempt.

Removing Tools

New in version: 2.3.4 You can dynamically remove tools from a server using the remove_tool method:

from FlashMCP import FlashMCP

mcp = FlashMCP(name="DynamicToolServer")

@mcp.tool()
def calculate_sum(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

mcp.remove_tool("calculate_sum")

Legacy JSON Parsing

New in version: 2.2.10 FlashMCP 1.0 and < 2.2.10 relied on a crutch that attempted to work around LLM limitations by automatically parsing stringified JSON in tool arguments (e.g., converting "[1,2,3]" to [1,2,3]). As of FlashMCP 2.2.10, this behavior is disabled by default because it circumvents type validation and can lead to unexpected type coercion issues (e.g. parsing “true” as a bool and attempting to call a tool that expected a string, which would fail type validation). Most modern LLMs correctly format JSON, but if working with models that unnecessarily stringify JSON (as was the case with Claude Desktop in late 2024), you can re-enable this behavior on your server by setting the environment variable FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS=1. We strongly recommend leaving this disabled unless necessary.

Get Started

Servers

Deployment

Clients

Patterns

Tools

What Are Tools?

Tools

The `@tool` Decorator

Parameters

Annotations

Parameter Metadata

Supported Types

Optional Arguments

Metadata

Async Tools

Return Values

Error Handling

Annotations

MCP Context

Parameter Types

Built-in Types

Date and Time Types

Collection Types

Union and Optional Types

Constrained Types

Literals

Enums

Binary Data

Bytes

Base64-encoded strings

Paths

UUIDs

Pydantic Models

Pydantic Fields

Server Behavior

Duplicate Tools

Removing Tools

Legacy JSON Parsing

Get Started

Servers

Deployment

Clients

Patterns

​What Are Tools?

​Tools

​The @tool Decorator

​Parameters

​Annotations

​Parameter Metadata

​Supported Types

​Optional Arguments

​Metadata

​Async Tools

​Return Values

​Error Handling

​Annotations

​MCP Context

​Parameter Types

​Built-in Types

​Date and Time Types

​Collection Types

​Union and Optional Types

​Constrained Types

​Literals

​Enums

​Binary Data

​Bytes

​Base64-encoded strings

​Paths

​UUIDs

​Pydantic Models

​Pydantic Fields

​Server Behavior

​Duplicate Tools

​Removing Tools

​Legacy JSON Parsing

What Are Tools?

Tools

The `@tool` Decorator

Parameters

Annotations

Parameter Metadata

Supported Types

Optional Arguments

Metadata

Async Tools

Return Values

Error Handling

Annotations

MCP Context

Parameter Types

Built-in Types

Date and Time Types

Collection Types

Union and Optional Types

Constrained Types

Literals

Enums

Binary Data

Bytes

Base64-encoded strings

Paths

UUIDs

Pydantic Models

Pydantic Fields

Server Behavior

Duplicate Tools

Removing Tools

Legacy JSON Parsing