From b5114e99f6cc2d733a949dc15e9ec43340c26062 Mon Sep 17 00:00:00 2001
From: mukunda katta <mukunda.vjcs6@gmail.com>
Date: Tue, 21 Apr 2026 08:19:14 -0700
Subject: [PATCH] docs(toolset): add YAML serialization examples

---
 docs-website/docs/tools/toolset.mdx | 145 ++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)

diff --git a/docs-website/docs/tools/toolset.mdx b/docs-website/docs/tools/toolset.mdx
index ddc0385d8c..abfa83a96b 100644
--- a/docs-website/docs/tools/toolset.mdx
+++ b/docs-website/docs/tools/toolset.mdx
@@ -69,6 +69,98 @@ subtract_tool = Tool(
 math_toolset = Toolset([add_tool, subtract_tool])
 ```
 
+### In YAML
+
+This YAML example shows how to define a `Toolset` with multiple tools inside a pipeline definition and reuse that same `Toolset` when configuring a chat generator.
+
+```yaml
+components:
+  math_toolset:
+    type: haystack.tools.toolset.Toolset
+    data:
+      tools:
+      - type: haystack.tools.tool.Tool
+        data:
+          name: add
+          description: Add two numbers
+          parameters:
+            type: object
+            properties:
+              a:
+                type: integer
+              b:
+                type: integer
+            required:
+            - a
+            - b
+          function: your_module.add_numbers
+          outputs_to_string: null
+          inputs_from_state: null
+          outputs_to_state: null
+      - type: haystack.tools.tool.Tool
+        data:
+          name: subtract
+          description: Subtract b from a
+          parameters:
+            type: object
+            properties:
+              a:
+                type: integer
+              b:
+                type: integer
+            required:
+            - a
+            - b
+          function: your_module.subtract_numbers
+          outputs_to_string: null
+          inputs_from_state: null
+          outputs_to_state: null
+  llm:
+    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
+    init_parameters:
+      model: gpt-4o-mini
+      tools:
+        type: haystack.tools.toolset.Toolset
+        data:
+          tools:
+          - type: haystack.tools.tool.Tool
+            data:
+              name: add
+              description: Add two numbers
+              parameters:
+                type: object
+                properties:
+                  a:
+                    type: integer
+                  b:
+                    type: integer
+                required:
+                - a
+                - b
+              function: your_module.add_numbers
+              outputs_to_string: null
+              inputs_from_state: null
+              outputs_to_state: null
+          - type: haystack.tools.tool.Tool
+            data:
+              name: subtract
+              description: Subtract b from a
+              parameters:
+                type: object
+                properties:
+                  a:
+                    type: integer
+                  b:
+                    type: integer
+                required:
+                - a
+                - b
+              function: your_module.subtract_numbers
+              outputs_to_string: null
+              inputs_from_state: null
+              outputs_to_state: null
+```
+
 ### Adding New Tools to Toolset
 
 ```python
@@ -202,3 +294,56 @@ Output:
 ```
 4 + 2 equals 6.
 ```
+
+The same serialized `Toolset` can also be passed to an `Agent` in YAML through its `tools` init parameter:
+
+```yaml
+components:
+  agent:
+    type: haystack.components.agents.agent.Agent
+    init_parameters:
+      chat_generator:
+        type: haystack.components.generators.chat.openai.OpenAIChatGenerator
+        init_parameters:
+          model: gpt-4o-mini
+      tools:
+        type: haystack.tools.toolset.Toolset
+        data:
+          tools:
+          - type: haystack.tools.tool.Tool
+            data:
+              name: add
+              description: Add two numbers
+              parameters:
+                type: object
+                properties:
+                  a:
+                    type: integer
+                  b:
+                    type: integer
+                required:
+                - a
+                - b
+              function: your_module.add_numbers
+              outputs_to_string: null
+              inputs_from_state: null
+              outputs_to_state: null
+          - type: haystack.tools.tool.Tool
+            data:
+              name: subtract
+              description: Subtract b from a
+              parameters:
+                type: object
+                properties:
+                  a:
+                    type: integer
+                  b:
+                    type: integer
+                required:
+                - a
+                - b
+              function: your_module.subtract_numbers
+              outputs_to_string: null
+              inputs_from_state: null
+              outputs_to_state: null
+```