Understand Spring AI Tool Mechanism in 5 Minutes: From @Tool Annotation to MCP Tool Bridging Full Chain

Introduction

“Why isn’t my @Tool method being recognized?”

“How do MCP Server tools bridge to my local ChatClient?”

“What’s the relationship between ToolCallback and ToolCallbackProvider?”

These are common confusions for developers new to Spring AI’s Tool mechanism.

Official documentation teaches you how to use it, but rarely explains how it works under the hood. The result is not knowing where to start troubleshooting when problems arise.

In this article, I’ll use plain language to help you understand Spring AI Tool’s underlying runtime mechanism. After reading, you’ll understand:

How a @Tool annotation becomes an AI-callable tool
The responsibilities and use cases for each type of Provider
The complete chain from tool registration to LLM invocation

Version Note (as of 2026-03-22): Spring AI’s latest stable version is 1.1.3, and latest preview version is 2.0.0-M3 (released on 2026-03-17). 1.1.2 is also a stable version, just not the latest stable version as of 2026-03-22. This article is primarily based on the current official Reference/API documentation; for 2.0.0-M3 changes, I’ll mark them separately to avoid mixing “stable version status” with “preview version changes”.

If your current project uses spring-ai-alibaba:1.1.2.0, note that its transitive org.springframework.ai dependency is still 1.1.2, not 1.1.3. So APIs like AugmentedToolCallback that are visible in 1.1.3 may not appear in your IDE yet.

1. Core Interfaces: ToolCallback and ToolCallbackProvider

Bottom line first: ToolCallback is a single tool, ToolCallbackProvider is a provider of tool collections.

1.1 ToolCallback: Abstraction of a Single Tool

ToolCallback is the smallest unit in Spring AI’s tool system, representing a tool that can be called by an AI model.

public interface ToolCallback {
    // Tool definition: name, description, JSON Schema for input parameters
    ToolDefinition getToolDefinition();

    // Tool metadata: e.g., returnDirect controls whether results are returned directly
    ToolMetadata getToolMetadata();

    // Execute the tool, input is a JSON string
    String call(String toolInput);

    // Execute with context
    String call(String toolInput, ToolContext toolContext);
}

Its responsibilities are simple:

Tell the AI what this tool is called, what it does, and what parameters it needs
Receive JSON parameters from the AI, execute logic, return results

Two most common local implementations:

MethodToolCallback — Wraps Java methods (used with @Tool annotation)
FunctionToolCallback — Wraps functional interfaces (Function, Supplier, Consumer, BiFunction, etc.)

1.2 ToolCallbackProvider: Tool Factory

ToolCallbackProvider is responsible for providing tools in batches.

public interface ToolCallbackProvider {
    // Return all tool callbacks
    ToolCallback[] getToolCallbacks();
}

Its responsibility: Collect tools from different sources and expose them uniformly for ChatClient registration.

2. Five Providers: Four Source Types + One Enhancer

In the current official API, ToolCallbackProvider has 5 known implementations. The first four handle “where tools come from”, and the last one handles “wrapping existing tools with enhancements”.

Provider	Tool Source	Characteristics
StaticToolCallbackProvider	Static array	Simplest, immutable after construction, manually create fixed tool sets
MethodToolCallbackProvider	`@Tool` annotated methods	Automatically scans objects for `@Tool` methods and generates ToolCallbacks
SyncMcpToolCallbackProvider	MCP synchronous client	Connects to remote MCP Server, automatically discovers and bridges tools
AsyncMcpToolCallbackProvider	MCP asynchronous client	Similar to Sync but uses async client; also implements `getToolCallbacks()`, plus provides reactive helper capabilities
AugmentedToolCallbackProvider	Enhancement wrapper for existing tools	Appends input Schema extension fields to existing tools, e.g., additional structured metadata

3. MethodToolCallbackProvider: Local Annotation Scanning

This is the most commonly used approach, automatically generating tools through @Tool annotations.

@Service
public class WeatherService {

    @Tool(name = "getWeather", description = "Get weather for a specified city")
    public String getWeather(@JsonProperty("city") String city) {
        return city + ": Sunny, 25\u00B0C";
    }

    @Tool(name = "query_weather_by_city_date", description = "Query weather by city and date")
    public String queryByCityAndDate(
            @JsonProperty("city") String city,
            @JsonProperty("date") String date) {
        return city + " on " + date + ": Cloudy, 22\u00B0C";
    }
}

Registration method:

@Configuration
public class ToolConfig {

    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(weatherService)  // Pass the Service object
                .build();
    }
}

How it works:

MethodToolCallbackProvider uses reflection to scan all methods in weatherService, finds methods with @Tool annotation, and generates a MethodToolCallback for each method.

This example registers 2 tools:

getWeather — Query weather by city
query_weather_by_city_date — Query weather by city and date

4. How to Register Multiple Services?

toolObjects() accepts varargs, you can pass multiple objects:

@Bean
public ToolCallbackProvider allTools(
        WeatherService weatherService,
        OrderService orderService,
        TradeService tradeService,
        GoodsService goodsService) {

    return MethodToolCallbackProvider.builder()
            .toolObjects(weatherService, orderService, tradeService, goodsService)
            .build();
}

Method 2: Multiple Beans (Spring AI auto-merges)

@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(weatherService)
            .build();
}

@Bean
public ToolCallbackProvider orderTools(OrderService orderService) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(orderService)
            .build();
}

If you’re using Spring Boot’s auto-configured MCP Server / MCP Client scenario, the framework collects these ToolCallbackProvider beans and merges them, achieving the same effect.

If you’re manually building a ChatClient, you still need to explicitly pass the ToolCallback[] returned by these Providers to defaultToolCallbacks(...).

5. SyncMcpToolCallbackProvider: Remote Tool Bridging

This is the core of MCP development, wrapping remote MCP Server tools as local ToolCallbacks.

@Component
public class McpClientService {

    @Autowired
    private SyncMcpToolCallbackProvider toolCallbackProvider;

    @PostConstruct
    public void init() {
        // Get all tools from remote MCP servers
        ToolCallback[] toolCallbacks = toolCallbackProvider.getToolCallbacks();

        // Register to ChatClient
        this.chatClient = ChatClient.builder(chatModel)
                .defaultToolCallbacks(toolCallbacks)
                .build();
    }
}

What it does:

MCP servers configured in application.yml
         ↓
Spring AI auto-configures SyncMcpToolCallbackProvider
         ↓
Reads configuration, connects to each MCP Server (starts process or establishes HTTP connection)
         ↓
Calls MCP's listTools API to get tool list
         ↓
Wraps each remote tool as a local ToolCallback
         ↓
Registers to ChatClient, LLM can call them

Result:

chatClient.prompt()
    .user("What's the weather in Beijing?")
    .call()
    .content();
// LLM automatically calls the remote mcp-server's getWeather tool
// Returns: "Beijing: Sunny, 25\u00B0C"

Sync vs Async:

SyncMcpToolCallbackProvider — Uses McpSyncClient, getToolCallbacks() returns ToolCallback[]
AsyncMcpToolCallbackProvider — Uses McpAsyncClient, also implements getToolCallbacks() returning ToolCallback[]; additionally provides asyncToolCallbacks(List<McpAsyncClient>) returning Flux<ToolCallback>

Note: Both can connect to multiple MCP Servers. Your choice depends on whether your application is synchronous or reactive. See Chapter 8 for details.

6. MCP Server vs Client: Each Has Its Role

Many beginners confuse this: Both MCP Server and Client use Providers, will they conflict?

The answer is no. They have a complementary relationship, each responsible for one side:

6.1 MCP Server Side: Two Main Paths Available Now

Path A: @McpTool annotation + annotation scanner
       ↓
Directly exposed as MCP Tool (this is the approach currently recommended by the Boot Starter docs)

Path B: Spring AI ToolCallback path
@Service + @Tool method / ToolCallback Bean / ToolCallbackProvider Bean
       ↓
Auto-converted to MCP Tool spec via tool-callback-converter
       ↓
Exposed to clients via MCP protocol (stdio / SSE / Streamable-HTTP)

6.2 MCP Client Side: Consuming Tools

Connects to MCP Server
       ↓
Gets tool list via MCP protocol (listTools)
       ↓
SyncMcpToolCallbackProvider (remote tools → local ToolCallback)
       ↓
Registers to ChatClient, enabling LLM to call them

6.3 One Diagram to Understand Both Sides

6.4 Simple Analogy

