GH-2947: Add @ToolParam annotation support for parameter name binding #3803
+181 −3
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
✨ Summary
This PR introduces support for the @ToolParam annotation, enabling flexible and explicit JSON-to-method parameter binding when invoking tools via MethodToolCallback.
✨ Changes
Introduced @ToolParam(String value) annotation
Enhanced MethodToolCallback to resolve method parameters by:
First using @ToolParam.value if present
Falling back to the actual parameter name otherwise
Allows flexible and explicit JSON-to-parameter binding for method-based tools
💡 Example
Developers can now define tool methods like this:
Given the input:
{ "user_name": "Alice" }The method will be invoked with name set to 'Alice'
This enhances flexibility when defining tools and avoids tight coupling between Java parameter names and input JSON structure.
🧪 Tests & Verification
✅ Unit tests added for:
Binding using @ToolParam("alias")
Binding with empty @ToolParam (falls back to parameter name)
Missing input values (should pass null)
Multiple annotated parameters
Compatibility with generic types and ToolContext
✅ ./mvnw clean verify passed (including Checkstyle)
✅ Apache license headers
✅ DCO signed
✅ Rebased on latest main, linear commit history maintained
📘 Documentation
JavaDoc provided for the new @ToolParam annotation
Inline comments in MethodToolCallback clarify binding logic
🔗 Closes #2947
📬 Let me know if any adjustments or refinements are needed!