What is tool (function) calling in Spring AI, and why would you use it?
answer
- Model requests, Spring executes
- @Tool + description guides the model
- ToolCallingManager runs the loop
- .tools() on ChatClient
- live data / actions, not text transforms
basics
~20 sTool calling lets the LLM ask your app to run a Java method (e.g. fetch weather, query a DB) and use the result in its answer. In Spring AI you annotate a method with @Tool and register it with the ChatClient.
solid answer
~40 sLarge language models only know their training data and can't perform live actions. Tool calling closes that gap: you expose Java methods the model may invoke to fetch fresh data or trigger side effects. In Spring AI you annotate methods with @Tool (describing what it does), register them on a ChatClient via .tools(...) or defaultTools(...), and Spring advertises their JSON schemas to the model. When the model decides a tool is needed, it returns a structured tool-call request; Spring's ToolCallingManager intercepts it, invokes your method, feeds the result back, and the model loops until it produces a final answer. Typical uses: retrieving real-time information (weather, prices), reading your own data, or taking actions (send email, create ticket). The model never runs your code directly — it only requests a call; Spring executes it.
code
java · 13 linesclass WeatherTools {
@Tool(description = "Get the current weather for a given city")
String currentWeather(@ToolParam(description = "City name, e.g. Paris") String city) {
return "18C, light rain in " + city; // real impl calls a weather API
}
}
String answer = ChatClient.create(chatModel)
.prompt("Do I need an umbrella in Paris today?")
.tools(new WeatherTools())
.call()
.content();go deeper
Know the one-sentence purpose (let the model call your code for live data/actions) and that @Tool + .tools() wires it up.
Explain the request/execute/feed-back loop and that the model chooses arguments while Spring executes.
Discuss why descriptions drive model behavior and cost/validation implications of tool results re-entering the prompt.
Frame tool calling as controlled delegation with a security/validation boundary at the execution point.
## The problem tool calling solves An LLM is a text predictor frozen at its training cutoff. It cannot look up today's weather, read your database, or send an email. **Tool calling** (historically called *function calling*) is the mechanism that lets the model delegate such work to code you control. ## The interaction loop 1. You register one or more tools with the model. Each tool has a **name**, a **description**, and an **input schema** (what arguments it takes). Spring AI derives all of this from your annotated Java method and sends it to the model as JSON. 2. On a user prompt, the model may decide it needs a tool. Instead of answering, it returns a **tool-call request**: the tool name plus JSON arguments it chose. 3. Spring AI's **ToolCallingManager** intercepts that request, deserializes the arguments, invokes your Java method, and captures the return value. 4. The return value is serialized (to JSON) and appended to the conversation as a *tool response* message. 5. The model is called again with that result and continues — possibly calling more tools — until it emits a final natural-language answer. Crucially, **the model never executes your code**; it only emits a request. Spring does the actual invocation, so you keep full control over what runs. ## Defining a tool in Spring AI The simplest form uses `@org.springframework.ai.tool.annotation.Tool` on a method, with optional `@ToolParam` to describe parameters: ```java class WeatherTools { @Tool(description = "Get the current weather for a city") String currentWeather(@ToolParam(description = "City name") String city) { return weatherService.lookup(city); // your real logic } } ``` Register it per request: ```java String answer = ChatClient.create(chatModel) .prompt("What should I wear in Paris today?") .tools(new WeatherTools()) .call() .content(); ``` The **description** matters: it is the model's only clue about *when* to call the tool, so write it clearly. Vague descriptions cause the model to skip or misuse the tool. ## Key terms - **ChatClient** — the fluent façade for talking to a chat model. - **@Tool** — marks a method as callable by the model; its `description` guides the model. - **@ToolParam** — documents a parameter (description, whether it's required). - **ToolCallingManager** — Spring's internal component that executes requested tools and manages the loop. ## When to use it Use tool calling when the model needs **live data** (APIs, DB), must **act** on the outside world, or should return **structured, verified** facts rather than hallucinated ones. Do not use it for pure text transformation the model can already do. ## Gotchas - If no registered tool fits, the model just answers from its own knowledge — it won't error. - The model chooses arguments; validate them, they may be malformed or out of range. - Tool results re-enter the prompt and consume tokens; large results inflate cost.
- Does the model run your Java code directly?No. The model only emits a structured tool-call request (name + JSON args). Spring AI's ToolCallingManager deserializes it, invokes the method on your behalf, and returns the result — so execution stays under your control.
- What happens if none of the registered tools is relevant to the prompt?Nothing special — the model simply answers from its own knowledge without calling a tool. Registering a tool makes it available, it doesn't force its use.
saying these in an interview costs you the question
- Saying the LLM executes the Java method itself
- Thinking @Tool forces the model to always call the tool
- Believing the description is optional / decorative — it's what the model uses to decide when to call