autobyteus 1.1.6__py3-none-any.whl → 1.1.7__py3-none-any.whl

autobyteus/tools/usage/formatters/default_xml_example_formatter.py

@@ -1,65 +1,103 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/default_xml_example_formatter.py
 import xml.sax.saxutils
-import json # Import json for embedding complex objects
-from typing import Any, TYPE_CHECKING
+import re
+from typing import Any, TYPE_CHECKING, List, Optional
 
-from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition, ParameterSchema
 from .base_formatter import BaseExampleFormatter
-from .default_json_example_formatter import DefaultJsonExampleFormatter # Import for reuse
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
 
 class DefaultXmlExampleFormatter(BaseExampleFormatter):
-    """Formats a tool usage example into a standardized XML <tool> string."""
+    """Formats a tool usage example into a standardized, nested XML <tool> string."""
 
     def provide(self, tool_definition: 'ToolDefinition') -> str:
-        tool_name = tool_definition.name
-        arg_schema = tool_definition.argument_schema
+        """
+        Generates a multi-shot example string for the given tool, including
+        a basic and an advanced usage case.
+        """
+        basic_example = self._generate_basic_example(tool_definition)
+        advanced_example = self._generate_advanced_example(tool_definition)
 
-        example_xml_parts = [f'<tool name="{tool_name}">']
-        arguments_part = []
+        examples = [basic_example]
+        if advanced_example:
+            examples.append(advanced_example)
+        
+        return "\n\n".join(examples)
 
-        if arg_schema and arg_schema.parameters:
-            for param_def in arg_schema.parameters:
-                if param_def.required or param_def.default_value is not None:
-                    placeholder_value = self._generate_placeholder_value(param_def)
-                    # For complex objects/arrays, we now get a dict/list.
-                    # Convert it to a JSON string for embedding in XML.
-                    if isinstance(placeholder_value, (dict, list)):
-                        value_str = json.dumps(placeholder_value, indent=2)
-                    else:
-                        value_str = str(placeholder_value)
-
-                    escaped_value = xml.sax.saxutils.escape(value_str)
-                    
-                    # Add newlines for readability if the value is a multiline JSON string
-                    if '\n' in escaped_value:
-                        arguments_part.append(f'        <arg name="{param_def.name}">\n{escaped_value}\n        </arg>')
-                    else:
-                        arguments_part.append(f'        <arg name="{param_def.name}">{escaped_value}</arg>')
-
-
-        if arguments_part:
+    def _schema_has_advanced_params(self, schema: Optional[ParameterSchema]) -> bool:
+        """Recursively checks if a schema or any of its sub-schemas have non-required parameters."""
+        if not schema:
+            return False
+        for param in schema.parameters:
+            if not param.required:
+                return True  # Found an optional param at this level
+            if param.object_schema and self._schema_has_advanced_params(param.object_schema):
+                return True  # Found an optional param in a nested object
+            if isinstance(param.array_item_schema, ParameterSchema) and self._schema_has_advanced_params(param.array_item_schema):
+                return True  # Found an optional param in an array of objects
+        return False
+
+    def _generate_basic_example(self, tool_def: 'ToolDefinition') -> str:
+        """Generates an XML example including only the required parameters."""
+        tool_name = tool_def.name
+        arg_schema = tool_def.argument_schema
+        
+        example_xml_parts = [
+            "### Example 1: Basic Call (Required Arguments)",
+            f'<tool name="{tool_name}">'
+        ]
+        
+        if arg_schema and any(p.required for p in arg_schema.parameters):
             example_xml_parts.append("    <arguments>")
+            arguments_part = self._generate_arguments_xml(arg_schema.parameters, 2, mode='basic')
             example_xml_parts.extend(arguments_part)
             example_xml_parts.append("    </arguments>")
         else:
-            example_xml_parts.append("    <!-- This tool takes no arguments -->")
+            example_xml_parts.append("    <!-- This tool has no required arguments. -->")
 
         example_xml_parts.append("</tool>")
         return "\n".join(example_xml_parts)
 
