refactor(tools): refactor all Tools to return ToolboxError

[duwenxin99]

• Use a generic util.ProcessGcpError for GCP tools
• Use a generic util.ProcessGeneralError for all other tools.

Error categorization in Invoke():

• Query errors default to AgentError.
• Missing/malformed parameters are AgentError.
• config, ctx, logger, source fetching errors are ClientServerError.

[gemini-code-assist]

Summary of Changes

Hello @duwenxin99, 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 refactors the error handling strategy across the tools module. By introducing a new, structured ToolboxError interface and associated error types, it enables more precise categorization of errors into agent-specific issues and server-side protocol problems. This change leads to more consistent error propagation, improved mapping to HTTP and JSON-RPC status codes, and a more robust and maintainable error management system throughout the application.

Highlights

• Structured Error Handling: Introduced a new structured error hierarchy with the ToolboxError interface, AgentError, and ClientServerError types to provide more granular control over error categorization and propagation.
• Unified Tool Error Returns: All Tool.Invoke methods across the codebase now consistently return util.ToolboxError instead of a generic error, ensuring a standardized error reporting mechanism for tool executions.
• Improved HTTP Status Mapping: Refactored server-side error handling in api.go and mcp.go to intelligently map ToolboxError categories to appropriate HTTP status codes (e.g., 200 OK for agent errors, 4xx/5xx for server errors) and JSON-RPC error codes.
• Centralized GCP Error Processing: Added a ProecessGcpError utility function to convert googleapi.Error instances into ClientServerError with relevant HTTP status codes (401, 403), streamlining error handling for Google Cloud Platform interactions.
• Deprecation of Generic Unauthorized Error: The util.ErrUnauthorized variable has been removed, with all its previous usages replaced by the new ClientServerError type, providing more context and detail for authorization-related failures.

Changelog

• internal/server/api.go
  • Removed unused strings import.
  • Updated error handling in toolInvokeHandler to use errors.As with util.ClientServerError and util.ToolboxError for more precise error categorization and HTTP status code assignment.
• internal/server/common_test.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified MockTool.Invoke method signature to return util.ToolboxError.
• internal/server/mcp.go
  • Removed unused strings import.
  • Refactored error handling for jsonrpc.INVALID_REQUEST to check for util.ClientServerError codes instead of string matching.
• internal/server/mcp/v20241105/method.go
  • Removed unused strings import.
  • Replaced direct util.ErrUnauthorized returns with util.NewClientServerError.
  • Updated toolsCallHandler error logic to differentiate between CategoryAgent (returning success with IsError: true) and CategoryServer (returning JSON-RPC errors) using the new ToolboxError interface.
• internal/server/mcp/v20250326/method.go
  • Removed unused strings import.
  • Replaced direct util.ErrUnauthorized returns with util.NewClientServerError.
  • Updated toolsCallHandler error logic to differentiate between CategoryAgent (returning success with IsError: true) and CategoryServer (returning JSON-RPC errors) using the new ToolboxError interface.
• internal/server/mcp/v20250618/method.go
  • Removed unused strings import.
  • Replaced direct util.ErrUnauthorized returns with util.NewClientServerError.
  • Updated toolsCallHandler error logic to differentiate between CategoryAgent (returning success with IsError: true) and CategoryServer (returning JSON-RPC errors) using the new ToolboxError interface.
• internal/server/mcp/v20251125/method.go
  • Removed unused strings import.
  • Replaced direct util.ErrUnauthorized returns with util.NewClientServerError.
  • Updated toolsCallHandler error logic to differentiate between CategoryAgent (returning success with IsError: true) and CategoryServer (returning JSON-RPC errors) using the new ToolboxError interface.
