Background

The previous implementation of toolbox-core treated all tool parameters as implicitly required. This limited the flexibility of tool definitions and did not align with common use cases where tools have optional arguments with default behaviors.

This PR introduces full support for optional parameters, corresponding to the feature added to the Toolbox server (#617), enabling developers to create more versatile and powerful tools. The changes ensure that optionality is correctly reflected and handled at every stage: from the function signature and type hinting down to the final payload sent to the server.

Proposed Changes

This PR introduces a series of coordinated changes across the parameter handling and tool invocation pipeline:

1. ParameterSchema Enhancement

• A new required: bool = True field has been added to the ParameterSchema of the Toolbox protocol, allowing tool manifest authors to explicitly mark parameters as optional.
• The internal __get_type() method now correctly wraps the type in typing.Optional when a parameter has required=False.
• The to_param() method now constructs an inspect.Parameter with default=None for optional parameters.

2. Correct Signature Generation

• In the ToolboxTool.__init__ method, the list of tool parameters is now sorted to place all required parameters before optional ones.
  • This robustly prevents a ValueError: non-default argument follows default argument that could occur if a manifest defined an optional parameter before a required one.

3. Aligned Pydantic Validation

The params_to_pydantic_model utility function has been updated to be aware of the required flag. It now generates Pydantic Field definitions with default=None for optional fields, ensuring runtime validation is consistent with the function signature.

4. Cleaner API Payloads

• The payload now only includes parameters that were explicitly provided by the user in the function call.
• Optional parameters that are omitted will be completely left out of the JSON request body, rather than being sent with a null value.
  • The Toolbox server fills such a field with the user-provided default value.

Impact

• For Tool Authors: You can now define optional parameters in your tool manifests by setting `default: "Some Value".
• For Tool Users: Tools with optional parameters will now have correct, user-friendly Python signatures (e.g., my_tool(required_arg: str, optional_arg: Optional[str] = "Some Value")). Standard tools like help()` and editor autocompletion will work as expected.
• For API Integrity: Requests sent to the Toolbox server are cleaner and more concise, reducing ambiguity by omitting keys for unprovided optional values.