-    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
-        # REUSE a more intelligent generator for complex objects
-        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
-            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+    def _generate_advanced_example(self, tool_def: 'ToolDefinition') -> Optional[str]:
+        """
+        Generates a more complex example if the schema has any optional parameters
+        at any level of nesting.
+        """
+        arg_schema = tool_def.argument_schema
+        if not self._schema_has_advanced_params(arg_schema):
+            return None
+        
+        tool_name = tool_def.name
+        example_xml_parts = [
+            "### Example 2: Advanced Call (With Optional & Nested Arguments)",
+            f'<tool name="{tool_name}">'
+        ]
+        
+        if arg_schema and arg_schema.parameters:
+             example_xml_parts.append("    <arguments>")
+             arguments_part = self._generate_arguments_xml(arg_schema.parameters, 2, mode='advanced')
+             example_xml_parts.extend(arguments_part)
+             example_xml_parts.append("    </arguments>")
+        else:
+             return None
+
+        example_xml_parts.append("</tool>")
+        return "\n".join(example_xml_parts)
 
-        # Fallback for primitives
+    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+        """Generates a descriptive placeholder value."""
         if param_def.default_value is not None:
             return param_def.default_value
+
+        if param_def.description:
+            match = re.search(r"e\.g\.,?\s*[`']([^`']+)[`']", param_def.description)
+            if match:
+                return match.group(1)
+
         if param_def.param_type == ParameterType.STRING:
-            return f"example_{param_def.name}"
+            return f"A valid string for '{param_def.name}'"
         if param_def.param_type == ParameterType.INTEGER:
             return 123
         if param_def.param_type == ParameterType.FLOAT:
@@ -68,8 +106,44 @@ class DefaultXmlExampleFormatter(BaseExampleFormatter):
             return True
         if param_def.param_type == ParameterType.ENUM:
             return param_def.enum_values[0] if param_def.enum_values else "enum_val"
-        if param_def.param_type == ParameterType.OBJECT:
-            return {"key": "value"} # Fallback if no schema
-        if param_def.param_type == ParameterType.ARRAY:
-            return ["item1", "item2"]
         return "placeholder"
+
+    def _generate_arguments_xml(self, params: List[ParameterDefinition], indent_level: int, mode: str) -> List[str]:
+        """Recursively generates XML for a list of parameter definitions based on the mode."""
+        xml_lines = []
+        indent = "    " * indent_level
+
+        params_to_render = params
+        if mode == 'basic':
+            params_to_render = [p for p in params if p.required]
+
+        for param_def in params_to_render:
+            param_name = param_def.name
+            
+            if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
+                xml_lines.append(f'{indent}<arg name="{param_name}">')
+                xml_lines.extend(self._generate_arguments_xml(param_def.object_schema.parameters, indent_level + 1, mode=mode))
+                xml_lines.append(f'{indent}</arg>')
+
+            elif param_def.param_type == ParameterType.ARRAY:
+                xml_lines.append(f'{indent}<arg name="{param_name}">')
+                
+                if isinstance(param_def.array_item_schema, ParameterSchema): # Array of objects
+                    xml_lines.append(f'{indent}    <item>')
+                    xml_lines.extend(self._generate_arguments_xml(param_def.array_item_schema.parameters, indent_level + 2, mode=mode))
+                    xml_lines.append(f'{indent}    </item>')
+                    xml_lines.append(f'{indent}    <!-- (more items as needed) -->')
+                else: # Array of primitives
+                    placeholder_1 = self._generate_placeholder_value(ParameterDefinition(name=f"{param_name}_item_1", param_type=ParameterType.STRING, description="An item from the list."))
+                    placeholder_2 = self._generate_placeholder_value(ParameterDefinition(name=f"{param_name}_item_2", param_type=ParameterType.STRING, description="An item from the list."))
+                    xml_lines.append(f'{indent}    <item>{xml.sax.saxutils.escape(str(placeholder_1))}</item>')
+                    xml_lines.append(f'{indent}    <item>{xml.sax.saxutils.escape(str(placeholder_2))}</item>')
+
+                xml_lines.append(f'{indent}</arg>')
+            
+            else: # Primitive types
+                placeholder_value = self._generate_placeholder_value(param_def)
+                escaped_value = xml.sax.saxutils.escape(str(placeholder_value))
+                xml_lines.append(f'{indent}<arg name="{param_name}">{escaped_value}</arg>')
+        
+        return xml_lines

autobyteus/tools/usage/formatters/default_xml_schema_formatter.py

@@ -1,20 +1,20 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/default_xml_schema_formatter.py
 import xml.sax.saxutils
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, List
 
-from autobyteus.tools.parameter_schema import ParameterType
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition, ParameterSchema
 from .base_formatter import BaseSchemaFormatter
 
 if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
 
 class DefaultXmlSchemaFormatter(BaseSchemaFormatter):
-    """Formats a tool's schema into a standardized XML string."""
+    """Formats a tool's schema into a standardized, potentially nested, XML string."""
 
     def provide(self, tool_definition: 'ToolDefinition') -> str:
-        arg_schema = tool_definition.argument_schema
         tool_name = tool_definition.name
         description = tool_definition.description
+        arg_schema = tool_definition.argument_schema
 
         escaped_description = xml.sax.saxutils.escape(description) if description else ""
         tool_tag = f'<tool name="{tool_name}" description="{escaped_description}">'
@@ -22,25 +22,55 @@ class DefaultXmlSchemaFormatter(BaseSchemaFormatter):
 
         if arg_schema and arg_schema.parameters:
             xml_parts.append("    <arguments>")
-            for param in arg_schema.parameters:
-                arg_tag = f'        <arg name="{param.name}"'
-                arg_tag += f' type="{param.param_type.value}"'
-                if param.description:
-                    escaped_param_desc = xml.sax.saxutils.escape(param.description)
-                    arg_tag += f' description="{escaped_param_desc}"'
-                arg_tag += f" required=\"{'true' if param.required else 'false'}\""
-
-                if param.default_value is not None:
-                    arg_tag += f' default="{xml.sax.saxutils.escape(str(param.default_value))}"'
-                if param.param_type == ParameterType.ENUM and param.enum_values:
-                    escaped_enum_values = [xml.sax.saxutils.escape(ev) for ev in param.enum_values]
-                    arg_tag += f' enum_values="{",".join(escaped_enum_values)}"'
-
-                arg_tag += " />"
-                xml_parts.append(arg_tag)
+            xml_parts.extend(self._format_params_recursively(arg_schema.parameters, 2))
             xml_parts.append("    </arguments>")
         else:
             xml_parts.append("    <!-- This tool takes no arguments -->")
 
         xml_parts.append("</tool>")
         return "\n".join(xml_parts)
+
+    def _format_params_recursively(self, params: List[ParameterDefinition], indent_level: int) -> List[str]:
+        """Recursively formats parameter definitions into XML strings."""
+        xml_lines = []
+        indent = "    " * indent_level
+
+        for param in params:
+            attrs = [
+                f'name="{param.name}"',
+                f'type="{param.param_type.value}"'
+            ]
+            if param.description:
+                attrs.append(f'description="{xml.sax.saxutils.escape(param.description)}"')
+            
+            attrs.append(f"required=\"{'true' if param.required else 'false'}\"")
+
+            if param.default_value is not None:
+                attrs.append(f'default="{xml.sax.saxutils.escape(str(param.default_value))}"')
+            if param.param_type == ParameterType.ENUM and param.enum_values:
+                escaped_enum = [xml.sax.saxutils.escape(ev) for ev in param.enum_values]
+                attrs.append(f'enum_values="{",".join(escaped_enum)}"')
+
+            is_object = param.param_type == ParameterType.OBJECT and param.object_schema
+            is_array = param.param_type == ParameterType.ARRAY and param.array_item_schema
+
+            if is_object:
+                xml_lines.append(f'{indent}<arg {" ".join(attrs)}>')
+                xml_lines.extend(self._format_params_recursively(param.object_schema.parameters, indent_level + 1))
+                xml_lines.append(f'{indent}</arg>')
+            elif is_array:
+                xml_lines.append(f'{indent}<arg {" ".join(attrs)}>')
+                if isinstance(param.array_item_schema, ParameterSchema):
+                    # Array of objects
+                    xml_lines.append(f'{indent}    <items type="object">')
+                    xml_lines.extend(self._format_params_recursively(param.array_item_schema.parameters, indent_level + 2))
+                    xml_lines.append(f'{indent}    </items>')
+                elif isinstance(param.array_item_schema, ParameterType):
+                    # Array of primitives
+                    xml_lines.append(f'{indent}    <items type="{param.array_item_schema.value}" />')
+                xml_lines.append(f'{indent}</arg>')
+            else:
+                # This is a simple/primitive type or a generic array
+                xml_lines.append(f'{indent}<arg {" ".join(attrs)} />')
+
+        return xml_lines

autobyteus/tools/usage/formatters/gemini_json_example_formatter.py

@@ -1,7 +1,8 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/gemini_json_example_formatter.py
-from typing import Dict, Any, TYPE_CHECKING
+import json
+from typing import Dict, Any, TYPE_CHECKING, Optional
 
