docs(tools): improve Tool base class documentation and validation err…

[iron-prog]

Which issue(s) does this pull-request address?

Closes: N/A

This PR does not correspond to an existing issue. It improves developer documentation and error clarity in the Tool base class.

---

Description

This PR improves readability and developer experience in the Tool base class.

Changes include:

• Added a docstring explaining the purpose and responsibilities of the Tool abstraction.
• Added a docstring to the __str__ method.
• Improved the input validation error message to include the tool name for easier debugging.

These changes do not modify runtime behavior except for improving the clarity of validation error messages.

---

Checklist

General

• I have read the appropriate contributor guide: Python
• I have signed off on my commit
• Commit messages and PR title follow conventional commits
• Appropriate label(s) added to PR: Python

Code quality checks

• Code quality checks pass: mise check

Testing

• Unit tests pass: mise test:unit
• E2E tests pass: mise test:e2e
• Tests are included (for bug fixes or new features)

Documentation

• Documentation is updated

[gemini-code-assist]

Summary of Changes

Hello, 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 improves the developer experience and clarity of the Tool base class. It introduces detailed documentation for the core Tool abstraction and its string representation, making it easier for developers to understand and implement. Furthermore, it refines the input validation error messages to be more informative by including the tool's name, which will streamline the debugging process without altering any core runtime behavior.

Highlights

• Documentation Enhancement: Added a comprehensive docstring to the Tool base class, detailing its purpose, responsibilities, and required subclass implementations.
• Method Documentation: Included a docstring for the __str__ method within the Tool class to clarify its functionality.
• Improved Error Clarity: Enhanced the input validation error message in the _validate_input method to include the specific tool's name, aiding in quicker debugging.
• Code Formatting: Applied minor code formatting adjustments across several import statements, function signatures, and method calls for improved readability and consistency.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• python/beeai_framework/tools/tool.py
  • Reformatted the import statement for beeai_framework.retryable to a multi-line format for better readability.
  • Added a detailed docstring to the Tool class, explaining its role, execution flow, and required abstract methods.
  • Included a docstring for the __str__ method to describe its return value.
  • Modified the _validate_input method to incorporate the tool's name into the ToolInputValidationError message.
  • Adjusted the formatting of several function and method signatures (_run, _generate_key, run, on_retry, get_input_schema, _run within bind_tool) to improve code layout and readability.
  • Refactored multi-line arguments in await context.emitter.emit calls and RetryableConfig initialization for enhanced visual organization.

Activity

• No specific human activity (comments, reviews, etc.) has been recorded for this pull request 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 significantly improves the developer experience by adding comprehensive docstrings to the Tool base class and its __str__ method. The improved input validation error message, which now includes the tool name, is a great addition for easier debugging. The code formatting has also been standardized across the file, enhancing readability. I have one minor suggestion to improve code style.