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 FastMCP, tools are Python functions exposed to LLMs through the MCP protocol. Tools in FastMCP transform regular Python functions into capabilities that LLMs can invoke during conversations. When an LLM decides to use a tool:

1. It sends a request with parameters based on the tool’s schema.
2. FastMCP validates these parameters against your function’s signature.
3. Your function executes with the validated inputs.
4. 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:

When this tool is registered, FastMCP automatically:

• Uses the function name (add) as the tool name.
• Parses the function’s docstring for the tool description and, if present, per-parameter descriptions (see Docstring Descriptions).
• 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.

Decorator Arguments

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

Using with Methods

The @mcp.tool decorator registers tools immediately, which doesn’t work with instance or class methods (you’d see self or cls as required parameters). For methods, use the standalone @tool decorator to attach metadata, then register the bound method:

Async Support

FastMCP supports both asynchronous (async def) and synchronous (def) functions as tools. Synchronous tools automatically run in a threadpool to avoid blocking the event loop, so multiple tool calls can execute concurrently even if individual tools perform blocking operations.

For I/O-bound operations like network requests or database queries, async tools are still preferred since they’re more efficient than threadpool dispatch. Use sync tools when working with synchronous libraries or for simple operations where the threading overhead doesn’t matter.

Thread affinity

This section applies to sync tools only. Async tools already run on the event loop and are not affected. Some libraries bind state to the thread they’re first used from and break when called from a different thread. The most common case is Windows COM — libraries like uiautomation, comtypes, and parts of pywin32 require CoInitialize to have been called on the current thread, and worker-pool threads don’t initialize COM by default. Similar constraints apply to tkinter, some GPU bindings (CUDA contexts), and certain hardware drivers. For these cases, pass run_in_thread=False so FastMCP invokes the sync function inline on the event loop thread instead of dispatching it to a worker:

The tradeoff is that the event loop is blocked for the duration of the call — other in-flight requests wait until the tool returns. Keep run_in_thread=False reserved for tools that genuinely need thread affinity, and prefer short-running calls in that path. Inline sync calls have no cancellation checkpoints, so timeout cannot interrupt them. Combining timeout with run_in_thread=False on a sync function is rejected at registration — drop one or the other.

Arguments

By default, FastMCP converts Python functions into MCP tools by inspecting the function’s signature and type annotations. This allows you to use standard Python type annotations for your tools. In general, the framework strives to “just work”: idiomatic Python behaviors like parameter defaults and type annotations are automatically translated into MCP schemas. However, there are a number of ways to customize the behavior of your tools.

Type Annotations

MCP tools have typed arguments, and FastMCP uses type annotations to determine those types. Therefore, you should use standard Python type annotations for tool arguments:

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

FastMCP supports all types that Pydantic supports as fields, including all Pydantic custom types. A few FastMCP-specific behaviors to note: Binary Data: bytes parameters accept raw strings without automatic base64 decoding. For base64 data, use str and decode manually with base64.b64decode(). Enums: Clients send enum values ("red"), not names ("RED"). Your function receives the Enum member (Color.RED). Paths and UUIDs: String inputs are automatically converted to Path and UUID objects. Pydantic Models: Must be provided as JSON objects (dicts), not stringified JSON. Even with flexible validation, {"user": {"name": "Alice"}} works, but {"user": '{"name": "Alice"}'} does not.

Optional Arguments

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

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.

Validation Modes

By default, FastMCP uses Pydantic’s flexible validation that coerces compatible inputs to match your type annotations. This improves compatibility with LLM clients that may send string representations of values (like "10" for an integer parameter). If you need stricter validation that rejects any type mismatches, you can enable strict input validation. Strict mode uses the MCP SDK’s built-in JSON Schema validation to validate inputs against the exact schema before passing them to your function:

Validation Behavior Comparison:

The default flexible validation mode is recommended for most use cases as it handles common LLM client behaviors gracefully while still providing strong type safety through Pydantic’s validation.

Parameter Metadata

You can provide additional metadata about parameters in several ways:

Docstring Descriptions

FastMCP parses your function’s docstring to extract both the tool description and per-parameter descriptions. Google, NumPy, and Sphinx docstring styles are all supported — the parser tries each and uses whichever finds parameter descriptions:

The free-form text above the Args section — whether a single line or multiple paragraphs — becomes the tool description, and each parameter’s docstring entry becomes the description for that parameter in the generated schema. Sections like Returns, Raises, and Example are excluded from the description but otherwise ignored. If a parameter already has an explicit description — via Annotated[x, "..."] or Field(description=...) — that description takes precedence over the docstring. This makes it safe to adopt docstring-based descriptions incrementally: existing annotations keep working, and docstrings fill in the gaps.

