update alloydb agent errors

update mock tool interface
update alloydb tools error
2026-02-02 19:24:59 -05:00 · 2026-02-02 18:40:53 -05:00 · 2026-02-02 18:38:27 -05:00 · 2026-02-02 18:38:27 -05:00 · 2026-02-02 18:38:04 -05:00 · 2026-02-02 18:38:04 -05:00
45 changed files with 516 additions and 296 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,25 +1,5 @@
 # Changelog

-## [1.0.0](https://github.com/googleapis/genai-toolbox/compare/v0.26.0...v1.0.0) (2026-02-02)
-
-
-### ⚠ BREAKING CHANGES
-
-* update configuration file v2 ([#2369](https://github.com/googleapis/genai-toolbox/issues/2369))
-
-### Features
-
-* **cli/invoke:** Add support for direct tool invocation from CLI ([#2353](https://github.com/googleapis/genai-toolbox/issues/2353)) ([6e49ba4](https://github.com/googleapis/genai-toolbox/commit/6e49ba436ef2390c13feaf902b29f5907acffb57))
-* **prebuiltconfigs/alloydb-omni:** Implement Alloydb omni dataplane tools ([#2340](https://github.com/googleapis/genai-toolbox/issues/2340)) ([e995349](https://github.com/googleapis/genai-toolbox/commit/e995349ea0756c700d188b8f04e9459121219f0c))
-* **sources/cloud-logging-admin:** Add source, tools, integration test and docs ([#2137](https://github.com/googleapis/genai-toolbox/issues/2137)) ([252fc30](https://github.com/googleapis/genai-toolbox/commit/252fc3091af10d25d8d7af7e047b5ac87a5dd041))
-* Update configuration file v2 ([#2369](https://github.com/googleapis/genai-toolbox/issues/2369)) ([293c1d6](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce))
-
-
-### Bug Fixes
-
-* **dataplex:** Capture GCP HTTP errors in MCP Toolbox ([#2347](https://github.com/googleapis/genai-toolbox/issues/2347)) ([1d7c498](https://github.com/googleapis/genai-toolbox/commit/1d7c4981164c34b4d7bc8edecfd449f57ad11e15))
-* Surface Dataplex API errors in MCP results ([1d7c498](https://github.com/googleapis/genai-toolbox/commit/1d7c4981164c34b4d7bc8edecfd449f57ad11e15))
-
 ## [0.26.0](https://github.com/googleapis/genai-toolbox/compare/v0.25.0...v0.26.0) (2026-01-22)


--- a/README.md
+++ b/README.md
@@ -142,7 +142,7 @@ To install Toolbox as a binary:
 >
 > ```sh
 > # see releases page for other versions
-> export VERSION=1.0.0
+> export VERSION=0.26.0
 > curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
 > chmod +x toolbox
 > ```
@@ -155,7 +155,7 @@ To install Toolbox as a binary:
 >
 > ```sh
 > # see releases page for other versions
-> export VERSION=1.0.0
+> export VERSION=0.26.0
 > curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox
 > chmod +x toolbox
 > ```
@@ -168,7 +168,7 @@ To install Toolbox as a binary:
 >
 > ```sh
 > # see releases page for other versions
-> export VERSION=1.0.0
+> export VERSION=0.26.0
 > curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox
 > chmod +x toolbox
 > ```
@@ -181,7 +181,7 @@ To install Toolbox as a binary:
 >
 > ```cmd
 > :: see releases page for other versions
-> set VERSION=1.0.0
+> set VERSION=0.26.0
 > curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe"
 > ```
 >
@@ -193,7 +193,7 @@ To install Toolbox as a binary:
 >
 > ```powershell
 > # see releases page for other versions
-> $VERSION = "1.0.0"
+> $VERSION = "0.26.0"
 > curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe"
 > ```
 >
@@ -206,7 +206,7 @@ You can also install Toolbox as a container:

 ```sh
 # see releases page for other versions
-export VERSION=1.0.0
+export VERSION=0.26.0
 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
 ```

@@ -230,7 +230,7 @@ To install from source, ensure you have the latest version of
 [Go installed](https://go.dev/doc/install), and then run the following command:

 ```sh
-go install github.com/googleapis/genai-toolbox@v1.0.0
+go install github.com/googleapis/genai-toolbox@v0.26.0
 ```
 <!-- {x-release-please-end} -->

--- a/cmd/version.txt
+++ b/cmd/version.txt
@@ -1 +1 @@
-1.0.0
+0.26.0
--- a/docs/en/getting-started/colab_quickstart.ipynb
+++ b/docs/en/getting-started/colab_quickstart.ipynb
@@ -234,7 +234,7 @@
      },
      "outputs": [],
      "source": [
-        "version = \"1.0.0\" # x-release-please-version\n",
+        "version = \"0.26.0\" # x-release-please-version\n",
        "! curl -O https://storage.googleapis.com/genai-toolbox/v{version}/linux/amd64/toolbox\n",
        "\n",
        "# Make the binary executable\n",
--- a/docs/en/getting-started/introduction/_index.md
+++ b/docs/en/getting-started/introduction/_index.md
@@ -109,7 +109,7 @@ To install Toolbox as a binary on Linux (AMD64):

 ```sh
 # see releases page for other versions
-export VERSION=1.0.0
+export VERSION=0.26.0
 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
 chmod +x toolbox
 ```
@@ -120,7 +120,7 @@ To install Toolbox as a binary on macOS (Apple Silicon):

 ```sh
 # see releases page for other versions
-export VERSION=1.0.0
+export VERSION=0.26.0
 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox
 chmod +x toolbox
 ```
@@ -131,7 +131,7 @@ To install Toolbox as a binary on macOS (Intel):

 ```sh
 # see releases page for other versions
-export VERSION=1.0.0
+export VERSION=0.26.0
 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox
 chmod +x toolbox
 ```
@@ -142,7 +142,7 @@ To install Toolbox as a binary on Windows (Command Prompt):

 ```cmd
 :: see releases page for other versions
-set VERSION=1.0.0
+set VERSION=0.26.0
 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe"
 ```

@@ -152,7 +152,7 @@ To install Toolbox as a binary on Windows (PowerShell):

 ```powershell
 # see releases page for other versions
-$VERSION = "1.0.0"
+$VERSION = "0.26.0"
 curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe"
 ```

@@ -164,7 +164,7 @@ You can also install Toolbox as a container:

 ```sh
 # see releases page for other versions
-export VERSION=1.0.0
+export VERSION=0.26.0
 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION
 ```

@@ -183,7 +183,7 @@ To install from source, ensure you have the latest version of
 [Go installed](https://go.dev/doc/install), and then run the following command:

 ```sh
-go install github.com/googleapis/genai-toolbox@v1.0.0
+go install github.com/googleapis/genai-toolbox@v0.26.0
 ```

 {{% /tab %}}
--- a/docs/en/getting-started/mcp_quickstart/_index.md
+++ b/docs/en/getting-started/mcp_quickstart/_index.md
@@ -105,7 +105,7 @@ In this section, we will download Toolbox, configure our tools in a
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/docs/en/getting-started/quickstart/shared/configure_toolbox.md
+++ b/docs/en/getting-started/quickstart/shared/configure_toolbox.md
@@ -13,7 +13,7 @@ In this section, we will download Toolbox, configure our tools in a
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/docs/en/how-to/connect-ide/looker_mcp.md
+++ b/docs/en/how-to/connect-ide/looker_mcp.md
@@ -100,19 +100,19 @@ After you install Looker in the MCP Store, resources and tools from the server a

 {{< tabpane persist=header >}}
 {{< tab header="linux/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/linux/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/arm64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/arm64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox
 {{< /tab >}}

 {{< tab header="windows/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/windows/amd64/toolbox.exe
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe
 {{< /tab >}}
 {{< /tabpane >}}
    <!-- {x-release-please-end} -->
--- a/docs/en/how-to/connect-ide/mssql_mcp.md
+++ b/docs/en/how-to/connect-ide/mssql_mcp.md
@@ -45,19 +45,19 @@ instance:
   <!-- {x-release-please-start-version} -->
   {{< tabpane persist=header >}}
 {{< tab header="linux/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/linux/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/arm64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/arm64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox
 {{< /tab >}}

 {{< tab header="windows/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/windows/amd64/toolbox.exe
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe
 {{< /tab >}}
 {{< /tabpane >}}
    <!-- {x-release-please-end} -->
--- a/docs/en/how-to/connect-ide/mysql_mcp.md
+++ b/docs/en/how-to/connect-ide/mysql_mcp.md
@@ -43,19 +43,19 @@ expose your developer assistant tools to a MySQL instance:
   <!-- {x-release-please-start-version} -->
   {{< tabpane persist=header >}}
 {{< tab header="linux/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/linux/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/arm64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/arm64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox
 {{< /tab >}}

 {{< tab header="windows/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/windows/amd64/toolbox.exe
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe
 {{< /tab >}}
 {{< /tabpane >}}
    <!-- {x-release-please-end} -->
--- a/docs/en/how-to/connect-ide/neo4j_mcp.md
+++ b/docs/en/how-to/connect-ide/neo4j_mcp.md
@@ -44,19 +44,19 @@ expose your developer assistant tools to a Neo4j instance:
   <!-- {x-release-please-start-version} -->
   {{< tabpane persist=header >}}
 {{< tab header="linux/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/linux/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/arm64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/arm64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox
 {{< /tab >}}

 {{< tab header="windows/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/windows/amd64/toolbox.exe
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe
 {{< /tab >}}
 {{< /tabpane >}}
    <!-- {x-release-please-end} -->
--- a/docs/en/how-to/connect-ide/postgres_mcp.md
+++ b/docs/en/how-to/connect-ide/postgres_mcp.md
@@ -56,19 +56,19 @@ Omni](https://cloud.google.com/alloydb/omni/current/docs/overview).
   <!-- {x-release-please-start-version} -->
   {{< tabpane persist=header >}}
 {{< tab header="linux/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/linux/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/arm64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/arm64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox
 {{< /tab >}}

 {{< tab header="windows/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/windows/amd64/toolbox.exe
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe
 {{< /tab >}}
 {{< /tabpane >}}
    <!-- {x-release-please-end} -->
--- a/docs/en/how-to/connect-ide/sqlite_mcp.md
+++ b/docs/en/how-to/connect-ide/sqlite_mcp.md
@@ -43,19 +43,19 @@ to expose your developer assistant tools to a SQLite instance:
   <!-- {x-release-please-start-version} -->
   {{< tabpane persist=header >}}
 {{< tab header="linux/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/linux/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/arm64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/arm64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox
 {{< /tab >}}

 {{< tab header="darwin/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/darwin/amd64/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox
 {{< /tab >}}

 {{< tab header="windows/amd64" lang="bash" >}}
-curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/windows/amd64/toolbox.exe
+curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe
 {{< /tab >}}
 {{< /tabpane >}}
    <!-- {x-release-please-end} -->
--- a/docs/en/samples/alloydb/ai-nl/alloydb_ai_nl.ipynb
+++ b/docs/en/samples/alloydb/ai-nl/alloydb_ai_nl.ipynb
@@ -771,7 +771,7 @@
      },
      "outputs": [],
      "source": [
-        "version = \"1.0.0\" # x-release-please-version\n",
+        "version = \"0.26.0\" # x-release-please-version\n",
        "! curl -L -o /content/toolbox https://storage.googleapis.com/genai-toolbox/v{version}/linux/amd64/toolbox\n",
        "\n",
        "# Make the binary executable\n",
--- a/docs/en/samples/alloydb/mcp_quickstart.md
+++ b/docs/en/samples/alloydb/mcp_quickstart.md
@@ -123,7 +123,7 @@ In this section, we will download and install the Toolbox binary.
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    export VERSION="1.0.0"
+    export VERSION="0.26.0"
    curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->
--- a/docs/en/samples/bigquery/colab_quickstart_bigquery.ipynb
+++ b/docs/en/samples/bigquery/colab_quickstart_bigquery.ipynb
@@ -220,7 +220,7 @@
      },
      "outputs": [],
      "source": [
-        "version = \"1.0.0\" # x-release-please-version\n",
+        "version = \"0.26.0\" # x-release-please-version\n",
        "! curl -O https://storage.googleapis.com/genai-toolbox/v{version}/linux/amd64/toolbox\n",
        "\n",
        "# Make the binary executable\n",
--- a/docs/en/samples/bigquery/local_quickstart.md
+++ b/docs/en/samples/bigquery/local_quickstart.md
@@ -179,7 +179,7 @@ to use BigQuery, and then run the Toolbox server.
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/docs/en/samples/bigquery/mcp_quickstart/_index.md
+++ b/docs/en/samples/bigquery/mcp_quickstart/_index.md
@@ -98,7 +98,7 @@ In this section, we will download Toolbox, configure our tools in a
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/docs/en/samples/looker/looker_gemini.md
+++ b/docs/en/samples/looker/looker_gemini.md
@@ -34,7 +34,7 @@ In this section, we will download Toolbox and run the Toolbox server.
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/docs/en/samples/looker/looker_gemini_oauth/_index.md
+++ b/docs/en/samples/looker/looker_gemini_oauth/_index.md
@@ -48,7 +48,7 @@ In this section, we will download Toolbox and run the Toolbox server.
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/docs/en/samples/looker/looker_mcp_inspector/_index.md
+++ b/docs/en/samples/looker/looker_mcp_inspector/_index.md
@@ -34,7 +34,7 @@ In this section, we will download Toolbox and run the Toolbox server.
    <!-- {x-release-please-start-version} -->
    ```bash
    export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-    curl -O https://storage.googleapis.com/genai-toolbox/v1.0.0/$OS/toolbox
+    curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox
    ```
    <!-- {x-release-please-end} -->

--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
 {
  "name": "mcp-toolbox-for-databases",
-  "version": "1.0.0",
+  "version": "0.26.0",
  "description": "MCP Toolbox for Databases is an open-source MCP server for more than 30 different datasources.",
  "contextFileName": "MCP-TOOLBOX-EXTENSION.md"
 }
--- a/internal/server/api.go
+++ b/internal/server/api.go
@@ -19,7 +19,6 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
-	"strings"

 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
@@ -235,8 +234,10 @@ func toolInvokeHandler(s *Server, w http.ResponseWriter, r *http.Request) {
 	params, err := parameters.ParseParams(tool.GetParameters(), data, claimsFromAuth)
 	if err != nil {
 		// If auth error, return 401
-		if errors.Is(err, util.ErrUnauthorized) {
-			s.logger.DebugContext(ctx, fmt.Sprintf("error parsing authenticated parameters from ID token: %s", err))
+		errMsg := fmt.Sprintf("error parsing authenticated parameters from ID token: %w", err)
+		var clientServerErr *util.ClientServerError
+		if errors.As(err, &clientServerErr) && clientServerErr.Code == http.StatusUnauthorized {
+			s.logger.DebugContext(ctx, errMsg)
 			_ = render.Render(w, r, newErrResponse(err, http.StatusUnauthorized))
 			return
 		}
@@ -259,34 +260,49 @@ func toolInvokeHandler(s *Server, w http.ResponseWriter, r *http.Request) {

 	// Determine what error to return to the users.
 	if err != nil {
-		errStr := err.Error()
-		var statusCode int
+		var tbErr util.ToolboxError

-		// Upstream API auth error propagation
-		switch {
-		case strings.Contains(errStr, "Error 401"):
-			statusCode = http.StatusUnauthorized
-		case strings.Contains(errStr, "Error 403"):
-			statusCode = http.StatusForbidden
-		}
+		if errors.As(err, &tbErr) {
+			switch tbErr.Category() {
+			case util.CategoryAgent:
+				// Agent Errors -> 200 OK
+				s.logger.DebugContext(ctx, fmt.Sprintf("Tool invocation agent error: %v", err))
+				_ = render.Render(w, r, newErrResponse(err, http.StatusOK))
+				return

-		if statusCode == http.StatusUnauthorized || statusCode == http.StatusForbidden {
-			if clientAuth {
-				// Propagate the original 401/403 error.
-				s.logger.DebugContext(ctx, fmt.Sprintf("error invoking tool. Client credentials lack authorization to the source: %v", err))
+			case util.CategoryServer:
+				// Server Errors -> Check the specific code inside
+				var clientServerErr *util.ClientServerError
+				statusCode := http.StatusInternalServerError // Default to 500
+
+				if errors.As(err, &clientServerErr) {
+					if clientServerErr.Code != 0 {
+						statusCode = clientServerErr.Code
+					}
+				}
+
+				// Process auth error
+				if statusCode == http.StatusUnauthorized || statusCode == http.StatusForbidden {
+					if clientAuth {
+						// Token error, pass through 401/403
+						s.logger.DebugContext(ctx, fmt.Sprintf("Client credentials lack authorization: %v", err))
+						_ = render.Render(w, r, newErrResponse(err, statusCode))
+						return
+					}
+					// ADC/Config error, return 500
+					statusCode = http.StatusInternalServerError
+				}
+
+				s.logger.ErrorContext(ctx, fmt.Sprintf("Tool invocation server error: %v", err))
 				_ = render.Render(w, r, newErrResponse(err, statusCode))
 				return
 			}
-			// ADC lacking permission or credentials configuration error.
-			internalErr := fmt.Errorf("unexpected auth error occured during Tool invocation: %w", err)
-			s.logger.ErrorContext(ctx, internalErr.Error())
-			_ = render.Render(w, r, newErrResponse(internalErr, http.StatusInternalServerError))
+		} else {
+			// Unknown error -> 500
+			s.logger.ErrorContext(ctx, fmt.Sprintf("Tool invocation unknown error: %v", err))
+			_ = render.Render(w, r, newErrResponse(err, http.StatusInternalServerError))
 			return
 		}
-		err = fmt.Errorf("error while invoking tool: %w", err)
-		s.logger.DebugContext(ctx, err.Error())
-		_ = render.Render(w, r, newErrResponse(err, http.StatusBadRequest))
-		return
 	}

 	resMarshal, err := json.Marshal(res)
--- a/internal/server/common_test.go
+++ b/internal/server/common_test.go
@@ -30,6 +30,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/server/resources"
 	"github.com/googleapis/genai-toolbox/internal/telemetry"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -51,7 +52,7 @@ type MockTool struct {
 	requiresClientAuthrorization bool
 }

-func (t MockTool) Invoke(context.Context, tools.SourceProvider, parameters.ParamValues, tools.AccessToken) (any, error) {
+func (t MockTool) Invoke(context.Context, tools.SourceProvider, parameters.ParamValues, tools.AccessToken) (any, util.ToolboxError) {
 	mock := []any{t.Name}
 	return mock, nil
 }
--- a/internal/server/mcp.go
+++ b/internal/server/mcp.go
@@ -23,7 +23,6 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"strings"
 	"sync"
 	"time"

@@ -444,15 +443,17 @@ func httpHandler(s *Server, w http.ResponseWriter, r *http.Request) {
 		code := rpcResponse.Error.Code
 		switch code {
 		case jsonrpc.INTERNAL_ERROR:
+			// Map Internal RPC Error (-32603) to HTTP 500
 			w.WriteHeader(http.StatusInternalServerError)
 		case jsonrpc.INVALID_REQUEST:
-			errStr := err.Error()
-			if errors.Is(err, util.ErrUnauthorized) {
-				w.WriteHeader(http.StatusUnauthorized)
-			} else if strings.Contains(errStr, "Error 401") {
-				w.WriteHeader(http.StatusUnauthorized)
-			} else if strings.Contains(errStr, "Error 403") {
-				w.WriteHeader(http.StatusForbidden)
+			var clientServerErr *util.ClientServerError
+			if errors.As(err, &clientServerErr) {
+				switch clientServerErr.Code {
+				case http.StatusUnauthorized:
+					w.WriteHeader(http.StatusUnauthorized)
+				case http.StatusForbidden:
+					w.WriteHeader(http.StatusForbidden)
+				}
 			}
 		}
 	}
--- a/internal/server/mcp/v20241105/method.go
+++ b/internal/server/mcp/v20241105/method.go
@@ -21,7 +21,6 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
-	"strings"

 	"github.com/googleapis/genai-toolbox/internal/prompts"
 	"github.com/googleapis/genai-toolbox/internal/server/mcp/jsonrpc"
@@ -124,7 +123,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	}
 	if clientAuth {
 		if accessToken == "" {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.ErrUnauthorized
+			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.NewClientServerError(
+				"missing access token in the 'Authorization' header",
+				http.StatusUnauthorized,
+				nil,
+			)
 		}
 	}

@@ -172,7 +175,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// Check if any of the specified auth services is verified
 	isAuthorized := tool.Authorized(verifiedAuthServices)
 	if !isAuthorized {
-		err = fmt.Errorf("unauthorized Tool call: Please make sure your specify correct auth headers: %w", util.ErrUnauthorized)
+		err = util.NewClientServerError(
+			"unauthorized Tool call: Please make sure you specify correct auth headers",
+			http.StatusUnauthorized,
+			nil,
+		)
 		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
 	}
 	logger.DebugContext(ctx, "tool invocation authorized")
@@ -194,30 +201,44 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// run tool invocation and generate response.
 	results, err := tool.Invoke(ctx, resourceMgr, params, accessToken)
 	if err != nil {
-		errStr := err.Error()
-		// Missing authService tokens.
-		if errors.Is(err, util.ErrUnauthorized) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
-		}
-		// Upstream auth error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
-			if clientAuth {
-				// Error with client credentials should pass down to the client
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+		var tbErr util.ToolboxError
+
+		if errors.As(err, &tbErr) {
+			switch tbErr.Category() {
+			case util.CategoryAgent:
+				// MCP - Tool execution error
+				// Return SUCCESS but with IsError: true
+				text := TextContent{
+					Type: "text",
+					Text: err.Error(),
+				}
+				return jsonrpc.JSONRPCResponse{
+					Jsonrpc: jsonrpc.JSONRPC_VERSION,
+					Id:      id,
+					Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
+				}, nil
+
+			case util.CategoryServer:
+				// MCP Spec - Protocol error
+				// Return JSON-RPC ERROR
+				var clientServerErr *util.ClientServerError
+				rpcCode := jsonrpc.INTERNAL_ERROR // Default to Internal Error (-32603)
+
+				if errors.As(err, &clientServerErr) {
+					if clientServerErr.Code == http.StatusUnauthorized || clientServerErr.Code == http.StatusForbidden {
+						if clientAuth {
+							rpcCode = jsonrpc.INVALID_REQUEST
+						} else {
+							rpcCode = jsonrpc.INTERNAL_ERROR
+						}
+					}
+				}
+				return jsonrpc.NewError(id, rpcCode, err.Error(), nil), err
 			}
-			// Auth error with ADC should raise internal 500 error
+		} else {
+			// Unknown error -> 500
 			return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
 		}
-
-		text := TextContent{
-			Type: "text",
-			Text: err.Error(),
-		}
-		return jsonrpc.JSONRPCResponse{
-			Jsonrpc: jsonrpc.JSONRPC_VERSION,
-			Id:      id,
-			Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
-		}, nil
 	}

 	content := make([]TextContent, 0)
--- a/internal/server/mcp/v20250326/method.go
+++ b/internal/server/mcp/v20250326/method.go
@@ -21,7 +21,6 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
-	"strings"

 	"github.com/googleapis/genai-toolbox/internal/prompts"
 	"github.com/googleapis/genai-toolbox/internal/server/mcp/jsonrpc"
@@ -124,7 +123,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	}
 	if clientAuth {
 		if accessToken == "" {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.ErrUnauthorized
+			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.NewClientServerError(
+				"missing access token in the 'Authorization' header",
+				http.StatusUnauthorized,
+				nil,
+			)
 		}
 	}

@@ -172,7 +175,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// Check if any of the specified auth services is verified
 	isAuthorized := tool.Authorized(verifiedAuthServices)
 	if !isAuthorized {
-		err = fmt.Errorf("unauthorized Tool call: Please make sure your specify correct auth headers: %w", util.ErrUnauthorized)
+		err = util.NewClientServerError(
+			"unauthorized Tool call: Please make sure you specify correct auth headers",
+			http.StatusUnauthorized,
+			nil,
+		)
 		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
 	}
 	logger.DebugContext(ctx, "tool invocation authorized")
@@ -194,31 +201,45 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// run tool invocation and generate response.
 	results, err := tool.Invoke(ctx, resourceMgr, params, accessToken)
 	if err != nil {
-		errStr := err.Error()
-		// Missing authService tokens.
-		if errors.Is(err, util.ErrUnauthorized) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
-		}
-		// Upstream auth error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
-			if clientAuth {
-				// Error with client credentials should pass down to the client
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+		var tbErr util.ToolboxError
+
+		if errors.As(err, &tbErr) {
+			switch tbErr.Category() {
+			case util.CategoryAgent:
+				// MCP - Tool execution error
+				// Return SUCCESS but with IsError: true
+				text := TextContent{
+					Type: "text",
+					Text: err.Error(),
+				}
+				return jsonrpc.JSONRPCResponse{
+					Jsonrpc: jsonrpc.JSONRPC_VERSION,
+					Id:      id,
+					Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
+				}, nil
+
+			case util.CategoryServer:
+				// MCP Spec - Protocol error
+				// Return JSON-RPC ERROR
+				var clientServerErr *util.ClientServerError
+				rpcCode := jsonrpc.INTERNAL_ERROR // Default to Internal Error (-32603)
+
+				if errors.As(err, &clientServerErr) {
+					if clientServerErr.Code == http.StatusUnauthorized || clientServerErr.Code == http.StatusForbidden {
+						if clientAuth {
+							rpcCode = jsonrpc.INVALID_REQUEST
+						} else {
+							rpcCode = jsonrpc.INTERNAL_ERROR
+						}
+					}
+				}
+				return jsonrpc.NewError(id, rpcCode, err.Error(), nil), err
 			}
-			// Auth error with ADC should raise internal 500 error
+		} else {
+			// Unknown error -> 500
 			return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
 		}
-		text := TextContent{
-			Type: "text",
-			Text: err.Error(),
-		}
-		return jsonrpc.JSONRPCResponse{
-			Jsonrpc: jsonrpc.JSONRPC_VERSION,
-			Id:      id,
-			Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
-		}, nil
 	}
-
 	content := make([]TextContent, 0)

 	sliceRes, ok := results.([]any)
--- a/internal/server/mcp/v20250618/method.go
+++ b/internal/server/mcp/v20250618/method.go
@@ -21,7 +21,6 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
-	"strings"

 	"github.com/googleapis/genai-toolbox/internal/prompts"
 	"github.com/googleapis/genai-toolbox/internal/server/mcp/jsonrpc"
@@ -117,7 +116,12 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	}
 	if clientAuth {
 		if accessToken == "" {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.ErrUnauthorized
+			errMsg := "missing access token in the 'Authorization' header"
+			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, errMsg, nil), util.NewClientServerError(
+				errMsg,
+				http.StatusUnauthorized,
+				nil,
+			)
 		}
 	}

@@ -165,7 +169,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// Check if any of the specified auth services is verified
 	isAuthorized := tool.Authorized(verifiedAuthServices)
 	if !isAuthorized {
-		err = fmt.Errorf("unauthorized Tool call: Please make sure your specify correct auth headers: %w", util.ErrUnauthorized)
+		err = util.NewClientServerError(
+			"unauthorized Tool call: Please make sure you specify correct auth headers",
+			http.StatusUnauthorized,
+			nil,
+		)
 		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
 	}
 	logger.DebugContext(ctx, "tool invocation authorized")
@@ -187,29 +195,44 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// run tool invocation and generate response.
 	results, err := tool.Invoke(ctx, resourceMgr, params, accessToken)
 	if err != nil {
-		errStr := err.Error()
-		// Missing authService tokens.
-		if errors.Is(err, util.ErrUnauthorized) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
-		}
-		// Upstream auth error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
-			if clientAuth {
-				// Error with client credentials should pass down to the client
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+		var tbErr util.ToolboxError
+
+		if errors.As(err, &tbErr) {
+			switch tbErr.Category() {
+			case util.CategoryAgent:
+				// MCP - Tool execution error
+				// Return SUCCESS but with IsError: true
+				text := TextContent{
+					Type: "text",
+					Text: err.Error(),
+				}
+				return jsonrpc.JSONRPCResponse{
+					Jsonrpc: jsonrpc.JSONRPC_VERSION,
+					Id:      id,
+					Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
+				}, nil
+
+			case util.CategoryServer:
+				// MCP Spec - Protocol error
+				// Return JSON-RPC ERROR
+				var clientServerErr *util.ClientServerError
+				rpcCode := jsonrpc.INTERNAL_ERROR // Default to Internal Error (-32603)
+
+				if errors.As(err, &clientServerErr) {
+					if clientServerErr.Code == http.StatusUnauthorized || clientServerErr.Code == http.StatusForbidden {
+						if clientAuth {
+							rpcCode = jsonrpc.INVALID_REQUEST
+						} else {
+							rpcCode = jsonrpc.INTERNAL_ERROR
+						}
+					}
+				}
+				return jsonrpc.NewError(id, rpcCode, err.Error(), nil), err
 			}
-			// Auth error with ADC should raise internal 500 error
+		} else {
+			// Unknown error -> 500
 			return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
 		}
-		text := TextContent{
-			Type: "text",
-			Text: err.Error(),
-		}
-		return jsonrpc.JSONRPCResponse{
-			Jsonrpc: jsonrpc.JSONRPC_VERSION,
-			Id:      id,
-			Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
-		}, nil
 	}

 	content := make([]TextContent, 0)
--- a/internal/server/mcp/v20251125/method.go
+++ b/internal/server/mcp/v20251125/method.go
@@ -21,7 +21,6 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
-	"strings"

 	"github.com/googleapis/genai-toolbox/internal/prompts"
 	"github.com/googleapis/genai-toolbox/internal/server/mcp/jsonrpc"
@@ -117,7 +116,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	}
 	if clientAuth {
 		if accessToken == "" {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.ErrUnauthorized
+			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, "missing access token in the 'Authorization' header", nil), util.NewClientServerError(
+				"missing access token in the 'Authorization' header",
+				http.StatusUnauthorized,
+				nil,
+			)
 		}
 	}

@@ -165,7 +168,11 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// Check if any of the specified auth services is verified
 	isAuthorized := tool.Authorized(verifiedAuthServices)
 	if !isAuthorized {
-		err = fmt.Errorf("unauthorized Tool call: Please make sure your specify correct auth headers: %w", util.ErrUnauthorized)
+		err = util.NewClientServerError(
+			"unauthorized Tool call: Please make sure you specify correct auth headers",
+			http.StatusUnauthorized,
+			nil,
+		)
 		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
 	}
 	logger.DebugContext(ctx, "tool invocation authorized")
@@ -187,29 +194,44 @@ func toolsCallHandler(ctx context.Context, id jsonrpc.RequestId, resourceMgr *re
 	// run tool invocation and generate response.
 	results, err := tool.Invoke(ctx, resourceMgr, params, accessToken)
 	if err != nil {
-		errStr := err.Error()
-		// Missing authService tokens.
-		if errors.Is(err, util.ErrUnauthorized) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
-		}
-		// Upstream auth error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
-			if clientAuth {
-				// Error with client credentials should pass down to the client
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+		var tbErr util.ToolboxError
+
+		if errors.As(err, &tbErr) {
+			switch tbErr.Category() {
+			case util.CategoryAgent:
+				// MCP - Tool execution error
+				// Return SUCCESS but with IsError: true
+				text := TextContent{
+					Type: "text",
+					Text: err.Error(),
+				}
+				return jsonrpc.JSONRPCResponse{
+					Jsonrpc: jsonrpc.JSONRPC_VERSION,
+					Id:      id,
+					Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
+				}, nil
+
+			case util.CategoryServer:
+				// MCP Spec - Protocol error
+				// Return JSON-RPC ERROR
+				var clientServerErr *util.ClientServerError
+				rpcCode := jsonrpc.INTERNAL_ERROR // Default to Internal Error (-32603)
+
+				if errors.As(err, &clientServerErr) {
+					if clientServerErr.Code == http.StatusUnauthorized || clientServerErr.Code == http.StatusForbidden {
+						if clientAuth {
+							rpcCode = jsonrpc.INVALID_REQUEST
+						} else {
+							rpcCode = jsonrpc.INTERNAL_ERROR
+						}
+					}
+				}
+				return jsonrpc.NewError(id, rpcCode, err.Error(), nil), err
 			}
-			// Auth error with ADC should raise internal 500 error
+		} else {
+			// Unknown error -> 500
 			return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
 		}
-		text := TextContent{
-			Type: "text",
-			Text: err.Error(),
-		}
-		return jsonrpc.JSONRPCResponse{
-			Jsonrpc: jsonrpc.JSONRPC_VERSION,
-			Id:      id,
-			Result:  CallToolResult{Content: []TextContent{text}, IsError: true},
-		}, nil
 	}

 	content := make([]TextContent, 0)
--- a/internal/tools/alloydb/alloydbcreatecluster/alloydbcreatecluster.go
+++ b/internal/tools/alloydb/alloydbcreatecluster/alloydbcreatecluster.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -122,44 +123,49 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()
 	project, ok := paramsMap["project"].(string)
 	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a non-empty string", nil)
 	}

 	location, ok := paramsMap["location"].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid 'location' parameter; expected a string", nil)
 	}

 	clusterID, ok := paramsMap["cluster"].(string)
 	if !ok || clusterID == "" {
-		return nil, fmt.Errorf("invalid or missing 'cluster' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a non-empty string", nil)
 	}

 	password, ok := paramsMap["password"].(string)
 	if !ok || password == "" {
-		return nil, fmt.Errorf("invalid or missing 'password' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'password' parameter; expected a non-empty string", nil)
 	}

 	network, ok := paramsMap["network"].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid 'network' parameter; expected a string")
+		return nil, util.NewAgentError("invalid 'network' parameter; expected a string", nil)
 	}

 	user, ok := paramsMap["user"].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid 'user' parameter; expected a string")
+		return nil, util.NewAgentError("invalid 'user' parameter; expected a string", nil)
+	}
+	resp, err := source.CreateCluster(ctx, project, location, network, user, password, clusterID, string(accessToken))
+
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
 	}

-	return source.CreateCluster(ctx, project, location, network, user, password, clusterID, string(accessToken))
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydbcreateinstance/alloydbcreateinstance.go
+++ b/internal/tools/alloydb/alloydbcreateinstance/alloydbcreateinstance.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -123,36 +124,36 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()
 	project, ok := paramsMap["project"].(string)
 	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a non-empty string", nil)
 	}

 	location, ok := paramsMap["location"].(string)
 	if !ok || location == "" {
-		return nil, fmt.Errorf("invalid or missing 'location' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a non-empty string", nil)
 	}

 	cluster, ok := paramsMap["cluster"].(string)
 	if !ok || cluster == "" {
-		return nil, fmt.Errorf("invalid or missing 'cluster' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a non-empty string", nil)
 	}

 	instanceID, ok := paramsMap["instance"].(string)
 	if !ok || instanceID == "" {
-		return nil, fmt.Errorf("invalid or missing 'instance' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'instance' parameter; expected a non-empty string", nil)
 	}

 	instanceType, ok := paramsMap["instanceType"].(string)
 	if !ok || (instanceType != "READ_POOL" && instanceType != "PRIMARY") {
-		return nil, fmt.Errorf("invalid 'instanceType' parameter; expected 'PRIMARY' or 'READ_POOL'")
+		return nil, util.NewAgentError("invalid 'instanceType' parameter; expected 'PRIMARY' or 'READ_POOL'", nil)
 	}

 	displayName, _ := paramsMap["displayName"].(string)
@@ -161,11 +162,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if instanceType == "READ_POOL" {
 		nodeCount, ok = paramsMap["nodeCount"].(int)
 		if !ok {
-			return nil, fmt.Errorf("invalid 'nodeCount' parameter; expected an integer for READ_POOL")
+			return nil, util.NewAgentError("invalid 'nodeCount' parameter; expected an integer for READ_POOL", nil)
 		}
 	}

-	return source.CreateInstance(ctx, project, location, cluster, instanceID, instanceType, displayName, nodeCount, string(accessToken))
+	resp, err := source.CreateInstance(ctx, project, location, cluster, instanceID, instanceType, displayName, nodeCount, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydbcreateuser/alloydbcreateuser.go
+++ b/internal/tools/alloydb/alloydbcreateuser/alloydbcreateuser.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -122,43 +123,43 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()
 	project, ok := paramsMap["project"].(string)
 	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a non-empty string", nil)
 	}

 	location, ok := paramsMap["location"].(string)
 	if !ok || location == "" {
-		return nil, fmt.Errorf("invalid or missing'location' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing'location' parameter; expected a non-empty string", nil)
 	}

 	cluster, ok := paramsMap["cluster"].(string)
 	if !ok || cluster == "" {
-		return nil, fmt.Errorf("invalid or missing 'cluster' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a non-empty string", nil)
 	}

 	userID, ok := paramsMap["user"].(string)
 	if !ok || userID == "" {
-		return nil, fmt.Errorf("invalid or missing 'user' parameter; expected a non-empty string")
+		return nil, util.NewAgentError("invalid or missing 'user' parameter; expected a non-empty string", nil)
 	}

 	userType, ok := paramsMap["userType"].(string)
 	if !ok || (userType != "ALLOYDB_BUILT_IN" && userType != "ALLOYDB_IAM_USER") {
-		return nil, fmt.Errorf("invalid or missing 'userType' parameter; expected 'ALLOYDB_BUILT_IN' or 'ALLOYDB_IAM_USER'")
+		return nil, util.NewAgentError("invalid or missing 'userType' parameter; expected 'ALLOYDB_BUILT_IN' or 'ALLOYDB_IAM_USER'", nil)
 	}
 	var password string

 	if userType == "ALLOYDB_BUILT_IN" {
 		password, ok = paramsMap["password"].(string)
 		if !ok || password == "" {
-			return nil, fmt.Errorf("password is required when userType is ALLOYDB_BUILT_IN")
+			return nil, util.NewAgentError("password is required when userType is ALLOYDB_BUILT_IN", nil)
 		}
 	}

@@ -170,7 +171,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			}
 		}
 	}
-	return source.CreateUser(ctx, userType, password, roles, string(accessToken), project, location, cluster, userID)
+	resp, err := source.CreateUser(ctx, userType, password, roles, string(accessToken), project, location, cluster, userID)
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydbgetcluster/alloydbgetcluster.go
+++ b/internal/tools/alloydb/alloydbgetcluster/alloydbgetcluster.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -120,28 +121,32 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+	if !ok || project == "" {
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+	if !ok || location == "" {
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+	if !ok || cluster == "" {
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a string", nil)
 	}

-	return source.GetCluster(ctx, project, location, cluster, string(accessToken))
+	resp, err := source.GetCluster(ctx, project, location, cluster, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydbgetinstance/alloydbgetinstance.go
+++ b/internal/tools/alloydb/alloydbgetinstance/alloydbgetinstance.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -120,32 +121,36 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+	if !ok || project == "" {
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+	if !ok || location == "" {
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+	if !ok || cluster == "" {
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a string", nil)
 	}
 	instance, ok := paramsMap["instance"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'instance' parameter; expected a string")
+	if !ok || instance == "" {
+		return nil, util.NewAgentError("invalid or missing 'instance' parameter; expected a string", nil)
 	}

-	return source.GetInstance(ctx, project, location, cluster, instance, string(accessToken))
+	resp, err := source.GetInstance(ctx, project, location, cluster, instance, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydbgetuser/alloydbgetuser.go
+++ b/internal/tools/alloydb/alloydbgetuser/alloydbgetuser.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -120,32 +121,36 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+	if !ok || project == "" {
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+	if !ok || location == "" {
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+	if !ok || cluster == "" {
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a string", nil)
 	}
 	user, ok := paramsMap["user"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'user' parameter; expected a string")
+	if !ok || user == "" {
+		return nil, util.NewAgentError("invalid or missing 'user' parameter; expected a string", nil)
 	}

-	return source.GetUsers(ctx, project, location, cluster, user, string(accessToken))
+	resp, err := source.GetUsers(ctx, project, location, cluster, user, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydblistclusters/alloydblistclusters.go
+++ b/internal/tools/alloydb/alloydblistclusters/alloydblistclusters.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -118,24 +119,28 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+	if !ok || project == "" {
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid 'location' parameter; expected a string", nil)
 	}

-	return source.ListCluster(ctx, project, location, string(accessToken))
+	resp, err := source.ListCluster(ctx, project, location, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydblistinstances/alloydblistinstances.go
+++ b/internal/tools/alloydb/alloydblistinstances/alloydblistinstances.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -119,28 +120,32 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+	if !ok || project == "" {
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+		return nil, util.NewAgentError("invalid 'cluster' parameter; expected a string", nil)
 	}

-	return source.ListInstance(ctx, project, location, cluster, string(accessToken))
+	resp, err := source.ListInstance(ctx, project, location, cluster, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydblistusers/alloydblistusers.go
+++ b/internal/tools/alloydb/alloydblistusers/alloydblistusers.go
@@ -22,6 +22,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -119,28 +120,32 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+	if !ok || project == "" {
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+	if !ok || location == "" {
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+	if !ok || cluster == "" {
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a string", nil)
 	}

-	return source.ListUsers(ctx, project, location, cluster, string(accessToken))
+	resp, err := source.ListUsers(ctx, project, location, cluster, string(accessToken))
+	if err != nil {
+		return nil, util.ProecessGcpError(err)
+	}
+	return resp, nil
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/alloydb/alloydbwaitforoperation/alloydbwaitforoperation.go
+++ b/internal/tools/alloydb/alloydbwaitforoperation/alloydbwaitforoperation.go
@@ -24,6 +24,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )

@@ -213,25 +214,25 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }

 // Invoke executes the tool's logic.
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
 	source, err := tools.GetCompatibleSource[compatibleSource](resourceMgr, t.Source, t.Name, t.Type)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("source used is not compatible with the tool", 500, err)
 	}

 	paramsMap := params.AsMap()

 	project, ok := paramsMap["project"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'project' parameter")
+		return nil, util.NewAgentError("missing 'project' parameter", nil)
 	}
 	location, ok := paramsMap["location"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'location' parameter")
+		return nil, util.NewAgentError("missing 'location' parameter", nil)
 	}
 	operation, ok := paramsMap["operation"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'operation' parameter")
+		return nil, util.NewAgentError("missing 'operation' parameter", nil)
 	}

 	ctx, cancel := context.WithTimeout(ctx, 30*time.Minute)
@@ -246,14 +247,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	for retries < maxRetries {
 		select {
 		case <-ctx.Done():
-			return nil, fmt.Errorf("timed out waiting for operation: %w", ctx.Err())
+			return nil, util.NewAgentError("timed out waiting for operation %s", ctx.Err())
 		default:
 		}

 		op, err := source.GetOperations(ctx, project, location, operation, alloyDBConnectionMessageTemplate, delay, string(accessToken))
 		if err != nil {
-			return nil, err
-		} else if op != nil {
+			return nil, util.ProecessGcpError(err)
+		}
+		if op != nil {
 			return op, nil
 		}

@@ -264,7 +266,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		}
 		retries++
 	}
-	return nil, fmt.Errorf("exceeded max retries waiting for operation")
+	return nil, util.NewAgentError("exceeded max retries waiting for operation", nil)
 }

 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
--- a/internal/tools/bigquery/bigqueryconversationalanalytics/bigqueryconversationalanalytics.go
+++ b/internal/tools/bigquery/bigqueryconversationalanalytics/bigqueryconversationalanalytics.go
@@ -184,7 +184,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if source.UseClientAuthorization() {
 		// Use client-side access token
 		if accessToken == "" {
-			return nil, fmt.Errorf("tool is configured for client OAuth but no token was provided in the request header: %w", util.ErrUnauthorized)
+			return nil, util.NewClientServerError("tool is configured for client OAuth but no token was provided in the request header", http.StatusUnauthorized, nil)
 		}
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
--- a/internal/tools/tools.go
+++ b/internal/tools/tools.go
@@ -17,6 +17,7 @@ package tools
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"slices"
 	"strings"

@@ -80,13 +81,13 @@ type AccessToken string
 func (token AccessToken) ParseBearerToken() (string, error) {
 	headerParts := strings.Split(string(token), " ")
 	if len(headerParts) != 2 || strings.ToLower(headerParts[0]) != "bearer" {
-		return "", fmt.Errorf("authorization header must be in the format 'Bearer <token>': %w", util.ErrUnauthorized)
+		return "", util.NewClientServerError("authorization header must be in the format 'Bearer <token>'", http.StatusUnauthorized, nil)
 	}
 	return headerParts[1], nil
 }

 type Tool interface {
-	Invoke(context.Context, SourceProvider, parameters.ParamValues, AccessToken) (any, error)
+	Invoke(context.Context, SourceProvider, parameters.ParamValues, AccessToken) (any, util.ToolboxError)
 	EmbedParams(context.Context, parameters.ParamValues, map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error)
 	Manifest() Manifest
 	McpManifest() McpManifest
--- a/internal/util/errors.go
+++ b/internal/util/errors.go
@@ -0,0 +1,88 @@
+// Copyright 2026 Google LLC
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package util
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"google.golang.org/api/googleapi"
+)
+
+type ErrorCategory string
+
+const (
+	CategoryAgent  ErrorCategory = "AGENT_ERROR"
+	CategoryServer ErrorCategory = "SERVER_ERROR"
+)
+
+// ToolboxError is the interface all custom errors must satisfy
+type ToolboxError interface {
+	error
+	Category() ErrorCategory
+}
+
+// Agent Errors return 200 to the sender
+type AgentError struct {
+	Msg   string
+	Cause error
+}
+
+func (e *AgentError) Error() string { return e.Msg }
+
+func (e *AgentError) Category() ErrorCategory { return CategoryAgent }
+
+func (e *AgentError) Unwrap() error { return e.Cause }
+
+func NewAgentError(msg string, cause error) *AgentError {
+	return &AgentError{Msg: msg, Cause: cause}
+}
+
+// ClientServerError returns 4XX/5XX error code
+type ClientServerError struct {
+	Msg   string
+	Code  int
+	Cause error
+}
+
+func (e *ClientServerError) Error() string { return fmt.Sprintf("%s: %v", e.Msg, e.Cause) }
+
+func (e *ClientServerError) Category() ErrorCategory { return CategoryServer }
+
+func (e *ClientServerError) Unwrap() error { return e.Cause }
+
+func NewClientServerError(msg string, code int, cause error) *ClientServerError {
+	return &ClientServerError{Msg: msg, Code: code, Cause: cause}
+}
+
+func ProecessGcpError(err error) ToolboxError {
+	var gErr *googleapi.Error
+	if errors.As(err, &gErr) {
+		if gErr.Code == 401 {
+			return NewClientServerError(
+				"failed to access GCP resource",
+				http.StatusUnauthorized,
+				err,
+			)
+		}
+		if gErr.Code == 403 {
+			return NewClientServerError(
+				"failed to access GCP resource",
+				http.StatusForbidden,
+				err,
+			)
+		}
+	}
+	return NewAgentError("error processing GCP request", err)
+}
--- a/internal/util/parameters/parameters.go
+++ b/internal/util/parameters/parameters.go
@@ -19,6 +19,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"reflect"
 	"regexp"
 	"slices"
@@ -118,7 +119,7 @@ func parseFromAuthService(paramAuthServices []ParamAuthService, claimsMap map[st
 		}
 		return v, nil
 	}
-	return nil, fmt.Errorf("missing or invalid authentication header: %w", util.ErrUnauthorized)
+	return nil, util.NewClientServerError("missing or invalid authentication header", http.StatusUnauthorized, nil)
 }

 // CheckParamRequired checks if a parameter is required based on the required and default field.
--- a/internal/util/util.go
+++ b/internal/util/util.go
@@ -17,7 +17,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -188,5 +187,3 @@ func InstrumentationFromContext(ctx context.Context) (*telemetry.Instrumentation
 	}
 	return nil, fmt.Errorf("unable to retrieve instrumentation")
 }
-
-var ErrUnauthorized = errors.New("unauthorized")
--- a/server.json
+++ b/server.json
@@ -14,11 +14,11 @@
        "url": "https://github.com/googleapis/genai-toolbox",
        "source": "github"
    },
-    "version": "1.0.0",
+    "version": "0.26.0",
    "packages": [
        {
            "registryType": "oci",
-            "identifier": "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:1.0.0",
+            "identifier": "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.26.0",
            "transport": {
                "type": "streamable-http",
                "url": "http://{host}:{port}/mcp"
Author	SHA1	Message	Date
duwenxin	7fb56bfe67	update alloydb agent errors	2026-02-02 18:40:53 -05:00
duwenxin	99b71589b0	update mock tool interface	2026-02-02 18:38:27 -05:00
duwenxin	3f85c16f32	update alloydb tools error	2026-02-02 18:38:27 -05:00
duwenxin	9e884f52ea	resolve comments	2026-02-02 18:38:04 -05:00
duwenxin	8a0f179f15	refactor error return	2026-02-02 18:38:04 -05:00
duwenxin	87ae5ae816	refactor api handler	2026-02-02 18:38:04 -05:00
duwenxin	0c5285c5c8	update agentError constructor	2026-02-02 18:37:45 -05:00
Wenxin Du	ac544d0878	Merge branch 'main' into err	2026-02-02 16:20:09 -05:00
duwenxin	54f9a3d312	update comment	2026-02-02 15:37:18 -05:00
duwenxin	62d96a662d	add client err	2026-02-02 15:35:48 -05:00
duwenxin	46244458c4	add error code	2026-02-02 13:20:49 -05:00
Wenxin Du	b6fa798610	Merge branch 'main' into err	2026-01-29 18:00:58 -05:00
duwenxin	bb58baff70	add constructors	2026-01-29 18:00:11 -05:00
duwenxin	32b2c9366d	feat(server): add Tool call error categories	2026-01-29 12:03:53 -05:00
@@ -1 +1 @@
 .0.0
 .26.0