Fix tests, linter, and doc knit

Author: Ololoshechkin

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/AIAgentTool.kt

@@ -46,7 +46,6 @@ public inline fun <reified Input, reified Output> AIAgent<Input, Output>.asTool(
     json = json,
 )
 
-
 /**
  * AIAgentTool is a generic tool that wraps an AI agent to facilitate integration
  * with the context of a tool execution framework. It enables the serialization,

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/environment/GenericAgentEnvironment.kt

@@ -10,10 +10,8 @@ import ai.koog.agents.core.model.message.EnvironmentToolResultMultipleToAgentMes
 import ai.koog.agents.core.model.message.EnvironmentToolResultToAgentContent
 import ai.koog.agents.core.tools.DirectToolCallsEnabler
 import ai.koog.agents.core.tools.Tool
-import ai.koog.agents.core.tools.ToolArgs
 import ai.koog.agents.core.tools.ToolException
 import ai.koog.agents.core.tools.ToolRegistry
-import ai.koog.agents.core.tools.ToolResult
 import ai.koog.agents.core.tools.annotations.InternalAgentToolsApi
 import ai.koog.prompt.message.Message
 import io.github.oshai.kotlinlogging.KLogger

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/model/message/Environment.kt

@@ -1,6 +1,5 @@
 package ai.koog.agents.core.model.message
 
-
 /**
  * Represents the content of tool result messages sent to an agent after a tool call is executed within
  * the local environment. This provides the result of the tool execution alongside metadata such as

agents/agents-ext/src/commonMain/kotlin/ai/koog/agents/ext/tool/file/patch/TokenNormalizedPatchApplier.kt

@@ -1,5 +1,6 @@
 package ai.koog.agents.ext.tool.file.patch
 
+import kotlinx.serialization.Serializable
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.contract
 
@@ -29,21 +30,25 @@ internal fun applyTokenNormalizedPatch(content: String, patch: FilePatch): Patch
 /**
  * Represents the result of applying a patch to a file
  */