-from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
 from .default_json_example_formatter import DefaultJsonExampleFormatter # Import for reuse
 
@@ -9,32 +10,64 @@ if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
 
 class GeminiJsonExampleFormatter(BaseExampleFormatter):
-    """Formats a tool usage example into the Google Gemini tool_calls format."""
+    """
+    Formats a tool usage example into the Google Gemini tool_calls format.
+    Provides both basic (required only) and advanced (all) examples if optional
+    parameters exist for the tool.
+    """
 
-    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates a formatted string containing basic and optionally an advanced usage example for the tool.
+        """
+        basic_example_dict = self._create_example_structure(tool_definition, mode='basic')
+        basic_example_str = "### Example 1: Basic Call (Required Arguments)\n"
+        basic_example_str += "```json\n"
+        basic_example_str += json.dumps(basic_example_dict, indent=2)
+        basic_example_str += "\n```"
+        
+        if not self._schema_has_advanced_params(tool_definition.argument_schema):
+            return basic_example_str
+
+        advanced_example_dict = self._create_example_structure(tool_definition, mode='advanced')
+        advanced_example_str = "### Example 2: Advanced Call (With Optional Arguments)\n"
+        advanced_example_str += "```json\n"
+        advanced_example_str += json.dumps(advanced_example_dict, indent=2)
+        advanced_example_str += "\n```"
+        
+        return f"{basic_example_str}\n\n{advanced_example_str}"
+
+    def _create_example_structure(self, tool_definition: 'ToolDefinition', mode: str) -> Dict:
+        """Helper to create a single Gemini tool call example for a given mode."""
         tool_name = tool_definition.name
         arg_schema = tool_definition.argument_schema
         arguments = {}
 
         if arg_schema and arg_schema.parameters:
-            for param_def in arg_schema.parameters:
-                if param_def.required or param_def.default_value is not None:
-                    arguments[param_def.name] = self._generate_placeholder_value(param_def)
-
+            params_to_render = arg_schema.parameters
+            if mode == 'basic':
+                params_to_render = [p for p in arg_schema.parameters if p.required]
+            
+            for param_def in params_to_render:
+                # Use the intelligent placeholder generator from the default formatter
+                arguments[param_def.name] = DefaultJsonExampleFormatter._generate_example_from_schema(
+                    param_def.object_schema or param_def.array_item_schema or param_def.param_type, 
+                    param_def.object_schema or arg_schema,
+                    mode=mode
+                ) if param_def.object_schema or param_def.array_item_schema else self._generate_simple_placeholder(param_def)
+        
         return {"name": tool_name, "args": arguments}
 
-    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
-        # REUSE a more intelligent generator for complex objects
-        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
-            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
-            
-        # Fallback for primitives
+    def _schema_has_advanced_params(self, schema: Optional[ParameterSchema]) -> bool:
+        """Recursively checks if a schema or any of its sub-schemas have non-required parameters."""
+        if not schema: return False
+        for param in schema.parameters:
+            if not param.required: return True
+            if param.object_schema and self._schema_has_advanced_params(param.object_schema): return True
+            if isinstance(param.array_item_schema, ParameterSchema) and self._schema_has_advanced_params(param.array_item_schema): return True
+        return False
+
+    def _generate_simple_placeholder(self, param_def: ParameterDefinition) -> Any:
+        """Generates a simple placeholder for primitive types."""
         if param_def.default_value is not None: return param_def.default_value
-        if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
-        if param_def.param_type == ParameterType.INTEGER: return 123
-        if param_def.param_type == ParameterType.FLOAT: return 123.45
-        if param_def.param_type == ParameterType.BOOLEAN: return True
-        if param_def.param_type == ParameterType.ENUM: return param_def.enum_values[0] if param_def.enum_values else "enum_val"
-        if param_def.param_type == ParameterType.OBJECT: return {"key": "value"}
-        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
-        return "placeholder"
+        return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.param_type, param_def.param_type, mode='basic')

autobyteus/tools/usage/formatters/google_json_example_formatter.py

@@ -1,7 +1,8 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/google_json_example_formatter.py
-from typing import Dict, Any, TYPE_CHECKING
+import json
+from typing import Dict, Any, TYPE_CHECKING, Optional
 
-from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
 # Import for reuse of the intelligent example generation logic
 from .default_json_example_formatter import DefaultJsonExampleFormatter
@@ -10,32 +11,64 @@ if TYPE_CHECKING:
     from autobyteus.tools.registry import ToolDefinition
 
 class GoogleJsonExampleFormatter(BaseExampleFormatter):
-    """Formats a tool usage example into the Google JSON tool_calls format."""
+    """
+    Formats a tool usage example into the Google JSON tool_calls format.
+    Provides both basic (required only) and advanced (all) examples if optional
+    parameters exist for the tool.
+    """
 
-    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates a formatted string containing basic and optionally an advanced usage example for the tool.
+        """
+        basic_example_dict = self._create_example_structure(tool_definition, mode='basic')
+        basic_example_str = "### Example 1: Basic Call (Required Arguments)\n"
+        basic_example_str += "```json\n"
+        basic_example_str += json.dumps(basic_example_dict, indent=2)
+        basic_example_str += "\n```"
+        
+        if not self._schema_has_advanced_params(tool_definition.argument_schema):
+            return basic_example_str
+
+        advanced_example_dict = self._create_example_structure(tool_definition, mode='advanced')
+        advanced_example_str = "### Example 2: Advanced Call (With Optional Arguments)\n"
+        advanced_example_str += "```json\n"
+        advanced_example_str += json.dumps(advanced_example_dict, indent=2)
+        advanced_example_str += "\n```"
+        
+        return f"{basic_example_str}\n\n{advanced_example_str}"
+
+    def _create_example_structure(self, tool_definition: 'ToolDefinition', mode: str) -> Dict:
+        """Helper to create a single Google tool call example for a given mode."""
         tool_name = tool_definition.name
         arg_schema = tool_definition.argument_schema
         arguments = {}
 
         if arg_schema and arg_schema.parameters:
