|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
Tool Specification Reference
Tool Specification Reference
Defining Tools covers the common ways to define and use tools. This reference covers the underlying interfaces and customization points.
ToolCallback
The ToolCallback interface models a tool: it carries the definition the model sees and the execution logic invoked when the model calls it.
public interface ToolCallback {
/** Definition used by the AI model to decide when and how to call the tool. */
ToolDefinition getToolDefinition();
/** Metadata controlling how the tool is handled (e.g. return-direct). */
ToolMetadata getToolMetadata();
/** Execute with the given JSON input and return the result. */
String call(String toolInput);
/** Execute with the given input and tool context. */
String call(String toolInput, ToolContext toolContext);
}
Spring AI provides MethodToolCallback and FunctionToolCallback as built-in implementations.
Implement ToolCallback directly when you need full control — for example, to proxy a remote tool source (as MCP integration does).
ToolDefinition
ToolDefinition is the contract the model sees: name, description, and input schema.
public interface ToolDefinition {
/** Unique tool name within the tool set provided to the model. */
String name();
/** Description used by the model to decide when to call the tool. */
String description();
/** JSON schema of the tool's input parameters. */
String inputSchema();
}
Build one with ToolDefinition.builder():
ToolDefinition toolDefinition = ToolDefinition.builder()
.name("currentWeather")
.description("Get the weather in location")
.inputSchema("""
{
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["C", "F"] }
},
"required": ["location", "unit"]
}
""")
.build();
For method-based tools, ToolDefinitions.from(method) generates a definition automatically.
The name and description of the method’s @Tool annotation override the defaults, which are the method name.
JSON Schema
The input schema tells the model how to call the tool.
Spring AI’s JsonSchemaGenerator produces the schema from a method or function’s parameter list and supports several customization annotations.
Parameter descriptions
Use any of these (Spring AI’s annotation has highest precedence):
-
@ToolParam(description = "…")— Spring AI -
@JsonPropertyDescription("…")— Jackson -
@Schema(description = "…")— Swagger
class CustomerTools {
@Tool(description = "Update customer information")
void updateCustomerInfo(
Long id,
String name,
@ToolParam(description = "Email address, RFC 5322 format", required = false) String email) {
// ...
}
}
Required vs optional
By default every parameter is required. Make a parameter optional via (in order of precedence):
-
@ToolParam(required = false)— Spring AI -
@JsonProperty(required = false)— Jackson; note that a@JsonPropertywithoutrequiredalso makes the parameter optional, because Jackson’s default isfalse -
@Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)— Swagger; the default mode,AUTO, counts as required -
@Nullable— Spring Framework / JSpecify
| Defining the correct required status is critical for reducing hallucinations. A parameter marked required forces the model to provide a value; an optional one lets it omit. If you mark a parameter required but the model has no way to determine its value, it will make one up. |
Tool Context
ToolContext lets you pass non-model data (tenant IDs, user IDs, request scope) to tool methods.
The data is not sent to the model — it’s purely for the tool’s internal use.
The chat request carries the tool definitions plus the tool context, and Spring AI sends only the tool definitions to the model (1). The model decides to call a tool and returns the tool call requests to Spring AI (2), which dispatches them to the matching tool (3). The tool context is handed directly to the tool at invocation time (3"), so it reaches the tool without ever passing through the model. The tool returns its result to Spring AI (4), which sends that result back to the model (5), and the model’s final answer is returned as the chat response (6).
In the example below, the Map.of("tenantId", "acme") passed to .toolContext() is the tool context from step (1), and getCustomerInfo reads it through its ToolContext parameter at step (3") — the tenantId reaches the tool without ever being exposed to the model.
class CustomerTools {
@Tool(description = "Retrieve customer information")
Customer getCustomerInfo(Long id, ToolContext toolContext) {
return customerRepository.findById(id, toolContext.getContext().get("tenantId"));
}
}
String response = ChatClient.create(chatModel)
.prompt("Tell me more about the customer with ID 42")
.tools(new CustomerTools())
.toolContext(Map.of("tenantId", "acme"))
.call()
.content();
If toolContext is set both as a default and at the call site, the two maps are merged; runtime values take precedence over defaults.
Return Direct
By default, the result of a tool call is sent back to the model so it can continue the conversation.
With returnDirect = true, the result bypasses the model and is returned directly to the caller — useful when the tool’s output is the final answer (e.g. a RAG retrieval) and the extra round-trip would add latency without value.
For declarative tools:
@Tool(description = "Retrieve customer information", returnDirect = true)
Customer getCustomerInfo(Long id) { ... }
For programmatic tools, set returnDirect via ToolMetadata:
ToolMetadata toolMetadata = ToolMetadata.builder()
.returnDirect(true)
.build();
If the model requests multiple tool calls in a single round, returnDirect is only honored if all the called tools have returnDirect = true.
Otherwise the results are sent back to the model.
|
Result Conversion
Tool results are converted to a String (the format the model expects) by a ToolCallResultConverter:
@FunctionalInterface
public interface ToolCallResultConverter {
String convert(Object result, Type returnType);
}
The default DefaultToolCallResultConverter uses Jackson to serialize the result.
Configure a custom converter on the @Tool annotation (resultConverter), or with toolCallResultConverter(…) on the MethodToolCallback and FunctionToolCallback builders.
The default converter returns "Done" for a void method, and a JSON object with the Base64-encoded PNG for a RenderedImage.
Method Tool Limitations
MethodToolCallbackProvider ignores a @Tool method that returns a functional type (Function, Supplier, Consumer), and logs a warning.
Spring AI does not unwrap Optional, asynchronous types (CompletableFuture, Future) or reactive types (Flow, Mono, Flux), so avoid them as parameter and return types:
use @Nullable or @ToolParam(required = false) instead of Optional, and return the value itself instead of a future or a publisher.
Exception Handling
When a tool throws, the exception is wrapped in ToolExecutionException and handed to the ToolExecutionExceptionProcessor:
@FunctionalInterface
public interface ToolExecutionExceptionProcessor {
String process(ToolExecutionException exception);
}
The processor has two choices: produce an error message that the framework feeds back to the model (so the model can recover or apologize), or re-throw the exception so the caller handles it.
The default DefaultToolExecutionExceptionProcessor:
-
Sends the message of any
RuntimeExceptionback to the model. -
Always re-throws checked exceptions and `Error`s.
Configure via property:
Property |
Description |
Default |
|
If |
|
Or by replacing the bean:
@Bean
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
return new DefaultToolExecutionExceptionProcessor(true);
}
If you implement your own ToolCallback, throw ToolExecutionException from call() when execution fails — that’s what the processor expects.
|
Tool Call Limits
DefaultToolCallingManager caps how many times a tool can be called within a turn, to guard against runaway loops:
ToolCallingManager toolCallingManager = ToolCallingManager.builder()
.maxCallsPerTool(40) // per-tool default
.maxCallsPerTool("search", 10) // override for one tool
.excludeToolFromLimit("getCurrentWeather") // no per-tool limit; still counts toward the total
.maxTotalToolCalls(150) // cap across all tools combined
.onLimitExceeded(ToolCallLimitBehavior.THROW) // or RETURN_ERROR_RESPONSE
.build();
These defaults (DefaultToolCallingManager.DEFAULT_MAX_CALLS_PER_TOOL / DEFAULT_MAX_TOTAL_TOOL_CALLS) apply even without calling these methods.
Use unlimitedCallsPerTool() / unlimitedTotalToolCalls() to disable a cap entirely.
Counting
Counts are scoped to the current turn only: only ToolResponseMessage entries from the last UserMessage onward are tallied, so history replayed by a ChatMemory advisor outside the loop never inflates the count for a new turn.
Nothing is cached on the manager itself — counts are recomputed from prompt.getInstructions() on every call, so a single ToolCallingManager instance stays safe to share across concurrent requests.
This also means disabling `ToolCallingAdvisor’s internal conversation history (see Inside the Loop) has no effect on limit counting — it always sees the complete turn history regardless of what’s trimmed for the rest of the chain.
Behavior When a Limit Is Exceeded
DefaultToolCallingManager throws ToolCallLimitExceededException, carrying the tool name (null for a total-limit breach), the limit that was hit, and the partial ToolExecutionResult already executed in the current batch, so no completed work is discarded.
ToolCallingAdvisor catches it and returns the breach as the final response - a single Generation (via ex.buildGeneration()), never one generation per tool call, so a successful call earlier in a parallel batch can’t hide the breach from callers reading only the first result.
Its finish reason is ToolCallLimitExceededException.FINISH_REASON, and any tool calls that did succeed earlier in the batch are preserved under the METADATA_PARTIAL_TOOL_RESPONSES metadata key instead of being discarded.
With onLimitExceeded(ToolCallLimitBehavior.RETURN_ERROR_RESPONSE), the manager instead skips the call and synthesizes an error ToolResponse — the same mechanism used for ToolExecutionException — so the model is told the limit was reached and the conversation continues instead of terminating.
This is also the option to reach for if you call ToolCallingManager.executeToolCalls(…) directly instead of going through ToolCallingAdvisor.
Configure via properties:
Property |
Description |
Default |
|
Max calls to one tool per turn. |
|
|
Per-tool override; |
— |
|
Tool names exempt from the per-tool limit. |
— |
|
Max tool calls across all tools per turn. |
|
|
|
|
Tool Resolution
Most of the time, tools are passed explicitly via .tools(…) and .defaultTools(…).
For more dynamic scenarios — name-based resolution at runtime — Spring AI uses ToolCallbackResolver:
public interface ToolCallbackResolver {
@Nullable
ToolCallback resolve(String toolName);
}
By default, a DelegatingToolCallbackResolver around a StaticToolCallbackResolver is auto-configured with all ToolCallback beans in the application context, plus tools produced by ToolCallbackProvider beans (with the exception of MCP providers, which are excluded to avoid eager listing — see Consuming MCP Server Tools).
Replace the resolver with a custom bean if you need a different strategy (database-backed, classpath-scanned, remote):
@Bean
ToolCallbackResolver toolCallbackResolver(List<ToolCallback> toolCallbacks) {
return new StaticToolCallbackResolver(toolCallbacks);
}
ToolCallingManager executes the tools that are attached to the request.
It asks the resolver only for a tool that the model calls but that is not attached to the request, and only when the resolution fallback is enabled.
To enable the behavior — where a tool known to the resolver, but not attached to the request may be resolved by name and executed — enable the resolution fallback:
spring.ai.tools.resolution.fallback.enabled=true
Property |
Description |
Default |
|
If |
|
When constructing a ToolCallingManager directly, the same switch is available on the builder via .resolutionFallbackEnabled(true) (default false).
| Enabling the resolution fallback makes every tool reachable through the resolver executable whenever the model names it, regardless of what a request attached — including risk-tier and destructive tools. Enable it only when you fully control which tools the resolver exposes. |
Observability
Spring AI emits Micrometer observations for tool calls under the spring.ai.tool name.
Each observation captures:
-
Tool name and definition metadata.
-
Execution duration.
-
Tracing context (when a
Traceris available).
See Tool Calling Observability for the full attribute reference.
Tool call arguments and results can optionally be exported as span attributes; this is disabled by default for sensitivity reasons. See Tool Call Arguments and Result Data to enable it.
Behavior to Know
-
Unknown tool. When the model calls a tool that is not attached to the request, and the resolution fallback does not find it,
ToolCallingManagerthrows anIllegalStateException("No ToolCallback found for tool name") instead of reporting an error to the model. -
Missing tool context. A
@Toolmethod that declares aToolContextparameter fails with anIllegalArgumentExceptionwhen the request has no tool context, or an empty one. The parameter does not appear in the schema that the model sees. -
Duplicate tool names. Two tools with the same name in one request fail with an
IllegalStateExceptionwhen the tools are passed throughChatClient. ThroughChatModelwith your ownToolCallingChatOptions, the first tool with the name wins, without an error, see MCP Tools. -
Tools set in two places. Tools passed to
ChatClientwith.tools(…)replace the tool callbacks set through.options(…). -
Custom exception processor. The auto-configured
ToolExecutionExceptionProcessorrethrows Spring Security’sClientAuthorizationException, so that OAuth2 flows can react to it; a processor of your own must do the same if you need that.
Related properties:
| Property | Description | Default |
|---|---|---|
|
The order of the auto-registered |
|
|
Whether tool observations include the tool arguments and results. |
|