feat(tools): enforce built-in tools limitations at build/start with h…

[WastingTimeToThink]

…elpful errors

• Add BuiltInTool marker interface.
• Add ToolConstraints to validate agent tree: (A1) only one built-in tool per agent; cannot mix with others (A2) built-ins forbidden in sub-agents
• Hook validation at LlmAgent.Builder#build()
• Unit tests for 5 scenarios; helpful error messages with docs link.

[gemini-code-assist]

Summary of Changes

Hello @WastingTimeToThink, 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 introduces robust validation for "built-in tools" within the adk framework, ensuring that LlmAgent configurations adhere to specific usage constraints. The changes prevent invalid tool setups by enforcing rules at build time, providing clear and helpful error messages to guide developers. This enhances the stability and predictability of agent behavior by catching configuration issues early.

Highlights

• New Built-in Tool Definition: A new marker interface, BuiltInTool, has been introduced to explicitly designate tools that have special framework-level constraints, allowing for their distinct identification and validation.
• Tool Constraint Validation Logic: A new utility class, ToolConstraints, has been added to enforce specific rules for built-in tools. These rules include allowing only one built-in tool per agent (and disallowing mixing with other tool types) and prohibiting built-in tools within sub-agents.
• Build-time Enforcement: The validation logic from ToolConstraints is now hooked into the LlmAgent.Builder#build() method. This ensures that any violations of built-in tool usage rules are caught early at build or startup time, preventing invalid agent configurations from being created.
• Comprehensive Unit Tests: Comprehensive unit tests have been added for the ToolConstraints class, covering various valid and invalid scenarios. These tests ensure the robustness and correctness of the new validation rules, providing confidence in the enforcement mechanism.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 helpful build-time validation for built-in tool usage, preventing incorrect configurations. The implementation is well-structured, using a dedicated ToolConstraints class and a BuiltInTool marker interface. The use of MethodHandles for compatibility is a smart way to ensure loose coupling. The unit tests effectively cover the new validation rules. I've included a few suggestions to enhance code clarity and remove minor redundancies.

[WastingTimeToThink]

Enforce Built-in tools limitations (Java): early guardrails + helpful error messages

Summary

Add BuiltInTool marker interface.
Add ToolConstraints for agent-tree validation.
Enforce two documented limitations at build/start:
Only one built-in tool per agent; cannot mix with other tools.
Built-in tools cannot be used in sub-agents.
Fail fast with actionable messages linking to docs.

Details

Introduce tools/internal/ToolConstraints to validate the full agent tree.
Integrated validation call in LlmAgent.Builder#build() to ensure invalid configurations are caught at construction time.
Error messages include agent name and tool list for quick debugging, plus link to documentation.
Pure DX improvement; no behavior change for valid configurations.

Tests

Added ToolConstraintsTest to cover key scenarios:
single built-in (pass)
built-in + normal (fail)
two built-ins (fail)
built-in in sub-agent (fail)
all normal tools (pass)

Backward compatibility

No changes for valid setups.

Docs

Reuses existing Built-in tools documentation; no new docs added.