Chapter 6: Activating tool-driven generation
The introduction explains why an LLM may need tools to obtain real-time information that training and RAG cannot supply.
After this chapter you will be able to
- Need for real-time tools. Explain why an LLM may need tools even when it has been trained on extensive information and can use RAG.
- Tools versus RAG. Distinguish how tools and RAG supply information an LLM was not trained on, and explain what tools can do beyond supplying data.
- Time tool declaration. Describe how TimeTools exposes its time lookup method as a tool for the LLM.
- Tool-enabled client configuration. Explain how the controller makes TimeTools available when it sends a prompt and what changes in the response.
- Tool definitions and requests. Describe how the initial request makes a tool available to the model and how the model asks for it to be called with suitable input.
- Application-mediated tool conversation. Trace how Spring AI handles the model's tool-call request and returns the tool result so the model can give a final answer. Distinguish the tool_calls and stop finish reasons.
- Database-backed game complexity ratings. Explain how user-supplied game complexity ratings could help Board Game Buddy answer questions about a game’s difficulty.
- Relational data foundation. Describe how Spring Data JDBC and an H2 in-memory database provide storage for game complexity data, including the roles of schema.sql and data.sql.
- Slug lookup repository. Explain how GameRepository looks up a game by slug and why its interface does not need a hand-written implementation.
- Tool description and selection. Explain that GameTools exposes getGameComplexity() as a @Tool-annotated method and that the tool description helps the LLM decide whether to use it to answer a question.
- Game title input and result. Trace how getGameComplexity() takes a game title, uses GameRepository to find its complexity, and returns a GameComplexityResponse; describe what happens when the game is not found.
- Tool registration scope. Distinguish registering GameTools with ChatClient at build time from supplying it when creating a prompt, and explain when the @Tool-annotated methods are available in each case.
- Functional interface tools. Explain how a tool can be implemented with Java’s Function, Supplier, or Consumer interfaces instead of an annotated bean method, and describe what changes in the GameTools example.
- Function tool request types. Explain why the Function-based GameTools takes a GameComplexityRequest rather than a String, and what its description does.
- Bean name tool registration. Describe how to register the Function-based GameTools with ChatClient, both when creating the client and at prompt time.
What it builds on
- Understanding RAG (chapter 4) · Assumes familiarity with RAG as a way to provide information beyond an LLM’s training.
- Submitting prompts (chapter 1) · Submitting a prompt to an LLM
Section by section
Introduction
The introduction explains why an LLM may need tools to obtain real-time information that training and RAG cannot supply.
- Need for real-time tools: Explain why an LLM may need tools even when it has been trained on extensive information and can use RAG.
Why it matters: It clarifies when a tool is needed instead of relying on the model’s existing knowledge or retrieved documents.
Key terms: LLMs, RAG, tools, real-time information
6.1 Getting started with AI tools
Introduces tools as a way for supported LLMs to obtain data and take actions through application logic, with Spring AI providing a consistent way to apply them.
- Tools versus RAG: Distinguish how tools and RAG supply information an LLM was not trained on, and explain what tools can do beyond supplying data.
Why it matters: This distinction explains why tools can let an LLM do more than answer questions. - Spring AI tool consistency: Explain the limitation on model support for tools and what Spring AI makes consistent across supporting providers.
Why it matters: It clarifies both when tool calling is available and what Spring AI simplifies.
Key terms: RAG, tools, application logic, tool calling, AI providers, Spring AI
6.1.1 Developing a tools-enabled application
Builds a Spring AI application that answers current-time questions by making a Java time lookup available to an LLM as a tool.
- Real-time answer limitation: Explain why the initial controller cannot give a precise current time and why a tool helps.
Why it matters: The first response shows why the application needs a time lookup rather than another prompt alone. - Time tool declaration: Describe how TimeTools exposes its time lookup method as a tool for the LLM.
Why it matters: The annotation makes an application method identifiable as a tool the LLM can use. - Tool-enabled client configuration: Explain how the controller makes TimeTools available when it sends a prompt and what changes in the response.
Why it matters: Declaring a tool is not enough; the ChatClient must also be configured to offer it with the prompt.
Key terms: real-time information, tools, TimeTools, getCurrentTime(), @Tool, time zone, @Component, defaultTools(), ChatClient
6.1.2 Digging deeper
Explains how a tool-assisted answer is produced through a conversation between the application and the model, rather than by the model directly invoking an application endpoint.
- Tool definitions and requests: Describe how the initial request makes a tool available to the model and how the model asks for it to be called with suitable input.
Why it matters: This distinguishes giving the model a tool to request from giving it the ability to run application code directly. - Application-mediated tool conversation: Trace how Spring AI handles the model's tool-call request and returns the tool result so the model can give a final answer. Distinguish the tool_calls and stop finish reasons.
Why it matters: It explains why tool use takes another model request even though Spring AI handles the tool invocation for the application.
Key terms: tools property, description property, parameters property, JSON schema, getCurrentTime, Spring AI, finish_reason, tool_calls, tool role, stop
6.2 Implementing tools
Introduces database-backed game complexity ratings as information a tool could provide to Board Game Buddy’s LLM.
- Database-backed game complexity ratings: Explain how user-supplied game complexity ratings could help Board Game Buddy answer questions about a game’s difficulty.
Why it matters: It connects a question about game difficulty to data the application can supply to the LLM.
Key terms: Board Game Buddy, complexity ranking, tool
6.2.1 Writing the tool’s foundations
The section builds the database, Java data model, and repository that a later tool will use to answer questions about game complexity.
- Relational data foundation: Describe how Spring Data JDBC and an H2 in-memory database provide storage for game complexity data, including the roles of schema.sql and data.sql.
Why it matters: The tool needs game complexity data to read before it can answer questions about it. - Game data representation: Describe the fields stored for each game and how the Game record presents its numerical complexity as a GameComplexity enum.
Why it matters: The record gives Java code a way to hold a game’s stored data and express its complexity as an enum value. - Slug lookup repository: Explain how GameRepository looks up a game by slug and why its interface does not need a hand-written implementation.
Why it matters: The repository supplies database lookup without requiring you to implement the data-access interface yourself.
Key terms: Spring Data JDBC, H2 in-memory database, DataSource, schema.sql, data.sql, Game table, Game record, slug, complexity, complexityEnum()
6.2.2 Defining the tool
This subsection defines a game complexity tool and explains how its annotations, repository lookup, and response help an LLM use it.
- Tool description and selection: Explain that GameTools exposes getGameComplexity() as a @Tool-annotated method and that the tool description helps the LLM decide whether to use it to answer a question.
Why it matters: A useful tool description helps the LLM choose the tool for an appropriate question. - Game title input and result: Trace how getGameComplexity() takes a game title, uses GameRepository to find its complexity, and returns a GameComplexityResponse; describe what happens when the game is not found.
Why it matters: This connects the information the LLM must supply with the game data the tool returns.
Key terms: GameTools, getGameComplexity(), @Tool, description attribute, gameTitle, @ToolParam, GameRepository, GameComplexityResponse, GameComplexity, placeholder Game
6.2.3 Putting the tool to work
This section shows how to make a game-complexity tool available to ChatClient and verify that it was called.
- Tool registration scope: Distinguish registering GameTools with ChatClient at build time from supplying it when creating a prompt, and explain when the @Tool-annotated methods are available in each case.
Why it matters: The choice determines whether the tool is available by default or supplied for a particular prompt. - Tool invocation verification: Describe how the application can be tried with game-complexity questions and how its logs help verify that the tool supplied an answer.
Why it matters: A plausible answer alone does not show that the application used the tool.
Key terms: GameTools, ChatClient, defaultTools(), tools(), @Tool, logger’s info() method, logs, game complexity tool
6.3 Enables functions as tools
This section shows how to define a Spring AI tool with a Java functional interface and register it with ChatClient by bean name.
- Functional interface tools: Explain how a tool can be implemented with Java’s Function, Supplier, or Consumer interfaces instead of an annotated bean method, and describe what changes in the GameTools example.
Why it matters: This gives you another way to expose application behavior as a tool. - Function tool request types: Explain why the Function-based GameTools takes a GameComplexityRequest rather than a String, and what its description does.
Why it matters: The input-type requirement determines the signature of the Function-based tool. - Bean name tool registration: Describe how to register the Function-based GameTools with ChatClient, both when creating the client and at prompt time.
Why it matters: The correct registration method lets ChatClient use the Function-based tool.
Key terms: Function, Supplier, Consumer, apply(), @Description, @Component, GameComplexityRequest, Java record, @ToolParam, gameTools
6.4 Summary
Where this is used later
- Introducing Model Context Protocol (chapter 7) · Assumes familiarity with tools used during AI generation.
- (chapter intro) (chapter 10) · Introduces tools as a way to connect generation to application capabilities.
- Securing tools (chapter 10) · Tools let an LLM interact with external APIs and data.
- (chapter intro) (chapter 7) · Assumes the earlier approach of implementing tools within a Spring AI application.
- Creating the MCP Server tools (chapter 7) · Using @Tool to define a tool method.
- Working with MCP Clients (chapter 7) · Prior use of tools to help generate answers.
Concepts explained in this chapter
- toolA tool is a callable capability that allows an AI model or application to obtain data or perform an action through external functionality.
- @Tool annotationThe @Tool annotation marks a method as a callable tool that an AI application can expose to a language model.
- defaultTools()defaultTools() is a ChatClient builder method that registers tools available to prompts sent through the resulting client.
- tool usageA tool call is a model-generated request for an application to invoke an external callable capability.
- Spring AISpring AI is a Java library that provides abstractions and integrations for incorporating generative AI capabilities into Spring applications.
- assistantAn assistant message is a message containing a response generated by a language model.
- tool roleA tool message is a message containing instructions for invoking external tools to perform an action or fetch additional context.
- Spring Data JDBCSpring Data JDBC is a Spring Data module that provides repository-based relational database access using JDBC.
- ChatClientChatClient is a Spring AI API component for sending conversational requests to language models and receiving responses.
- language modelA large language model is a machine-learning model trained on extensive text data to understand and generate natural-language content.
- Spring AI OpenAI starterThe Spring AI OpenAI integration is the Spring AI module that connects applications to OpenAI models and services.
- Spring InitializrSpring Initializr is a service that generates customizable Spring Boot project structures and build configurations.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.