LLM Tool Call Reasoning Using Embabel Agentic AI Framework

1. Overview

Tool-call reasoning improves the observability of AI agents by capturing the rationale behind LLM tool selection rather than simply recording which tool the model invokes.

Insight into agentic tool selection decisions helps developers debug agentic workflows, validate decision quality, and identify opportunities for prompt or tool design improvements. This transparency becomes increasingly important as agents grow more autonomous and interact with larger sets of tools.

In this tutorial, we’ll look at how the Embabel Agentic AI framework can be used to obtain this level of observability in our Java applications.

2. Tool Call Reasoning Using Spring AI

Before diving into how to use Embabel, let’s first consider how the problem is solved in the Spring AI Tool Argument Augmenter.

The Tool Argument Augmenter dynamically augments tool schemas with additional reasoning fields, such as innerThought or confidence. The result is improved observability into agent behavior without changing existing tool implementations.

In Spring AI, tools are defined using a JSON Schema that specifies the expected arguments. The LLM evaluates these schemas and decides which tool to invoke and which arguments to pass. Spring AI’s augmentation layer exploits this mechanism by extending the schema’s properties with additional properties visible to the model (i.e., schema augmentation).

An essential implementation feature is that the real tool definition, applied at the time of tool invocation, remains unchanged. The augmentation layer intercepts the tool-call payload, extracts the reasoning fields, removes them, and invokes the actual tool with only the expected arguments. The tool itself remains unaware of the augmentation.

The user receives tool-call reasoning details via a separate DTO (with properties innerThought and confidence).

2.1. Spring AI Solution Design Analysis

The design is strong in several areas.

First, it provides structured and machine-readable observability. Because reasoning fields are part of the schema, they are easier to evaluate, store, or feed into analytics pipelines.

Second, it remains largely non-invasive. Existing tools, including MCP tools and local @Tool methods, continue to work without modification.

Third, the solution leverages existing LLM capabilities instead of inventing proprietary reasoning APIs. Any model that supports structured tool calling can, in principle, support this approach.

However, the design also introduces trade-offs; a key limitation is that the exposed schema is no longer the actual contract. The LLM-facing schema contains fields that the underlying tool never actually accepts. Architecturally, this means that an augmented tool schema is not the same as the runtime tool method contract.

The approach introduces additional complexity through:

• Augmented DTOs
• Schema merging
• Augmented fields extraction
• Tool-wrapping infrastructure

This increases both conceptual overhead and coupling with Spring AI’s internal JSON Schema tool model.

3. Tool Call Reasoning Using a System Prompt

A simpler alternative is to define a standardized system-level protocol via prompting. When invoking a tool, the prompt should request the LLM to:

• Explain briefly why the tool is needed
• State what information is expected
• Provide a confidence level

This shifts reasoning capture from a schema-level contract to a prompt-level protocol—from structural enforcement to semantic guidance. In practice, schema augmentation enforces a hard contract (“fields must exist”), while prompting establishes a soft convention (“behave this way”).

Both approaches rely on model-generated explanations and therefore share the same variability in content and phrasing. The practical difference lies in output structure: schema augmentation enforces the presence of explicit fields, making explanations easier to capture and parse, whereas a prompt-based approach leaves them in semi-structured format.

The main advantage of the prompt-based approach is portability. Schema augmentation depends on framework-specific mechanisms (e.g., tool schema generation, callback providers, argument interception), whereas a system prompt relies only on a universal capability: sending instructions to the model. This makes it portable across other agentic frameworks such as Spring AI, LangChain4j, Semantic Kernel, OpenAI, Anthropic, and Google DeepMind.

Compared to the Spring AI augmentation approach, the prompt-based solution keeps the implementation simpler by avoiding synthetic schemas, augmentation DTOs, schema transformation, and custom tool-wrapping infrastructure.

Neither approach is universally superior—they embody different engineering trade-offs. In practice, a hybrid model often works best: use prompt-level protocols for general guidance and apply schema-level augmentation selectively where stronger guarantees are needed.

