Enabling Large Language Models to Call Your Java Methods with Spring AI Tool Calling

Large language models cannot directly obtain real‑time or private information such as the current time, weather, or database inventory, nor can they perform actions like placing orders or sending emails.

Tool Calling fills this gap

By exposing Java methods as tools, the model can request their execution; Spring AI runs the method and feeds the result back to the model for a final answer.

@Tool: Turning a method into a tool

Annotate a method with @Tool and provide a clear description. Example:

class DateTimeTools {
    @Tool(description = "获取用户当前时区的日期和时间")
    String getCurrentDateTime() {
        return LocalDateTime.now()
            .atZone(LocaleContextHolder.getTimeZone().toZoneId())
            .toString();
    }
}

Register the tool with the chat client:

String answer = chatClient.prompt()
        .user("现在几点了？")
        .tools(new DateTimeTools())
        .call()
        .content();
// Model sees it needs time → calls getCurrentDateTime() → answers

The description is the sole basis for the model to decide whether and when to invoke the tool, so it must be explicit.

@ToolParam: Tools with parameters

When a tool requires input, annotate each parameter with @ToolParam and describe its meaning. Example:

class WeatherService {
    @Tool(description = "查询指定城市的当前天气")
    String getWeather(@ToolParam(description = "城市名称，如：北京") String city) {
        // Call real weather API here
        return city + "今天晴，25℃";
    }
}

String answer = chatClient.prompt()
        .user("北京天气怎么样？")
        .tools(new WeatherService())
        .call()
        .content();
// Model extracts city=北京 → calls getWeather("北京") → returns answer

Execution flow: model requests, Spring AI executes

The model never runs your code; it returns a request like call getWeather(北京). Spring AI performs the Java method, captures the result (e.g., "晴，25℃"), and feeds it back so the model can generate the final response.

用户提问
   │
   ▼
模型判断需要工具 ──► 返回「调用 getWeather(北京)」
                               │
                               ▼
                     Spring AI 执行 Java 方法
                               │ 返回「晴，25℃」
                               ▼
                     结果回填给模型 ──► 模型生成最终答案

Note: The model must support function calling. DeepSeek's deepseek-chat model supports this, allowing the series to work out‑of‑the‑box.

Key takeaways

Tool Calling enables models to obtain real‑time data and perform actions by invoking Java methods. @Tool marks a method as callable; the description guides the model. @ToolParam describes each parameter so the model can extract arguments from user input.

Use .tools(object) to register tool instances with ChatClient.

The model only issues a request; Spring AI executes the method and returns the result.