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 @JsonProperty without required also makes the parameter optional, because Jackson’s default is false

  • @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.

Tool Context

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.

Returning tool call results directly to the caller

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 RuntimeException back to the model.

  • Always re-throws checked exceptions and `Error`s.

Configure via property:

Property

Description

Default

spring.ai.tools.throw-exception-on-error

If true, all tool errors are thrown for the caller to handle. If false, errors are sent back to the model as messages.

false

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

spring.ai.tools.limits.max-calls-per-tool-default

Max calls to one tool per turn. -1 disables.

40

spring.ai.tools.limits.max-calls-per-tool.<name>

Per-tool override; -1 exempts that tool.

—

spring.ai.tools.limits.excluded-tools

Tool names exempt from the per-tool limit.

—

spring.ai.tools.limits.max-total-tool-calls

Max tool calls across all tools per turn. -1 disables.

150

spring.ai.tools.limits.on-limit-exceeded

THROW or RETURN_ERROR_RESPONSE.

THROW

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

spring.ai.tools.resolution.fallback.enabled

If true, a requested tool that is absent from the request’s tool callbacks may be resolved by name through the ToolCallbackResolver and executed. If false, only the tools attached to the request can be executed.

false

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 Tracer is 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.

Logging

All main operations log at DEBUG. Enable with:

logging.level.org.springframework.ai=DEBUG

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, ToolCallingManager throws an IllegalStateException ("No ToolCallback found for tool name") instead of reporting an error to the model.

  • Missing tool context. A @Tool method that declares a ToolContext parameter fails with an IllegalArgumentException when 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 IllegalStateException when the tools are passed through ChatClient. Through ChatModel with your own ToolCallingChatOptions, the first tool with the name wins, without an error, see MCP Tools.

  • Tools set in two places. Tools passed to ChatClient with .tools(…​) replace the tool callbacks set through .options(…​).

  • Custom exception processor. The auto-configured ToolExecutionExceptionProcessor rethrows Spring Security’s ClientAuthorizationException, 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

spring.ai.chat.client.tool-calling.advisor-order

The order of the auto-registered ToolCallingAdvisor.

HIGHEST_PRECEDENCE + 300

spring.ai.tools.observations.include-content

Whether tool observations include the tool arguments and results.

false