• internal/tools/alloydb/alloydbcreatecluster/alloydbcreatecluster.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydbcreateinstance/alloydbcreateinstance.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydbcreateuser/alloydbcreateuser.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydbgetcluster/alloydbgetcluster.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydbgetinstance/alloydbgetinstance.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydbgetuser/alloydbgetuser.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydblistclusters/alloydblistclusters.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydblistinstances/alloydblistinstances.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydblistusers/alloydblistusers.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/alloydb/alloydbwaitforoperation/alloydbwaitforoperation.go
  • Added import for github.com/googleapis/genai-toolbox/internal/util.
  • Modified Invoke method signature to return util.ToolboxError.
  • Replaced fmt.Errorf for parameter validation and timeout errors with util.NewAgentError.
  • Wrapped GCP API errors with util.ProecessGcpError.
• internal/tools/bigquery/bigqueryconversationalanalytics/bigqueryconversationalanalytics.go
  • Updated authorization error handling to use util.NewClientServerError instead of wrapping util.ErrUnauthorized.
• internal/tools/tools.go
  • Added import for net/http.
  • Modified the Tool interface's Invoke method signature to return util.ToolboxError.
  • Updated AccessToken.ParseBearerToken to return util.NewClientServerError for invalid bearer tokens.
• internal/util/errors.go
  • New file added, defining the ToolboxError interface, AgentError struct (for agent-specific errors), ClientServerError struct (for server/client protocol errors), and ProecessGcpError function.
• internal/util/parameters/parameters.go
  • Added import for net/http.
  • Updated parseFromAuthService to return util.NewClientServerError for missing or invalid authentication headers.
• internal/util/util.go
  • Removed the deprecated ErrUnauthorized variable.
  • Removed unused errors import.

Activity

• The author duwenxin99 has undertaken a significant refactoring to standardize error handling across the entire tool invocation system.
• This pull request introduces a new, more robust error abstraction layer, impacting how errors are defined, returned, and processed throughout the application.
• Changes span core server logic, JSON-RPC endpoints, and individual tool implementations, indicating a comprehensive architectural improvement in error management.

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 refactors error handling across all tools by introducing the ToolboxError interface, standardizing structured error reporting and consistently applying changes across all Invoke methods. A critical systemic security issue was identified: resource ID parameters (e.g., project, location, cluster) are passed to the underlying GCP API without validation. This vulnerability allows for API path manipulation via path traversal, potentially leading to unauthorized access, especially when the toolbox uses its own service account credentials (ADC). Strict regex validation is recommended for all such parameters. Additionally, the review includes suggestions for improving parameter validation by checking for empty strings, addresses a bug in NewAgentError usage, and proposes improvements for the new ProecessGcpError function, including a typo and a recommendation for a better default error type.

[shuzhou-gc]

Sorry it is probably a naive question, but what is the rationale to have different error types tied to detailed reasons for such errors?

I imagine maybe there are automated handling based on error type? Maybe there are metrics built upon that? The trade-off, obviously, is that the developers will have to

• be familiar with all these detailed error types, or
• copy/paste what existed, or
• write their own if the meaning/reason, based on individual developers interpretation, does not already exist.

[duwenxin99]

There are only two new error types - AgentError and ClientServerError. The main rationale to distinguish between them is to return 200 OK status code for all agent errors (with error message in the response body) to allow the agent to self-correct. Therefore, detailed error message for AgentError allows LLM to understand the cause of error; for ClientServerError, it allows developers to debug more easily.
This refactor does increase the learning curve for the contributors, but I will add a more detailed guide in the documentation to make sure the categorization and expectations are clear.

[shuzhou-gc]

I see.

But interestingly, why do you want to return 200 for errors? Isn't it conventional to return 4xx-5xx for errors?

[shuzhou-gc]

And I am a little confused about the difference between those 2 errors...

Say ClientServerError is for developers, does it mean that the error cannot be resolved automatically? In the code above, the error is used in incompatible source. Is it possible to update the source type using prompt?

Another error example NewAgentError, it is used for missing password. This is cannot be resolve automatically, right?

I guess I must have missed something.

[duwenxin99]

The source type used is defined in the server configuration yaml file so that can only changed by the developers.
In this case, the password is passed in as a tool invocation parameter, then it should be an AgentError because the agent provides these params.