-            for param_def in arg_schema.parameters:
-                if param_def.required or param_def.default_value is not None:
-                    arguments[param_def.name] = self._generate_placeholder_value(param_def)
-
+            params_to_render = arg_schema.parameters
+            if mode == 'basic':
+                params_to_render = [p for p in arg_schema.parameters if p.required]
+            
+            for param_def in params_to_render:
+                # Use the intelligent placeholder generator from the default formatter
+                arguments[param_def.name] = DefaultJsonExampleFormatter._generate_example_from_schema(
+                    param_def.object_schema or param_def.array_item_schema or param_def.param_type, 
+                    param_def.object_schema or arg_schema,
+                    mode=mode
+                ) if param_def.object_schema or param_def.array_item_schema else self._generate_simple_placeholder(param_def)
+        
         return {"name": tool_name, "args": arguments}
 
-    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
-        # REUSE the intelligent generator for complex objects
-        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
-            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+    def _schema_has_advanced_params(self, schema: Optional[ParameterSchema]) -> bool:
+        """Recursively checks if a schema or any of its sub-schemas have non-required parameters."""
+        if not schema: return False
+        for param in schema.parameters:
+            if not param.required: return True
+            if param.object_schema and self._schema_has_advanced_params(param.object_schema): return True
+            if isinstance(param.array_item_schema, ParameterSchema) and self._schema_has_advanced_params(param.array_item_schema): return True
+        return False
 
-        # Fallback for primitives
+    def _generate_simple_placeholder(self, param_def: ParameterDefinition) -> Any:
+        """Generates a simple placeholder for primitive types."""
         if param_def.default_value is not None: return param_def.default_value
-        if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
-        if param_def.param_type == ParameterType.INTEGER: return 123
-        if param_def.param_type == ParameterType.FLOAT: return 123.45
-        if param_def.param_type == ParameterType.BOOLEAN: return True
-        if param_def.param_type == ParameterType.ENUM: return param_def.enum_values[0] if param_def.enum_values else "enum_val"
-        if param_def.param_type == ParameterType.OBJECT: return {"key": "value"}
-        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
-        return "placeholder"
+        return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.param_type, param_def.param_type, mode='basic')

autobyteus/tools/usage/formatters/openai_json_example_formatter.py

@@ -1,8 +1,8 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/openai_json_example_formatter.py
 import json
-from typing import Dict, Any, TYPE_CHECKING
+from typing import Dict, Any, TYPE_CHECKING, Optional
 
-from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition
 from .base_formatter import BaseExampleFormatter
 from .default_json_example_formatter import DefaultJsonExampleFormatter # Import for reuse
 
