skip to content

What is tool (function) calling in Spring AI, and why would you use it?

level: juniorimportance: must knowfreq 55%

answer

  1. Model requests, Spring executes
  2. @Tool + description guides the model
  3. ToolCallingManager runs the loop
  4. .tools() on ChatClient
  5. live data / actions, not text transforms

basics

~20 s

Tool 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 s

Large 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 lines
java
class 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

for a junior

Know the one-sentence purpose (let the model call your code for live data/actions) and that @Tool + .tools() wires it up.

for a middle

Explain the request/execute/feed-back loop and that the model chooses arguments while Spring executes.

for a senior

Discuss why descriptions drive model behavior and cost/validation implications of tool results re-entering the prompt.

for a principal

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

context

resolving links…