![](https://github.com/spring-io/spring-io-static/blob/main/blog/tzolov/20251124/spring-ai-tool-response-formats.png?raw=true) JSON is the go-to format for LLM tool responses, but recent discussions around alternative formats like TOON (Token-Oriented Object Notation) claim potential benefits in token efficiency and performance. While the debate continues—with critical analyses pointing to context-dependent results—the question is: how to experiment with these formats in your own Spring AI applications? This article demonstrates **how** to configure Spring AI to convert tool responses between `JSON`, `TOON`, `XML`, `CSV`, and `YAML`, enabling you to decide what works best for your specific use case. ## Spring AI Tool Calling: A Quick Overview Let's briefly review how Spring AI Tool Calling works: ![](https://docs.spring.io/spring-ai/reference/_images/tools/tool-calling-01.jpg) 1. Tool definitions (name, description, parameters schema) are added to the chat request. 2. When the model decides to call a tool, it sends the tool name and input parameters. 3. Spring AI identifies and executes the tool with the provided parameters. 4. Spring AI handles the tool result. 5. Spring AI sends the tool result back to the model as part of the conversation history. 6. The model generates the final response using the tool result as additional context. The ToolCallback interface is at the heart of this process. Each tool is wrapped in a `ToolCallback` that handles the serialization and execution logic. We can intercept and convert the response format at two key points: * **Tool Result level** : After the tool executes but before JSON serialization (Approach 1) * **Response level** : After JSON serialization, transforming JSON to another format (Approach 2) Both approaches have their merits, and the choice depends on your specific requirements. Let's explore each in detail. ## Approach 1: Custom ToolCallResultConverter Configuration > **Important** : Applicable only for local tool implementations such as `@Tool`, `FunctionToolCallback` and `MethodToolCallback`. Currently it is not supported by the MCP Tools. The ToolCallResultConverter interface provides fine-grained control over individual tool formats. The DefaultToolCallResultConverter serializes the result to JSON, but you can customize the serialization process by providing your own ToolCallResultConverter implementation. For example, a custom ToonToolCallResultConverter can look like this: public static class ToonToolCallResultConverter implements ToolCallResultConverter { private ToolCallResultConverter delegate = new DefaultToolCallResultConverter(); @Override public String convert(@Nullable Object result, @Nullable Type returnType) { // First convert to JSON using the default converter String json = this.delegate.convert(result, returnType); // Then convert JSON to TOON return JToon.encodeJson(json); } } It uses the default JSON converter, then converts to TOON using libraries such as JToon or toon4j. **Register with @Tool:** @Tool(description = "Get random titanic passengers", resultConverter = ToonToolCallResultConverter.class) // (1) public List randomTitanicToon( @ToolParam(description = "Number of records to return") int count) { return TitanicData.getRandomTitanicPassengers(count); } Uses the `resultConverter` attribute to set the custom ToonToolCallResultConverter. **Execution flow:** Tool executes → Default converter creates JSON → TOON converter transforms JSON → LLM receives TOON response. You can also register the ToolCallResultConverter with the FunctionToolCallback and MethodToolCallback builders programmatically. **Limitations:** * ❌ **MCP incompatible** : Doesn't work with `@McpTool` (Model Context Protocol tools) * ❌ **Repetitive** : Must implement and register for each tool needing conversion * ❌ **Maintenance overhead** : Changes require updating multiple tool definitions The Application2.java provides an implementation example. ## Approach 2: Global Tool Response Configuration Apply format conversion globally using a custom `ToolCallbackProvider` that wraps existing providers with delegator pattern: Original ToolCallbackProvider ↓ wrapped by DelegatorToolCallbackProvider ↓ creates wrapped callbacks DelegatorToolCallback (for each tool) ↓ intercepts call() method ↓ converts response JSON → Target Format (TOON/XML/CSV/YAML) #### Component 1: DelegatorToolCallbackProvider public class DelegatorToolCallbackProvider implements ToolCallbackProvider { private final ToolCallbackProvider delegate; private final ResponseConverter.Format format; public DelegatorToolCallbackProvider(ToolCallbackProvider delegate, ResponseConverter.Format format) { this.delegate = delegate; this.format = format; } @Override public ToolCallback[] getToolCallbacks() { return Stream.of(this.delegate.getToolCallbacks()) .map(callback -> new DelegatorToolCallback(callback, this.format)) .toArray(ToolCallback[]::new); } } This provider wraps an existing `ToolCallbackProvider` and creates a `DelegatorToolCallback` wrapper for each tool callback. The format parameter specifies which format to convert to. #### Component 2: DelegatorToolCallback public static class DelegatorToolCallback implements ToolCallback { private final ToolCallback delegate; private final ResponseConverter.Format format; public DelegatorToolCallback(ToolCallback delegate, ResponseConverter.Format format) { this.delegate = delegate; this.format = format; } @Override public ToolDefinition getToolDefinition() { return this.delegate.getToolDefinition(); } @Override public String call(String toolInput) { // Call the original tool to get JSON response String jsonResponse = this.delegate.call(toolInput); // Convert to target format return ResponseConverter.convert(jsonResponse, this.format); } } The callback wrapper intercepts the `call()` method, allowing the original tool to execute normally, then converts its JSON response to the desired format. #### Component 3: ResponseConverter Utility public class ResponseConverter { public enum Format { TOON, YAML, XML, CSV, JSON } public static String convert(String json, Format format) { switch (format) { case TOON: return jsonToToon(json); case YAML: return jsonToYaml(toJsonNode(json)); case XML: return jsonToXml(toJsonNode(json)); case CSV: return jsonToCsv(toJsonNode(json)); case JSON: return json; } throw new IllegalStateException("Unsupported format: " + format); } private static String jsonToToon(String jsonString) {...} private static String jsonToYaml(JsonNode jsonNode) {...} private static String jsonToXml(JsonNode jsonNode) {...} private static String jsonToCsv(JsonNode jsonNode) {...} } The ResponseConverter provides conversion methods for each supported format, handling the specific requirements of each (like wrapping arrays for XML or building dynamic schemas for CSV). **Usage example:** @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } @Bean CommandLineRunner commandLineRunner(ChatClient.Builder chatClientBuilder, ToolCallbackProvider toolCallbackProvider) { // Wrap the provider with format conversion var provider = new DelegatorToolCallbackProvider( toolCallbackProvider, ResponseConverter.Format.TOON ); // Configure ChatClient with the wrapped provider var chatClient = chatClientBuilder .defaultToolCallbacks(provider) .build(); return args -> { var response = chatClient .prompt("Please show me 10 Titanic passengers?") .call() .chatResponse(); System.out.println(String.format(""" RESPONSE: %s USAGE: %s """, response.getResult().getOutput().getText(), response.getMetadata().getUsage())); }; } @Bean MethodToolCallbackProvider methodToolCallbackProvider() { return MethodToolCallbackProvider.builder() .toolObjects(new MyTools()) .build(); } static class MyTools { @Tool(description = "Get titanic passengers") public List randomTitanicToon( @ToolParam(description = "Number of records to return") int count) { return TitanicData.getTitanicPassengersInRange(30, count); } } } **Execution flow:** User prompt → LLM calls tool → Wrapper intercepts → Tool executes → JSON created → Format converter transforms → LLM receives converted response. The Application example leverages the ToolCallAdvisor (e.g. moving the tool execution as part of the Advisor chain) and a custom logging advisor `MyLogAdvisor` that helps to see the actual tool responses in different formats. This advisor will print out the tool responses, allowing you to see the target format output. ### Format Conversion Details Let's examine each supported format and see what the output looks like. #### JSON (default) [{"PassengerId":"31","Survived":"0","Pclass":"1","Name":"Uruchurtu, Don. Manuel E","Sex":"male","Age":40,"SibSp":"0","Parch":"0","Ticket":"PC 17601","Fare":27.7208,"Cabin":null,"Embarked":"C"}, {"PassengerId":"32","Survived":"1","Pclass":"1","Name":"Spencer, Mrs. William Augustus (Marie Eugenie)","Sex":"female","Age":null,"SibSp":"1","Parch":"0","Ticket":"PC 17569","Fare":146.5208,"Cabin":"B78","Embarked":"C"}, {"PassengerId":"33","Survived":"1","Pclass":"3","Name":"Glynn, Miss. Mary Agatha","Sex":"female","Age":null,"SibSp":"0","Parch":"0","Ticket":"335677","Fare":7.75,"Cabin":null,"Embarked":"Q"}, {"PassengerId":"34","Survived":"0","Pclass":"2","Name":"Wheadon, Mr. Edward H","Sex":"male","Age":66,"SibSp":"0","Parch":"0","Ticket":"C.A. 24579","Fare":10.5,"Cabin":null,"Embarked":"S"}, {"PassengerId":"35","Survived":"0","Pclass":"1","Name":"Meyer, Mr. Edgar Joseph","Sex":"male","Age":28,"SibSp":"1","Parch":"0","Ticket":"PC 17604","Fare":82.1708,"Cabin":null,"Embarked":"C"}] #### TOON [5]{PassengerId,Survived,Pclass,Name,Sex,Age,SibSp,Parch,Ticket,Fare,Cabin,Embarked}: "31","0","1","Uruchurtu, Don. Manuel E",male,40,"0","0",PC 17601,27.7208,null,C "32","1","1","Spencer, Mrs. William Augustus (Marie Eugenie)",female,null,"1","0",PC 17569,146.5208,B78,C "33","1","3","Glynn, Miss. Mary Agatha",female,null,"0","0","335677",7.75,null,Q "34","0","2","Wheadon, Mr. Edward H",male,66,"0","0",C.A. 24579,10.5,null,S "35","0","1","Meyer, Mr. Edgar Joseph",male,28,"1","0",PC 17604,82.1708,null,C #### XML 3101Uruchurtu, Don. Manuel Emale4000PC 1760127.7208C 3211Spencer, Mrs. William Augustus (Marie Eugenie)female10PC 17569146.5208B78C 3313Glynn, Miss. Mary Agathafemale003356777.75Q 3402Wheadon, Mr. Edward Hmale6600C.A. 2457910.5S 3501Meyer, Mr. Edgar Josephmale2810PC 1760482.1708C #### YAML --- - PassengerId: "31" Survived: "0" Pclass: "1" Name: "Uruchurtu, Don. Manuel E" Sex: "male" Age: 40 SibSp: "0" Parch: "0" Ticket: "PC 17601" Fare: 27.7208 Cabin: null Embarked: "C" ... - PassengerId: "35" Survived: "0" Pclass: "1" Name: "Meyer, Mr. Edgar Joseph" Sex: "male" Age: 28 SibSp: "1" Parch: "0" Ticket: "PC 17604" Fare: 82.1708 Cabin: null Embarked: "C" #### CSV PassengerId,Survived,Pclass,Name,Sex,Age,SibSp,Parch,Ticket,Fare,Cabin,Embarked 31,0,1,"Uruchurtu, Don. Manuel E",male,40,0,0,"PC 17601",27.7208,,C 32,1,1,"Spencer, Mrs. William Augustus (Marie Eugenie)",female,,1,0,"PC 17569",146.5208,B78,C 33,1,3,"Glynn, Miss. Mary Agatha",female,,0,0,335677,7.75,,Q 34,0,2,"Wheadon, Mr. Edward H",male,66,0,0,"C.A. 24579",10.5,,S 35,0,1,"Meyer, Mr. Edgar Joseph",male,28,1,0,"PC 17604",82.1708,,C #### Token Usage Here is the tokens usage estimates per each format Format | Prompt Tokens | Completion Tokens | Total Tokens ---|---|---|--- CSV | 293 | 522 | 815 TOON | 308 | 538 | 846 JSON | 447 | 545 | 992 YAML | 548 | 380 | 928 XML | 599 | 572 | 1171 ## Best Practices and Recommendations * Start with JSON—it's proven, safe, and universally understood * Measure performance in your specific context; don't assume alternatives are always better * Avoid converting complex nested structures to CSV or TOON * Include error handling in all converters * Provide JSON fallback when conversion fails * Log conversion metrics for monitoring ## Conclusion Spring AI offers flexibility for experimenting with tool response formats through two distinct approaches. Use `ToolCallResultConverter` for selective, per-tool conversion when you need fine-grained control. Choose the global `DelegatorToolCallbackProvider` approach for consistent format conversion across all tools, including MCP tools. Both support multiple formats—TOON, YAML, XML, CSV, and JSON—giving you the freedom to optimize for your specific use case. ### Try It Yourself > **Note** : The following code is for demonstration purposes only and should not be used in production without proper testing, error handling, and security considerations. The complete demo is available on GitHub. Run it with different formats: ./mvnw spring-boot:run -Dspring.ai.tool.response.format=TOON ./mvnw spring-boot:run -Dspring.ai.tool.response.format=CSV ./mvnw spring-boot:run -Dspring.ai.tool.response.format=YAML Experiment with the formats and measure their impact in your specific environment to determine what works best for your use case. * * * ## Resources * **Example Code** : spring-ai-tool-response-format-demo * **Spring AI Documentation** : https://docs.spring.io/spring-ai/reference/ * **TOON Format** : https://github.com/toon-format/toon * **Critical Analysis** : * https://www.improvingagents.com/blog/toon-benchmarks * https://www.towardsdeeplearning.com/toon-benchmarks-a-critical-analysis-of-different-results-d2a74563adca

Beyond JSON: Converting Spring AI Tool Response Formats to TOON, XML, CSV, YAML, ...