4. Tool Call Reasoning with Embabel

Embabel is an Agentic AI framework founded by Rod Johnson, creator of the Spring Framework. For introductory information about Embabel, please refer to the Baeldung article “Using the Embabel Agent Framework”. You can find the official Embabel documentation here, and more resources on Medium.

4.1. Quick Introduction to Embabel Modes

Embabel is a comprehensive framework for developing Agentic AI applications on the JVM. A key feature of Embabel is the employment of a fluent API with structured outputs in all modes – an important feature in the Agentic AI landscape for the JVM:

• Basic mode (without “thinking” or streaming)
• Thinking mode (details to follow)
• Streaming mode

We’ll explore the “thinking” mode, which serves as the foundation for the Tool Call Reasoning solution.

4.2. Embabel Agentic AI Dependencies

First, let’s define the major Embabel dependencies required for testing:

<!-- Embabel Agent Starter -->
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-openai</artifactId>
    <version>${embabel-agent.version}</version>
</dependency>

<!-- Embabel Agent Test Support -->
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-test-internal</artifactId>
    <version>${embabel-agent.version}</version>
    <scope>test</scope>
</dependency>

The embabel-agent-starter-openai dependency provides us with the core classes required to use OpenAI models with Embabel.

We also include embabel-agent-test-internal to allow us to use the AgentTestApplication test support class with our @SpringBootTest.

4.3. Thinking Mode Fluent API Concepts

Let’s introduce key concepts of the Embabel “thinking” mode fluent API:

ThinkingResponse<ParkingRecommendation> result = ai.withDefaultLlm()
  .withToolObject(tools)
  .withToolLoopInspectors(callbackTracker, loggingInspector)
  .withToolLoopTransformers(systemMessageTransformer)
  .thinking()
  .createObject(prompt, ParkingRecommendation.class);

Ai is a gateway to LLM connectivity; we can define the default Ai LLM in the configuration file or supply it explicitly.

ThinkingResponse is a wrapper object that includes a reference to the underlying business object, ParkingRecommendation, and so-called ThinkingBlocks with LLM reasoning.

withToolObject() is a reference to the ParkingTooling tool object (with details later in the article).

withToolInspectors() refers to optional callbacks, helpful for additional logging, metrics collection, etc. CallbackTracker collects statistics (counter of LLM calls, counter of tool calls, list of invoked tools), while ToolLoopLoggingInspector logs LLM and tool invocation details (for example: ToolLoopLoggingInspector – afterLlmCall: iteration=1, toolCalls=2, contentLength=1063, usage=prompt=834, completion=260)

withToolLoopTransformers()  demonstrates user-controlled conversation history management via ToolLoopTransformer. In this example, the transformer is configured with two system messages and always positions them at the top of the conversation history before LLM calls.

thinking() indicates a fluent API subtype as “thinking mode” and outputs ThinkingResponse, which wraps the business object, constructed by the API createObject().

Finally, the prompt variable contains our user message.

Thinking mode includes a few more APIs, including a very useful one, createObjectIfPossible(). In the scenario, if the LLM is not capable of creating the object, ThinkingResponse will still carry reasoning behind this fact.

4.4. Use Case

Our use case is an optimal parking solution finder subject to time and cost constraints. There would be three tools at our disposal:

• Free street parking locator
• Metered parking locator
• Garage reservation

The final thinking block explains the reasoning behind the recommendation, based on information gathered through probing multiple tools.

We will split the prompt into a generic, domain-neutral system message that can be used across a variety of business scenarios and a domain-specific user message.

Let’s specify the system message:

"""
CRITICAL WORKFLOW - Two-phase decision process:

=== PHASE 1: Tool Selection (First Response) ===

1. For EACH tool you plan to call, emit a SEPARATE <tool_use_reasoning> block:

    <tool_use_reasoning>
    Tool: [TOOL_NAME]
    Why THIS tool: [explain why this specific tool is needed]
    Information expected: [what this tool will reveal]
    Advantage over alternatives: [why this tool vs others]
    Confidence in this tool selection [confidence=0.XX]
    </tool_use_reasoning>

    Since you must call at least 2 tools, you must emit at least 2 separate blocks.

2. Call AT LEAST TWO tools to gather comprehensive information
    - You MUST call at least 2 tools to probe different aspects.
    - Tools are PROBES for information gathering, not final decisions.
    - Multiple probes provide better decision quality.

=== PHASE 2: Final Decision (After receiving tool results) ===

1. Emit final decision reasoning:
    <final_decision_reasoning>
    - What each tool probe revealed
    - How the probe results informed your analysis
    - Why you chose this option based on probe data and constraints
    Confidence: [confidence=0.XX]
    </final_decision_reasoning>

2. Then provide the final structured output
    - Your final recommendation should synthesize insights from multiple probes.
    - Never copy reasoning blocks into the final structured object.

REMINDER: One <tool_use_reasoning> block per tool call. At least 2 tools = at least 2 blocks.
Emit reasoning in BOTH phases.
"""

And let’s specify a user message:

"""
Scenario:
An advisor is driving to a client meeting in Midtown Manhattan.

Constraints:
- 30 minutes remain before the meeting starts
- arriving late is not acceptable
- the meeting is expected to last about 3 hours

Parking options:
- Street parking: free, but uncertain
- Metered parking: $5 per hour, typically limited to 2 hours
- Garage parking: $30 per hour, guaranteed availability

Important decision factors:
- available time before the meeting
- risk of arriving late
- trade-offs between street, metered, and garage parking

Recommend the best parking option.

Available tools: %s
"""

Next, we’ll supply the available tools.

4.5. Tool Definition

Let’s define the tool object:

static class ParkingTooling {

    @LlmTool(description = "Find free street parking. Uncertain and may take time.")
    public String findStreetParking(String location, int maxMinutes) {
        boolean found = ThreadLocalRandom.current().nextDouble() < 0.3; // low probability
        if (found) {
            return "Street parking found near " + location + " (free)";
        }
        return "No street parking found within " + maxMinutes + " minutes";
    }

    @LlmTool(description = "Find metered parking. Moderate cost and moderate availability. " +
        "May have time limits.")
    public String findMeterParking(String location, int maxMinutes) {
        boolean found = ThreadLocalRandom.current().nextDouble() < 0.6; // medium probability
        if (found) {
            return "Metered parking found near " + location + " ($5/hour, 2-hour limit)";
        }
        return "No metered parking found within " + maxMinutes + " minutes";
    }

    @LlmTool(description = "Reserve guaranteed garage parking near destination.")
    public String reserveGarage(String location) {
        return "Garage reserved near " + location + " ($30/hour, guaranteed)";
    }
}

Here, LlmTool is an Embabel tool annotation, which includes a tool description. Embabel allows us to expose tools to the LLM by implementing the Embabel Tool interface, or using annotated Java methods. Here, we see the latter approach.

4.6. Test Results Discussion

Our test ToolCallReasoningIntegrationTest invokes the LLM (which in turn invokes tools and summarizes tool selection recommendations) and logs results using custom logging functions.

We have a reportToolCallPattern() method that takes CallbackTracker as a parameter and logs tool pattern and statistics:

17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest - === TOOL CALL PATTERN ANALYSIS ===
Total LLM calls: 2
Unique tools: [findStreetParking, findMeterParking]
Total invocations: 2
Tool result callbacks: 2
Iterations with tool calls: 1
17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest - PATTERN: All 2 tools called in SAME iteration (parallel)
17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest - Thinking blocks captured: 3
17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest -   Block 1: tagType=TAG, tagValue=tool_use_reasoning, contentLength=481
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Tool: functions.findStreetParking
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Attributes: {confidence=0.85}
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -   Block 2: tagType=TAG, tagValue=tool_use_reasoning, contentLength=494
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Tool: functions.findMeterParking
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Attributes: {confidence=0.90}
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -   Block 3: tagType=TAG, tagValue=final_decision_reasoning, contentLength=755
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Attributes: {confidence=0.95}

