Issue 3884 Improve tool parameter conversion error messages

[wilocu]

Summary

This PR enhances error handling for tool parameter type conversion failures by providing detailed, actionable error messages when the model returns
values that cannot be converted to expected parameter types (e.g., empty strings for numeric parameters).

Changes

1. New ToolParameterConversionException Class

• Extends ToolExecutionException to provide parameter-specific context
• Includes parameter name, expected type, actual value, and helpful suggestions
• Provides different guidance for numeric vs non-numeric type failures

2. Enhanced MethodToolCallback

• Catches NumberFormatException and IllegalStateException during parameter conversion
• Wraps conversion errors with ToolParameterConversionException including parameter context
• Maintains backward compatibility through exception hierarchy

3. Improved JsonParser.toTypedObject()

• Better error messages for all numeric type conversions (Byte, Short, Integer, Long, Float, Double)
• Enhanced enum conversion error messages with available options
• Filters redundant original error messages for cleaner output

Error Message Examples

Before:
java.lang.NumberFormatException: null

After:
Tool parameter conversion failed for parameter 'userId' in tool 'getUserData':
Expected type: Long, but received: "" (empty string)
Suggestion: Ensure your prompt clearly specifies that numeric parameters should contain valid numbers, not empty strings.
Consider making the parameter optional or providing a default value in your tool description.

Testing

• Added comprehensive test coverage for new exception types
• Validated error message quality and content
• Ensured no regressions in existing functionality
• All 35 JsonParserTests pass, confirming backward compatibility

Signed-off-by: Mattia Pasetto [email protected]

I am still pretty new to contributions, please double check and let me know of any errors.