Simple String Descriptions

For basic parameter descriptions, you can use a convenient shorthand with Annotated:

This shorthand syntax is equivalent to using Field(description=...) but more concise for simple descriptions.

Advanced Metadata with Field

For validation constraints and advanced metadata, use Pydantic’s Field class with Annotated:

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

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

Hiding Parameters from the LLM

To inject values at runtime without exposing them to the LLM (such as user_id, credentials, or database connections), use dependency injection with Depends(). Parameters using Depends() are automatically excluded from the tool schema:

See Custom Dependencies for more details on dependency injection.

Return Values

FastMCP tools can return data in two complementary formats: traditional content blocks (like text and images) and structured outputs (machine-readable JSON). When you add return type annotations, FastMCP automatically generates output schemas to validate the structured data and enables clients to deserialize results back to Python objects. Understanding how these three concepts work together:

• Return Values: What your Python function returns (determines both content blocks and structured data)
• Structured Outputs: JSON data sent alongside traditional content for machine processing
• Output Schemas: JSON Schema declarations that describe and validate the structured output format

The following sections explain each concept in detail.

Content Blocks

FastMCP automatically converts tool return values into appropriate MCP content blocks:

• str: Sent as TextContent
• bytes: Base64 encoded and sent as BlobResourceContents (within an EmbeddedResource)
• fastmcp.utilities.types.Image: Sent as ImageContent
• fastmcp.utilities.types.Audio: Sent as AudioContent
• fastmcp.utilities.types.File: Sent as base64-encoded EmbeddedResource
• MCP SDK content blocks: Sent as-is
• A list of any of the above: Converts each item according to the above rules
• None: Results in an empty response

Media Helper Classes

FastMCP provides helper classes for returning images, audio, and files. When you return one of these classes, either directly or as part of a list, FastMCP automatically converts it to the appropriate MCP content block. For example, if you return a fastmcp.utilities.types.Image object, FastMCP will convert it to an MCP ImageContent block with the correct MIME type and base64 encoding.

Each helper class accepts either path= or data= (mutually exclusive):

• path: File path (string or Path object) - MIME type detected from extension
• data: Raw bytes - requires format= parameter for MIME type
• format: Optional format override (e.g., “png”, “wav”, “pdf”)
• name: Optional name for File when using data=
• annotations: Optional MCP annotations for the content

Structured Output

The 6/18/2025 MCP spec update introduced structured content, which is a new way to return data from tools. Structured content is a JSON object that is sent alongside traditional content. FastMCP automatically creates structured outputs alongside traditional content when your tool returns data that has a JSON object representation. This provides machine-readable JSON data that clients can deserialize back to Python objects. Automatic Structured Content Rules:

• Object-like results (dict, Pydantic models, dataclasses) → Always become structured content (even without output schema)
• Non-object results (int, str, list) → Only become structured content if there’s an output schema to validate/serialize them
• All results → Always become traditional content blocks for backward compatibility

Dictionaries and Objects

When your tool returns a dictionary, dataclass, or Pydantic model, FastMCP automatically creates structured content from it. The structured content contains the actual object data, making it easy for clients to deserialize back to native objects.

Primitives and Collections

When your tool returns a primitive type (int, str, bool) or a collection (list, set), FastMCP needs a return type annotation to generate structured content. The annotation tells FastMCP how to validate and serialize the result. Without a type annotation, the tool only produces content:

When you add a return annotation, such as -> int, FastMCP generates structuredContent by wrapping the primitive value in a {"result": ...} object, since JSON schemas require object-type roots for structured output:

Typed Models

Return type annotations work with any type that can be converted to a JSON schema. Dataclasses and Pydantic models are particularly useful because FastMCP extracts their field definitions to create detailed schemas.

The Person dataclass becomes an output schema (second tab) that describes the expected format. When executed, clients receive the result (third tab) with both content and structuredContent fields.

Output Schemas

The 6/18/2025 MCP spec update introduced output schemas, which are a new way to describe the expected output format of a tool. When an output schema is provided, the tool must return structured output that matches the schema. When you add return type annotations to your functions, FastMCP automatically generates JSON schemas that describe the expected output format. These schemas help MCP clients understand and validate the structured data they receive.

Primitive Type Wrapping

For primitive return types (like int, str, bool), FastMCP automatically wraps the result under a "result" key to create valid structured output:

Manual Schema Control

You can override the automatically generated schema by providing a custom output_schema:

Schema generation works for most common types including basic types, collections, union types, Pydantic models, TypedDict structures, and dataclasses.

ToolResult and Metadata

For complete control over tool responses, return a ToolResult object. This gives you explicit control over all aspects of the tool’s output: traditional content, structured data, and metadata.