Recommended: ParkingRecommendation[chosenOption=GARAGE, location=Midtown Manhattan, estimatedTotalCost=90, summary=Street parking is unavailable within 30 minutes and metered parking is limited to 2 hours, insufficient for a 3-hour meeting. Garage parking offers guaranteed availability and ensures timely arrival, making it the best option despite higher cost.]
Reasoning:
  ThinkingBlock(content=Tool: functions.findStreetParking
Why THIS tool: To check the availability and likelihood of finding free street parking near Midtown Manhattan within the 30-minute time constraint.
Information expected: Whether street parking is realistically available and how long it might take to find a spot.
Advantage over alternatives: Street parking is free and the cheapest option, but highly uncertain. Testing its feasibility is key before considering costlier options.
Confidence in this tool selection [confidence=0.9], tagType=TAG, tagValue=tool_use_reasoning)
  ThinkingBlock(content=Tool: functions.findMeterParking
Why THIS tool: To evaluate availability and feasibility of metered parking given the 2-hour limit and $5/hour cost within the 30-minute timeframe.
Information expected: Confirm if metered parking spots are available nearby and potential cost and time constraints.
Advantage over alternatives: Metered parking balances moderate cost and availability but with time limits, important to check if it fits the meeting duration.
Confidence in this tool selection [confidence=0.9], tagType=TAG, tagValue=tool_use_reasoning)
  ThinkingBlock(content=- The street parking probe revealed no available free street parking within the critical 30-minute arrival window, making this option too risky given the zero tolerance for lateness.
- Metered parking is available near the destination, but limited to 2 hours and costs $5/hour. This time limit is insufficient for the 3-hour meeting, so this option creates the risk of parking violation or disruption.
- Although not probed yet, garage parking guarantees availability and can cover the full 3-hour meeting, eliminating risk of lateness or parking issues at a higher cost ($30/hour).
- Given the importance of timely arrival and the meeting length, garage parking is the most reliable and suitable choice despite the cost premium.
Confidence: [confidence=0.95], tagType=TAG, tagValue=final_decision_reasoning)

Embabel returned a structured object of type ParkingRecommendation with all expected fields, including summary. 

Each ThinkingBlock includes an explanation of the tool selection, a tagType specifies the LLM reasoning format – in our case, this is XML TAG (could be PREFIX, or no tag), a tagValue=tool_use_reasoning, and a tagValue=final_decision_reasoning, which are the dynamic user-defined XML tags we specified in the system prompt. Please note two ThinkingBlocks, one for each tool call.

Finally, the ThinkingBlock with the recommendation was emitted, with placeholder confidence substituted, as expected.

The use of placeholders permits further automated processing for tool selection reasoning. The method extractAttributes() (please refer to the code linked to the article) scans a ThinkingBlock for attributes in [key=value] format and returns them as a Map of key-value pairs. For example, it converts text like [confidence=0.9] into an entry such as “confidence” -> 0.9.

Thus, Embabel’s thinking mode output is semi-structured.

5. Conclusion

In this article, we saw how Embabel provides a solution for tool selection reasoning by employing its “thinking” APIs.

While Spring AI provides out-of-the-box support for Tool Selection Reasoning, the solution has noticeable trade-offs. An alternative solution using Embabel is very simple and, unlike Spring AI, does not require hidden schema manipulations or the introduction of a custom DTO, and is fully built on the existing Embabel foundation APIs.

With Embabel, yet another solution using LLM Tool Loop callbacks is available, but it is outside the scope of this article.

The article code is available over on GitHub.

The author would like to thank Rod Johnson and Ajen Poutsma for their reviews and suggestions.