@@ -11,41 +11,71 @@ if TYPE_CHECKING:
 
 class OpenAiJsonExampleFormatter(BaseExampleFormatter):
     """
-    Formats a tool usage example into a format resembling an entry in the
-    OpenAI JSON 'tool_calls' array, intended for prompting a model.
+    Formats a tool usage example into the OpenAI JSON 'tool_calls' format.
+    Provides both basic (required only) and advanced (all) examples if optional
+    parameters exist for the tool.
     """
+    
+    def provide(self, tool_definition: 'ToolDefinition') -> str:
+        """
+        Generates a formatted string containing basic and optionally an advanced usage example for the tool.
+        """
+        basic_example_dict = self._create_example_structure(tool_definition, mode='basic')
+        basic_example_str = "### Example 1: Basic Call (Required Arguments)\n"
+        basic_example_str += "```json\n"
+        basic_example_str += json.dumps(basic_example_dict, indent=2)
+        basic_example_str += "\n```"
+        
+        if not self._schema_has_advanced_params(tool_definition.argument_schema):
+            return basic_example_str
 
-    def provide(self, tool_definition: 'ToolDefinition') -> Dict:
+        advanced_example_dict = self._create_example_structure(tool_definition, mode='advanced')
+        advanced_example_str = "### Example 2: Advanced Call (With Optional Arguments)\n"
+        advanced_example_str += "```json\n"
+        advanced_example_str += json.dumps(advanced_example_dict, indent=2)
+        advanced_example_str += "\n```"
+        
+        return f"{basic_example_str}\n\n{advanced_example_str}"
+
+    def _create_example_structure(self, tool_definition: 'ToolDefinition', mode: str) -> Dict:
+        """Helper to create a single OpenAI tool call example for a given mode."""
         tool_name = tool_definition.name
         arg_schema = tool_definition.argument_schema
         arguments = {}
 
         if arg_schema and arg_schema.parameters:
-            for param_def in arg_schema.parameters:
-                if param_def.required or param_def.default_value is not None:
-                    arguments[param_def.name] = self._generate_placeholder_value(param_def)
+            params_to_render = arg_schema.parameters
+            if mode == 'basic':
+                params_to_render = [p for p in arg_schema.parameters if p.required]
+            
+            for param_def in params_to_render:
+                # Use the intelligent placeholder generator from the default formatter
+                arguments[param_def.name] = DefaultJsonExampleFormatter._generate_example_from_schema(
+                    param_def.object_schema or param_def.array_item_schema or param_def.param_type, 
+                    param_def.object_schema or arg_schema,
+                    mode=mode
+                ) if param_def.object_schema or param_def.array_item_schema else self._generate_simple_placeholder(param_def)
 
         function_call = {
             "function": {
                 "name": tool_name,
-                "arguments": json.dumps(arguments),
+                # FIX: Keep arguments as a dictionary for clear examples in the prompt.
+                # Do NOT stringify it here.
+                "arguments": arguments,
             },
         }
-
         return {"tool": function_call}
 
-    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
-        # REUSE a more intelligent generator for complex objects
-        if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
-            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+    def _schema_has_advanced_params(self, schema: Optional[ParameterSchema]) -> bool:
+        """Recursively checks if a schema or any of its sub-schemas have non-required parameters."""
+        if not schema: return False
+        for param in schema.parameters:
+            if not param.required: return True
+            if param.object_schema and self._schema_has_advanced_params(param.object_schema): return True
+            if isinstance(param.array_item_schema, ParameterSchema) and self._schema_has_advanced_params(param.array_item_schema): return True
+        return False
 
-        # Fallback for primitives
+    def _generate_simple_placeholder(self, param_def: ParameterDefinition) -> Any:
+        """Generates a simple placeholder for primitive types."""
         if param_def.default_value is not None: return param_def.default_value
-        if param_def.param_type == ParameterType.STRING: return f"example_{param_def.name}"
-        if param_def.param_type == ParameterType.INTEGER: return 123
-        if param_def.param_type == ParameterType.FLOAT: return 123.45
-        if param_def.param_type == ParameterType.BOOLEAN: return True
-        if param_def.param_type == ParameterType.ENUM: return param_def.enum_values[0] if param_def.enum_values else "enum_val"
-        if param_def.param_type == ParameterType.OBJECT: return {"key": "value"}
-        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"]
-        return "placeholder"
+        return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.param_type, param_def.param_type, mode='basic')