GH-2947: Add @ToolParam annotation support for parameter name binding #3803
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!