Role	Analogy	Classes Used
MCP Server	Restaurant (exposes menu items)	`@McpTool` or `ToolCallbackProvider`
MCP Client	Food delivery platform (aggregates restaurants)	SyncMcpToolCallbackProvider

A restaurant can either directly use @McpTool to produce its menu, or first produce ToolCallbacks, then have the Server Starter auto-convert them to MCP Tools
The delivery platform uses SyncMcpToolCallbackProvider to turn each restaurant’s “menu” into “orderable items” (local ToolCallbacks) for users

6.5 What If Server Side Doesn’t Use MethodToolCallbackProvider?

A prerequisite here: This question only applies when you choose the @Tool → MethodToolCallbackProvider → MCP Tool path.

// Without MethodToolCallbackProvider
public class WeatherService {
    @Tool(name = "getWeather", description = "...")
    public String getWeather(String city) { ... }
}

Result: The @Tool annotation alone won’t automatically become an MCP Tool. If you haven’t configured MethodToolCallbackProvider, nor wrapped it as another ToolCallback Bean / ToolCallbackProvider Bean, the client’s listTools will return an empty list.

But if you take the @McpTool + annotation scanner path, you don’t need MethodToolCallbackProvider.

7. Complete Call Chain: From Registration to Execution

The following flow diagram uses the @Tool / ToolCallback → ChatClient → tool calling path as the main thread, connecting all stages:

┌─────────────────────────────────────────────────────────────────┐
│                        Registration Phase                        │
└─────────────────────────────────────────────────────────────────┘

@Service + @Tool annotated methods                application.yml MCP config
       │                                              │
       ▼                                              ▼
MethodToolCallbackProvider                   SyncMcpToolCallbackProvider
       │                                              │
       └──────────────────┬───────────────────────────┘
                          ▼
                  ToolCallback[]
                          │
                          ▼
              ChatClient.builder()
                  .defaultToolCallbacks()
                          │
                          ▼
                    ChatClient initialization complete

┌─────────────────────────────────────────────────────────────────┐
│                       Invocation Phase                           │
└─────────────────────────────────────────────────────────────────┘

User: "What's the weather in Beijing?"
       │
       ▼
ChatModel sends request (carrying tool definitions: name + description + inputSchema)
       │
       ▼
AI model decides: needs to call getWeather tool
       │
       ▼
AI returns tool call request (tool name + JSON parameters)
       │
       ▼
ToolCallingManager receives
       │
       ▼
ToolCallbackResolver finds the corresponding ToolCallback
       │
       ▼
ToolCallback.call('{"city":"Beijing"}')
       │
       ▼
Returns: "Beijing: Sunny, 25\u00B0C"
       │
       ▼
ToolResponseMessage sent back to AI model
       │
       ▼
AI generates final response: "The weather in Beijing today is sunny, temperature 25\u00B0C"

8. Five ToolCallback Types: What’s Each For?

We covered Providers above; now let’s look at how the ToolCallbacks they generate differ:

8.1 MethodToolCallback

Purpose: Wraps @Tool annotated Java methods

@Tool(name = "getWeather", description = "Get weather")
public String getWeather(String city) {
    return city + ": Sunny, 25\u00B0C";
}
// ↓ Wrapped into
MethodToolCallback

On execution: Directly invokes Java method via reflection

8.2 FunctionToolCallback

Purpose: Encapsulates existing code functionality through functional interfaces

// Call an existing Service method
FunctionToolCallback.builder("calculatePrice", (Function<String, BigDecimal>) input -> {
        return orderService.calculatePrice(input);
    })
    .build();

On execution: Calls Function.apply()

8.3 SyncMcpToolCallback vs AsyncMcpToolCallback

This is the pair most easily confused.

Both are used for bridging remote MCP Server tools, the difference is only in the underlying MCP client type:

Comparison	SyncMcpToolCallback	AsyncMcpToolCallback
Underlying client	`McpSyncClient`	`McpAsyncClient`
Sync entry point for callers	`getToolCallbacks()`	`getToolCallbacks()`
Generated Provider	`SyncMcpToolCallbackProvider`	`AsyncMcpToolCallbackProvider`
Multiple MCP Server support	Yes	Yes
Additional reactive capability	None	`asyncToolCallbacks(List<McpAsyncClient>) -> Flux<ToolCallback>`