ToolResult accepts three fields: content - The traditional MCP content blocks that clients display to users. Can be a string (automatically converted to TextContent), a list of MCP content blocks, or any serializable value (converted to JSON string). At least one of content or structured_content must be provided.

structured_content - A dictionary containing structured data that matches your tool’s output schema. This enables clients to programmatically process the results. If you provide structured_content, it must be a dictionary or None. If only structured_content is provided, it will also be used as content (converted to JSON string).

meta

Runtime metadata about the tool execution. Use this for performance metrics, debugging information, or any client-specific data that doesn’t belong in the content or structured output.

When returning ToolResult, you have full control - FastMCP won’t automatically wrap or transform your data. ToolResult can be returned with or without an output schema.

Custom Serialization

When you need custom serialization (like YAML, Markdown tables, or specialized formats), return ToolResult with your serialized content. This makes the serialization explicit and visible in your tool’s code:

Error Handling

If your tool encounters an error, you can raise a standard Python exception (ValueError, TypeError, FileNotFoundError, custom exceptions, etc.) or a FastMCP ToolError. By default, all exceptions (including their details) are logged and converted into an MCP error response to be sent back to the client LLM. This helps the LLM understand failures and react appropriately. If you want to mask internal error details for security reasons, you can:

1. Use the mask_error_details=True parameter when creating your FastMCP instance:

2. Or use ToolError to explicitly control what error information is sent to clients:

When mask_error_details=True, only error messages from ToolError will include details, other exceptions will be converted to a generic message.

Timeouts

Tools can specify a timeout parameter to limit how long execution can take. When the timeout is exceeded, the client receives an MCP error and the tool stops processing. This protects your server from unexpectedly slow operations that could block resources or leave clients waiting indefinitely.

Timeouts are specified in seconds as a float. When a tool exceeds its timeout, FastMCP returns an MCP error with code -32000 and a message indicating which tool timed out and how long it ran. Both sync and async tools support timeouts—sync functions run in thread pools, so the timeout applies to the entire operation regardless of execution model.

Timeouts vs Background Tasks

Timeouts apply to foreground execution—when a tool runs directly in response to a client request. They protect your server from tools that unexpectedly hang due to network issues, resource contention, or other transient problems.

When a tool times out, FastMCP logs a warning suggesting task mode. For operations you know will be long-running, use task=True instead—background tasks offload work to distributed workers and let clients poll for progress.

Component Visibility

You can control which tools are enabled for clients using server-level enabled control. Disabled tools don’t appear in list_tools and can’t be called.

See Visibility for the complete visibility control API including key formats, tag-based filtering, and provider-level control.

MCP Annotations

FastMCP 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. FastMCP accepts either a plain dict or ToolAnnotations; the examples below use ToolAnnotations for consistency and stronger editor/type support.

FastMCP supports these standard annotations:

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.

Using Annotation Hints

MCP clients like Claude and ChatGPT use annotation hints to determine when to skip confirmation prompts and how to present tools to users. The most commonly used hint is readOnlyHint, which signals that a tool only reads data without making changes. Read-only tools improve user experience by:

• Skipping confirmation prompts for safe operations
• Allowing broader access without security concerns
• Enabling more aggressive batching and caching

Mark a tool as read-only when it retrieves data, performs calculations, or checks status without modifying state:

For tools that write to databases, send notifications, create/update/delete resources, or trigger workflows, omit readOnlyHint or set it to False. Use destructiveHint=True for operations that cannot be undone. Client-specific behavior:

• ChatGPT: Skips confirmation prompts for read-only tools in Chat mode (see ChatGPT integration)
• Claude: Uses hints to understand tool safety profiles and make better execution decisions

Notifications

FastMCP automatically sends notifications/tools/list_changed notifications to connected clients when tools are added, removed, enabled, or disabled. This allows clients to stay up-to-date with the current tool set without manually polling for changes.

Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications. Clients can handle these notifications using a message handler to automatically refresh their tool lists or update their interfaces.

Accessing the 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.

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)
• Request Information: ctx.request_id, ctx.client_id

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

Server Behavior

Duplicate Tools

You can control how the FastMCP server behaves if you register the same component twice. Identity is the component’s type, name, and version together, so a tool and a prompt may share a name, and two versions of one tool coexist. Only an exact repeat of all three counts as a duplicate. The on_duplicate argument sets that policy once for every component type.

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

You can dynamically remove tools from a server through its local provider:

Versioning

Tools support versioning, allowing you to maintain multiple implementations under the same name while clients automatically receive the highest version. See Versioning for complete documentation on version comparison, retrieval, and migration patterns.