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

autobyteus/tools/usage/formatters/default_json_example_formatter.py

@@ -1,7 +1,8 @@
 # file: autobyteus/autobyteus/tools/usage/formatters/default_json_example_formatter.py
-from typing import Dict, Any, TYPE_CHECKING, List, Optional
+import json
+from typing import Dict, Any, TYPE_CHECKING, List, Optional, Union
 
-from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition
+from autobyteus.tools.parameter_schema import ParameterType, ParameterDefinition, ParameterSchema
 from .base_formatter import BaseExampleFormatter
 
 if TYPE_CHECKING:
@@ -10,20 +11,47 @@ if TYPE_CHECKING:
 class DefaultJsonExampleFormatter(BaseExampleFormatter):
     """
     Formats a tool usage example into a generic JSON format.
-    It intelligently generates detailed examples for complex object schemas.
+    It intelligently generates detailed examples for complex object schemas, providing
+    both a basic (required parameters only) and an advanced (all parameters) example
+    if optional parameters are available.
     """
 
-    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 the full tool call example structure 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:
-                # Always include required parameters in the example.
-                # Also include optional parameters that have a default value to show common usage.
-                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':
+                # In basic mode, we only render required parameters.
+                params_to_render = [p for p in arg_schema.parameters if p.required]
+            
+            for param_def in params_to_render:
+                arguments[param_def.name] = self._generate_placeholder_value(param_def, mode=mode)
 
         return {
             "tool": {
@@ -32,12 +60,34 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
             },
         }
 
-    def _generate_placeholder_value(self, param_def: ParameterDefinition) -> Any:
+    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_placeholder_value(self, param_def: ParameterDefinition, mode: str = 'basic') -> Any:
+        """
+        Generates a placeholder value for a parameter, recursing for complex types.
+        The mode determines whether to include optional fields in nested structures.
+        """
         # If an object parameter has a detailed schema, generate a structured example from it.
         if param_def.param_type == ParameterType.OBJECT and param_def.object_schema:
-            # We pass the full schema document to allow for resolving $refs
-            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema)
+            return DefaultJsonExampleFormatter._generate_example_from_schema(param_def.object_schema, param_def.object_schema, mode=mode)
         
+        # Handle arrays with a detailed item schema.
+        if param_def.param_type == ParameterType.ARRAY and param_def.array_item_schema:
+            # Generate one example item for the array to keep it concise.
+            example_item = DefaultJsonExampleFormatter._generate_example_from_schema(param_def.array_item_schema, param_def.array_item_schema, mode=mode)
+            return [example_item]
+
         # Fallback to simple placeholder generation for primitives or objects without schemas.
         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}"
@@ -46,15 +96,34 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
         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"]
+        if param_def.param_type == ParameterType.ARRAY: return ["item1", "item2"] # This now only applies to generic arrays
         return "placeholder"
 
     @staticmethod
-    def _generate_example_from_schema(sub_schema: Dict[str, Any], full_schema: Dict[str, Any]) -> Any:
+    def _generate_example_from_schema(
+        sub_schema: Union[Dict[str, Any], 'ParameterSchema', 'ParameterType'], 
+        full_schema: Union[Dict[str, Any], 'ParameterSchema', 'ParameterType'], 
+        mode: str = 'basic'
+    ) -> Any:
         """
         Recursively generates an example value from a JSON schema dictionary.
         This is a static method so it can be reused by other formatters.
+        The 'mode' parameter controls whether optional fields are included in nested objects.
+        The default mode is 'basic' to maintain backward compatibility.
         """
+        # FIX: Handle primitive ParameterType for array items directly.
+        if isinstance(sub_schema, ParameterType):
+            if sub_schema == ParameterType.STRING: return "example_string"
+            if sub_schema == ParameterType.INTEGER: return 1
+            if sub_schema == ParameterType.FLOAT: return 1.1
+            if sub_schema == ParameterType.BOOLEAN: return True
+            return "unknown_primitive"
+
+        if isinstance(sub_schema, ParameterSchema):
+            sub_schema = sub_schema.to_json_schema_dict()
+        if isinstance(full_schema, ParameterSchema):
+            full_schema = full_schema.to_json_schema_dict()
+
         if "$ref" in sub_schema:
             ref_path = sub_schema["$ref"]
             try:
@@ -63,7 +132,7 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
                 resolved_schema = full_schema
                 for part in parts:
                     resolved_schema = resolved_schema[part]
-                return DefaultJsonExampleFormatter._generate_example_from_schema(resolved_schema, full_schema)
+                return DefaultJsonExampleFormatter._generate_example_from_schema(resolved_schema, full_schema, mode=mode)
             except (KeyError, IndexError):
                 return {"error": f"Could not resolve schema reference: {ref_path}"}
 
@@ -80,16 +149,16 @@ class DefaultJsonExampleFormatter(BaseExampleFormatter):
             properties = sub_schema.get("properties", {})
             required_fields = sub_schema.get("required", [])
             for prop_name, prop_schema in properties.items():
-                # Include required fields and a subset of optional fields for a concise example.
-                if prop_name in required_fields:
-                    example_obj[prop_name] = DefaultJsonExampleFormatter._generate_example_from_schema(prop_schema, full_schema)
+                # Include fields if in 'advanced' mode or if they are required.
+                if mode == 'advanced' or prop_name in required_fields:
+                    example_obj[prop_name] = DefaultJsonExampleFormatter._generate_example_from_schema(prop_schema, full_schema, mode=mode)
             return example_obj
         
         elif schema_type == "array":
             items_schema = sub_schema.get("items")
             if isinstance(items_schema, dict):
-                # Generate one example item for the array to keep it concise
-                return [DefaultJsonExampleFormatter._generate_example_from_schema(items_schema, full_schema)]
+                # Generate one example item for the array to keep it concise.
+                return [DefaultJsonExampleFormatter._generate_example_from_schema(items_schema, full_schema, mode=mode)]
             else:
                 return ["example_item_1"]
 

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')