Key point: Both can connect to multiple MCP Servers — you don’t need to choose Async just for multi-Server support!

API Perspective

SyncMcpToolCallbackProvider:

public ToolCallback[] getToolCallbacks()

AsyncMcpToolCallbackProvider:

public ToolCallback[] getToolCallbacks()

public static Flux<ToolCallback> asyncToolCallbacks(List<McpAsyncClient> mcpClients)

In other words: The unified interface exposed externally is still ToolCallback[]; the Async version just additionally provides reactive streaming assembly capability.

8.4 AugmentedToolCallback

This is an implementation that has appeared in the current 1.1.3 API docs but many articles haven’t covered yet.

Note: If your project is still on 1.1.0 or 1.1.2, you likely won’t see AugmentedToolCallback / AugmentedToolCallbackProvider in your IDE. I’ve personally checked the Maven cache: these classes appear in spring-ai-model:1.1.3, but not in 1.1.0 / 1.1.2.

Purpose: Appends input Schema extension fields to existing tools without changing the original tool method signature.

Typical scenarios:

Adding structured metadata fields to tools
Uniformly recording extra parameters during tool calls
Extending the tool protocol without modifying original tool input parameters

The corresponding Provider at the underlying level is AugmentedToolCallbackProvider, with the related low-level tool being ToolInputSchemaAugmenter.

8.5 Which One Should I Use?

Scenario	Recommendation
Spring MVC + standard scenarios	`SyncMcpToolCallbackProvider`
WebFlux reactive applications	`AsyncMcpToolCallbackProvider`
Need to connect to multiple MCP Servers	Either works
Need to append structured fields to existing tools	`AugmentedToolCallbackProvider`

Conclusion: If you’re using Spring MVC, just go with SyncMcpToolCallbackProvider — no need to switch architectures.

8.6 FunctionCallback Is Deprecated, How to Migrate?

Spring AI previously used FunctionCallback, later unified to the ToolCallback API. FunctionCallback is deprecated; migration is recommended.

Why was it deprecated?

Early on, different AI vendors used inconsistent naming. Later it was unified to “tool calling”:

OpenAI: function calling → tool calling
Anthropic: tool use → tool calling

Spring AI aligned with this and deprecated FunctionCallback, unifying on ToolCallback.

Migration Method 1: @Tool Annotation (Recommended)

Old code (FunctionCallback):

@Component
public class WeatherFunction {

    public String getWeather(String city) {
        return city + ": Sunny, 25\u00B0C";
    }
}

// Registration
FunctionCallback callback = FunctionCallback.builder()
    .function("getWeather", weatherFunction)
    .description("Get weather for a specified city")
    .inputType(WeatherRequest.class)
    .build();

New code (@Tool annotation):

@Service
public class WeatherService {

    @Tool(name = "getWeather", description = "Get weather for a specified city")
    public String getWeather(@JsonProperty("city") String city) {
        return city + ": Sunny, 25\u00B0C";
    }
}

// Registration - auto scanning
@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(weatherService)
            .build();
}

Migration Method 2: FunctionToolCallback (Wrapping Existing Interfaces)

If you don’t want to modify existing code, use the wrapping approach:

// Existing Service, no changes needed
@Service
public class OrderService {
    public BigDecimal calculatePrice(String orderId) {
        // Original logic
        return new BigDecimal("99.99");
    }
}

// Wrap with FunctionToolCallback
@Configuration
public class ToolConfig {

    @Bean
    public ToolCallback orderPriceTool(OrderService orderService) {
        return FunctionToolCallback.builder("calculatePrice", orderService::calculatePrice)
            .description("Calculate price based on order ID")
            .inputType(String.class)
            .build();
    }
}

API Migration Reference

Old API	New API
`FunctionCallback`	`ToolCallback`
`FunctionCallback.builder().function()`	`FunctionToolCallback.builder(name, function)`
`FunctionCallback.builder().method()`	`MethodToolCallback.builder()`
`FunctionCallingOptions`	`ToolCallingChatOptions`
`ChatClient.builder().defaultFunctions()`	`ChatClient.builder().defaultTools()`
`FunctionCallingOptions.builder().functionCallbacks()`	`ToolCallingChatOptions.builder().toolCallbacks()`

9. Class Relationship Diagram Cheat Sheet

