feat(tool): add ToolSchemaModule to support @ToolParam parsing.

[LearningGp]

AgentScope-Java Version

1.0.8

Description

feat(tool): add ToolSchemaModule to support @ToolParam parsing.

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[gemini-code-assist]

Summary of Changes

Hello @LearningGp, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the JSON schema generation capabilities for tools by introducing a dedicated module to process custom @ToolParam annotations. This integration allows for more precise and declarative definition of tool parameter metadata, such as descriptions and requiredness, directly within the code, streamlining the process of creating accurate and informative tool schemas.

Highlights

• New ToolSchemaModule: Introduced a new ToolSchemaModule that integrates with victools JSON Schema generator to interpret @ToolParam annotations. This module allows developers to define descriptions and required status for tool parameters directly in their code using annotations.
• Enhanced JSON Schema Generation: The JsonSchemaUtils utility has been updated to incorporate the new ToolSchemaModule, enabling automatic parsing of @ToolParam annotations when generating JSON schemas for tools. This provides more granular control over schema metadata.
• Configurable Required Fields: The ToolSchemaModule offers an option (PROPERTY_REQUIRED_FALSE_BY_DEFAULT) to control the default 'required' status of un-annotated fields, providing flexibility in schema generation behavior.

Changelog

• agentscope-core/src/main/java/io/agentscope/core/tool/ToolSchemaModule.java
  • Added ToolSchemaModule to interpret @ToolParam annotations for JSON schema generation, handling descriptions and required status.
  • Implemented an option to treat un-annotated fields as optional by default.
• agentscope-core/src/main/java/io/agentscope/core/util/JsonSchemaUtils.java
  • Integrated ToolSchemaModule into the SchemaGeneratorConfigBuilder to enable @ToolParam parsing during JSON schema generation.
  • Configured PROPERTY_REQUIRED_BY_DEFAULT to false for the ToolSchemaModule.
• agentscope-core/src/test/java/io/agentscope/core/tool/ToolSchemaModuleTest.java
  • Added comprehensive unit tests for ToolSchemaModule to verify correct handling of annotated and unannotated fields.
  • Included tests for description parsing, required status, and the PROPERTY_REQUIRED_FALSE_BY_DEFAULT option.

Activity

• The pull request was created by LearningGp.
• No additional human activity (comments, reviews) has been recorded yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a ToolSchemaModule to enable parsing of @ToolParam annotations on POJO fields for JSON schema generation, which is a great feature. The implementation is clean and includes a comprehensive set of unit tests. My main feedback is to address an inconsistency where the name attribute of @ToolParam is ignored by this new module, unlike its handling for method parameters. I've provided a suggestion to align this behavior for better consistency and predictability.

[Copilot]

Pull request overview

This PR adds ToolSchemaModule to enable @ToolParam annotation support for POJO fields in JSON schema generation. This complements the existing Jackson annotation support and provides a consistent annotation approach for both tool method parameters and structured output POJO fields.

Changes:

• Introduces ToolSchemaModule that integrates with victools JSON schema generator to read @ToolParam annotations on POJO fields
• Integrates the new module into JsonSchemaUtils to apply it globally to all schema generation
• Adds comprehensive unit tests for the module covering all annotation scenarios

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
ToolSchemaModule.java	New module implementing victools Module interface to process @ToolParam annotations on POJO fields for description and required metadata
ToolSchemaModuleTest.java	Comprehensive unit tests covering annotated/unannotated fields, required/optional behavior, and edge cases
JsonSchemaUtils.java	Integrates ToolSchemaModule into the static schema generator configuration with PROPERTY_REQUIRED_FALSE_BY_DEFAULT option

[codecov]

Codecov Report

❌ Patch coverage is 92.85714% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...java/io/agentscope/core/tool/ToolSchemaModule.java	92.30%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!