Inconsistent advice in documentation regarding the use of default values in function tools

[vadakattu]

Describe the bug

On the parent page for custom tools, the guidance strongly advises against the use of default values:

• Do not set default values for parameters. E.g., def my_func(param1: str = "default"). Default values are not reliably supported or used by the underlying models during function call generation. All necessary information should be derived by the LLM from the context or explicitly requested if missing.

Whilst the sub page for function tools encourages the use of optional values in a dedicated section optional parameters section

Optional Parameters

A parameter is considered optional if you provide a default value. This is the standard Python way to define optional arguments. You can also mark a parameter as optional using typing.Optional[SomeType] or the | None syntax (Python 3.10+).

Expected behaviour

Clear and consistent guidance of when function tool argument defaults should and should not be specified.