ToolCallbackProvider (interface)
    │
    ├── StaticToolCallbackProvider       ← Static tool array
    │
    ├── MethodToolCallbackProvider       ← Local @Tool annotated methods
    │
    ├── SyncMcpToolCallbackProvider      ← MCP synchronous client
    │
    ├── AsyncMcpToolCallbackProvider     ← MCP asynchronous client
    │
    └── AugmentedToolCallbackProvider    ← Existing tool enhancer

ToolCallback (interface)
    │
    ├── MethodToolCallback               ← Wraps Java method
    │
    ├── FunctionToolCallback             ← Wraps functional interface
    │
    ├── SyncMcpToolCallback              ← Wraps MCP sync tool
    │
    ├── AsyncMcpToolCallback             ← Wraps MCP async tool
    │
    └── AugmentedToolCallback            ← Wraps enhanced tool

10. Common Questions

Q1: Does the Bean method name (like weatherTools) matter?

A: No, this is just the Spring Bean name. What actually matters is the name in @Tool(name = "getWeather"), that’s the tool name exposed to the LLM.

Q2: Will tools with the same name conflict?

A: By default, usually not. The current MCP Client Boot Starter defaults to using DefaultMcpToolNamePrefixGenerator, which automatically adds prefixes when duplicate names appear across connections, ensuring unique tool names.

Only when you explicitly disable prefix generation (e.g., using McpToolNamePrefixGenerator.noPrefix()) AND multiple MCP Servers expose tools with the same name will an IllegalStateException be thrown due to naming conflicts.

Q3: What happens when tool execution throws an exception?

A: Default configuration spring.ai.tools.throw-exception-on-error=false, exceptions are returned to the model as error messages; setting to true will throw exceptions directly.

11. Current Version Status (as of 2026-03-22)

11.1 First Distinguish “Stable” from “Preview”

Latest Stable Version: 1.1.3
Latest Preview Version: 2.0.0-M3 Release date is 2026-03-17. If you’re writing about production environments, I recommend primarily following the 1.1.3 official Reference; if you’re evaluating Spring Boot 4 / Jackson 3 / Spring AI 2.x, then supplement with M3 changes separately.

11.2 These Are “Currently Still Valid” Directions

FunctionCallback → ToolCallback migration is still the official recommended path But this isn’t a change added in 2.0.0-M3, it’s a unified migration direction that started earlier. Official now maintains a separate migration guide.
Tool Argument Augmentation has entered current tools documentation The official naming in current docs is Tool Argument Augmentation. If you’re using 1.1.3, the core classes are:
- AugmentedToolCallbackProvider
- AugmentedToolCallback
- ToolInputSchemaAugmenter
Dynamic Tool Discovery has official guide ToolSearchToolCallAdvisor can indeed do dynamic tool discovery, and the official guide provides 34% - 64% token savings data. But note: it comes from org.springaicommunity:tool-search-tool, not a core module built into Spring AI core itself.

11.3 2.0.0-M3 Breaking Changes Worth Noting

MCP Annotations migrated into Spring AI core Package name moved from org.springaicommunity.mcp to org.springframework.ai.mcp.annotation.
Spring-specific MCP transport implementation moved into Spring AI project The Spring transport implementation originally in MCP Java SDK moved to org.springframework.ai.mcp related modules.
Jackson 2 → Jackson 3 This is a real breaking change, especially affecting dependencies and package names.
ToolContext no longer automatically includes conversation history This is a breaking change explicitly called out in the M3 release notes, pay special attention when upgrading.

11.4 This Article’s Verification Sources

Spring AI Reference 1.1.3
Spring AI current API Javadoc
Spring AI 2.0.0-M3 release notes
Spring AI 2.0 Dynamic Tool Search guide

Summary

In one sentence:

ToolCallback is the wrapper for a single tool, ToolCallbackProvider is the factory for tool collections. MethodToolCallbackProvider handles local @Tool methods, Sync/AsyncMcpToolCallbackProvider bridges remote MCP tools, AugmentedToolCallbackProvider handles enhancement of existing tools; and on the MCP Server side, you can currently still use the @McpTool annotation route directly.

Understanding this mechanism enables you to:

Clearly know why your tools aren’t being recognized
Understand how MCP tools are integrated
Know which part of the chain to troubleshoot when problems occur

Welcome to follow the WeChat Official Account FishTech Notes for more discussions!