+@Serializable
 public sealed interface PatchApplyResult {
 
     /**
      * Represents a successful patch application
      */
+    @Serializable
     public data class Success(val updatedContent: String) : PatchApplyResult
 
     /**
      * Represents a failed patch application, including the reason for the failure
      */
+    @Serializable
     public sealed class Failure(public val reason: String) : PatchApplyResult {
 
         /**
          * Represents a failure to find the original text in the file content
          */
+        @Serializable
         public object OriginalNotFound : Failure(
             """
             The original text to replace was not found in the file content. 

agents/agents-tools/src/commonTest/kotlin/ai/koog/agents/core/tools/LLMDescriptionUsageTest.kt

@@ -30,7 +30,7 @@ class LLMDescriptionUsageTest {
         // All parameters use class-level description per current implementation
         val params = desc.requiredParameters + desc.optionalParameters
         assertEquals("a", params[0].description)
-        assertEquals("b", params[0].description)
+        assertEquals("b", params[1].description)
     }
 
     // 2) Property-level LLMDescription does NOT override parameter descriptions currently

docs/docs/class-based-tools.md

@@ -150,5 +150,82 @@ object CastToDoubleTool : SimpleTool<CastToDoubleTool.Args>() {
 ```
 <!--- KNIT example-class-based-tools-02.kt --> 
 
+### Sending Tool Result to LLM in Custom Format
+
+If you are not happy with JSON results sent to LLM (in some cases, LLMs can work better if tool output is structured as Markdown, for instance), you have to follow the following steps:
+1. Implement `ToolResult.TextSerializable` interface, and override `textForLLM()` method
+2. Override `resultSerializer` using `ToolResultUtils.toTextSerializer<T>()`
+
+#### Example
+
+<!--- INCLUDE
+import ai.koog.agents.core.tools.SimpleTool
+import ai.koog.agents.core.tools.ToolArgs
+import ai.koog.agents.core.tools.ToolDescriptor
+import ai.koog.agents.core.tools.ToolParameterDescriptor
+import ai.koog.agents.core.tools.ToolParameterType
+import kotlinx.serialization.Serializable
+import ai.koog.agents.core.tools.annotations.LLMDescription
+import ai.koog.prompt.markdown.markdown
+-->
+```kotlin
+// A tool that edits file
+object EditFile : Tool<EditFile.Args, EditFile.Result>() {
+    // Define tool arguments
+    @Serializable
+    public data class Args(
+        val path: String,
+        val original: String,
+        val replacement: String
+    )
+
+    @Serializable
+    public data class Result(
+        private val patchApplyResult: PatchApplyResult
+    ) : ToolResult.TextSerializable() {
+
+        @Serializable
+        public sealed interface PatchApplyResult {
+            @Serializable
+            public data class Success(val updatedContent: String) : PatchApplyResult
+            
+            @Serializable
+            public sealed class Failure(public val reason: String) : PatchApplyResult
+        }
+        
+        // Textual output (in Markdown format) that will be visible to the LLM after the tool finishes.
+        override fun textForLLM(): String = markdown {
+            if (patchApplyResult is PatchApplyResult.Success) {
+                line {
+                    bold("Successfully").text(" edited file (patch applied)")
+                }
+            } else {
+                line {
+                    text("File was ")
+                        .bold("not")
+                        .text(" modified (patch application failed: ${patchApplyResult.reason})")
+                }
+            }
+        }
+
+        override fun toString(): String = textForLLM()
+    }
+
+    // Serializer for the Args class
+    override val argsSerializer = Args.serializer()
+
+    // Description of the tool, visible to LLM
+    override val toolDescription = "Edits the given file"
+    
+    // Function that executes the tool with the provided arguments
+    override suspend fun execute(args: Args): Result {
+        return TODO("Implement file edit")
+    }
+}
+```
+<!--- KNIT example-class-based-tools-02.kt -->
+
+
+
 After implementing your tool, you need to add it to a tool registry and then use it with an agent.
 For details, see [Tool registry](tools-overview.md#tool-registry).

docs/docs/testing.md

@@ -133,7 +133,7 @@ public object AnalyzeTool : Tool<AnalyzeTool.Args, String>() {
     override val name = "message"
     override val toolDescription = "Service tool, used by the agent to talk with user"
 
-    override suspend fun execute(args: Args): String = args.message
+    override suspend fun execute(args: Args): String = args.query
 }
 
 typealias PositiveToneTool = SayToUser
@@ -430,10 +430,12 @@ object AnalyzeTool : Tool<AnalyzeTool.Args, String>() {
     @Serializable
     data class Args(
         @property:LLMDescription("Message from the agent")
-        val query: String
+        val query: String,
+        val depth: Int
     )
 
     override val argsSerializer: KSerializer<Args> = Args.serializer()
+    override val resultSerializer: KSerializer<String> = String.serializer()
  
     override val name = "message"
     override val toolDescription = "Service tool, used by the agent to talk with user"
@@ -499,7 +501,15 @@ object AnalyzeTool : Tool<AnalyzeTool.Args, AnalyzeTool.Result>() {
         val depth: Int
     )
 
+    @Serializable
+    data class Result(
+        val analysis: String,
+        val confidence: Double,
+        val metadata: Map<String, String> = mapOf()
+    )
+
     override val argsSerializer: KSerializer<Args> = Args.serializer()
+    override val resultSerializer: KSerializer<String> = Result.serializer()
  
     override val name = "message"
     override val toolDescription = "Service tool, used by the agent to talk with user"

docs/docs/tools-overview.md

@@ -215,11 +215,7 @@ val analysisAgent = AIAgent(
 val analysisAgentTool = analysisAgent.asTool(
     agentName = "analyzeTransactions",
     agentDescription = "Performs financial transaction analysis",
-    inputDescriptor = ToolParameterDescriptor(
-        name = "request",
-        description = "Transaction analysis request",
-        type = ToolParameterType.String
-    )
+    inputDescription = "Transaction analysis request",
 )
 ```
 <!--- KNIT example-tools-overview-05.kt -->

examples/notebooks/Banking.ipynb

@@ -888,9 +888,8 @@
   },
   {
    "metadata": {
-    "ExecuteTime": {
-     "end_time": "2025-08-18T19:31:37.345301Z",
-     "start_time": "2025-08-18T19:31:37.295809Z"
+    "jupyter": {
+     "is_executing": true
     }
    },
    "cell_type": "code",
@@ -910,31 +909,23 @@
     "            transferAgent.asTool(\n",
     "                agentName = \"transferMoney\",\n",
     "                agentDescription = \"Transfers money and handles all related operations\",\n",
-    "                inputDescriptor = ToolParameterDescriptor(\n",
-    "                    name = \"request\",\n",
-    "                    description = \"Transfer request from the user\",\n",
-    "                    type = ToolParameterType.String\n",
-    "                )\n",
+    "                inputDescription = \"Transfer request from the user\"\n",
     "            )\n",
     "        )\n",
     "\n",
     "        tool(\n",
     "            analysisAgent.asTool(\n",
     "                agentName = \"analyzeTransactions\",\n",
     "                agentDescription = \"Performs analytics on user transactions\",\n",
-    "                inputDescriptor = ToolParameterDescriptor(\n",
-    "                    name = \"request\",\n",
-    "                    description = \"Transaction analytics request\",\n",
-    "                    type = ToolParameterType.String\n",
-    "                )\n",
+    "                inputDescription = \"Transaction analytics request\"\n",
     "            )\n",
     "        )\n",
     "    },\n",
     "    systemPrompt = \"$bankingAssistantSystemPrompt\\n$transactionAnalysisPrompt\"\n",
     ")"
    ],
    "outputs": [],
-   "execution_count": 19
+   "execution_count": null
   },
   {
    "metadata": {},