Fixes to detect optional parameters in tool conversion used by "nat mcp serve" (#1133)

Parameters with default values were incorrectly marked as required in MCP tool schemas. Now checking for PydanticUndefined and properly extracting default values from Pydantic fields to correctly identify optional parameters.

This PR also adds comprehensive unit tests for the tool schema conversion

- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

* **New Features**
  * Improved detection and handling of optional parameters and default/default-factory values in tool wrapper generation, with unified validation and consistent invocation behavior for workflows and regular functions.
  * Ensures parameter descriptions, order, and type annotations are preserved in generated wrappers.

* **Tests**
  * Added comprehensive tests covering optional/default combinations, wrapper signatures, execution paths, and observability propagation.


## Summary by CodeRabbit

## Release Notes

* **New Features**
  * Added improved support for optional parameters in MCP tools with enhanced default value handling.

* **Bug Fixes**
  * Fixed inconsistent behavior with nested schema validation and default factory application in tool parameters.

* **Tests**
  * Added comprehensive test coverage for optional field handling and parameter validation scenarios.

Authors:
  - Will Killian (https://github.com/willkill07)
  - Anuradha Karuppiah (https://github.com/AnuradhaKaruppiah)

Approvers:
  - Anuradha Karuppiah (https://github.com/AnuradhaKaruppiah)

URL: #1133

Author: willkill07

src/nat/front_ends/mcp/tool_converter.py

@@ -18,9 +18,12 @@
 from inspect import Parameter
 from inspect import Signature
 from typing import TYPE_CHECKING
+from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
 
 from nat.builder.context import ContextState
 from nat.builder.function import Function
@@ -31,6 +34,41 @@
 
 logger = logging.getLogger(__name__)
 
+# Sentinel: marks "optional; let Pydantic supply default/factory"
+_USE_PYDANTIC_DEFAULT = object()
+
+
+def is_field_optional(field: FieldInfo) -> tuple[bool, Any]:
+    """Determine if a Pydantic field is optional and extract its default value for MCP signatures.
+
+    For MCP tool signatures, we need to distinguish:
+    - Required fields: marked with Parameter.empty
+    - Optional with concrete default: use that default
+    - Optional with factory: use sentinel so Pydantic can apply the factory later
+
+    Args:
+        field: The Pydantic FieldInfo to check
+
+    Returns:
+        A tuple of (is_optional, default_value):
+        - (False, Parameter.empty) for required fields
+        - (True, actual_default) for optional fields with explicit defaults
+        - (True, _USE_PYDANTIC_DEFAULT) for optional fields with default_factory
+    """
+    if field.is_required():
+        return False, Parameter.empty
+
+    # Field is optional - has either default or factory
+    if field.default is not PydanticUndefined:
+        return True, field.default
+
+    # Factory case: mark optional in signature but don't fabricate a value
+    if field.default_factory is not None:
+        return True, _USE_PYDANTIC_DEFAULT
+
+    # Rare corner case: non-required yet no default surfaced
+    return True, _USE_PYDANTIC_DEFAULT
+
 
 def create_function_wrapper(
     function_name: str,
@@ -76,12 +114,15 @@ def create_function_wrapper(
             # Get the field type and convert to appropriate Python type
             field_type = field.annotation
 
+            # Check if field is optional and get its default value
+            _is_optional, param_default = is_field_optional(field)
+
             # Add the parameter to our list
             parameters.append(
                 Parameter(
                     name=name,
                     kind=Parameter.KEYWORD_ONLY,
-                    default=Parameter.empty if field.is_required else None,
+                    default=param_default,
                     annotation=field_type,
                 ))
 
@@ -140,33 +181,23 @@ async def call_with_observability(func_call):
                         result = await call_with_observability(lambda: function.ainvoke(chat_request, to_type=str))
                 else:
                     # Regular handling
-                    # Handle complex input schema - if we extracted fields from a nested schema,
-                    # we need to reconstruct the input
-                    if len(schema.model_fields) == 1 and len(parameters) > 1:
-                        # Get the field name from the original schema
-                        field_name = next(iter(schema.model_fields.keys()))
-                        field_type = schema.model_fields[field_name].annotation
-
-                        # If it's a pydantic model, we need to create an instance
-                        if field_type and hasattr(field_type, "model_validate"):
-                            # Create the nested object
-                            nested_obj = field_type.model_validate(kwargs)
-                            # Call with the nested object
-                            kwargs = {field_name: nested_obj}
+                    # Strip sentinel values so Pydantic can apply defaults/factories
+                    cleaned_kwargs = {k: v for k, v in kwargs.items() if v is not _USE_PYDANTIC_DEFAULT}
+
+                    # Always validate with the declared schema
+                    # This handles defaults, factories, nested models, validators, etc.
+                    model_input = schema.model_validate(cleaned_kwargs)
 
                     # Call the NAT function with the parameters - special handling for Workflow
                     if is_workflow:
-                        # For workflow with regular input, we'll assume the first parameter is the input
-                        input_value = list(kwargs.values())[0] if kwargs else ""
-
-                        # Workflows have a run method that is an async context manager
-                        # that returns a Runner
-                        async with function.run(input_value) as runner:
+                        # Workflows expect the model instance directly
+                        async with function.run(model_input) as runner:
                             # Get the result from the runner
                             result = await runner.result(to_type=str)
                     else:
-                        # Regular function call
-                        result = await call_with_observability(lambda: function.acall_invoke(**kwargs))
+                        # Regular function call - unpack the validated model
+                        result = await call_with_observability(lambda: function.acall_invoke(**model_input.model_dump())
+                                                               )
 
                 # Report completion
                 if ctx: