refactor redis

cmd/root.go

@@ -35,7 +35,6 @@ import (
 	yaml "github.com/goccy/go-yaml"
 	"github.com/googleapis/genai-toolbox/internal/auth"
 	"github.com/googleapis/genai-toolbox/internal/cli/invoke"
-	"github.com/googleapis/genai-toolbox/internal/cli/skills"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/log"
 	"github.com/googleapis/genai-toolbox/internal/prebuiltconfigs"
@@ -402,8 +401,6 @@ func NewCommand(opts ...Option) *Command {
 
 	// Register subcommands for tool invocation
 	baseCmd.AddCommand(invoke.NewCommand(cmd))
-	// Register subcommands for skill generation
-	baseCmd.AddCommand(skills.NewCommand(cmd))
 
 	return cmd
 }

cmd/skill_generate_test.go

@@ -1,179 +0,0 @@
-// 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 cmd
-
-import (
-	"context"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-	"time"
-)
-
-func TestGenerateSkill(t *testing.T) {
-	// Create a temporary directory for tests
-	tmpDir := t.TempDir()
-	outputDir := filepath.Join(tmpDir, "skills")
-
-	// Create a tools.yaml file with a sqlite tool
-	toolsFileContent := `
-sources:
-  my-sqlite:
-    kind: sqlite
-    database: test.db
-tools:
-  hello-sqlite:
-    kind: sqlite-sql
-    source: my-sqlite
-    description: "hello tool"
-    statement: "SELECT 'hello' as greeting"
-`
-
-	toolsFilePath := filepath.Join(tmpDir, "tools.yaml")
-	if err := os.WriteFile(toolsFilePath, []byte(toolsFileContent), 0644); err != nil {
-		t.Fatalf("failed to write tools file: %v", err)
-	}
-
-	args := []string{
-		"skills-generate",
-		"--tools-file", toolsFilePath,
-		"--output-dir", outputDir,
-		"--name", "hello-sqlite",
-		"--description", "hello tool",
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
-
-	_, got, err := invokeCommandWithContext(ctx, args)
-	if err != nil {
-		t.Fatalf("command failed: %v\nOutput: %s", err, got)
-	}
-
-	// Verify generated directory structure
-	skillPath := filepath.Join(outputDir, "hello-sqlite")
-	if _, err := os.Stat(skillPath); os.IsNotExist(err) {
-		t.Fatalf("skill directory not created: %s", skillPath)
-	}
-
-	// Check SKILL.md
-	skillMarkdown := filepath.Join(skillPath, "SKILL.md")
-	content, err := os.ReadFile(skillMarkdown)
-	if err != nil {
-		t.Fatalf("failed to read SKILL.md: %v", err)
-	}
-
-	expectedFrontmatter := `---
-name: hello-sqlite
-description: hello tool
----`
-	if !strings.HasPrefix(string(content), expectedFrontmatter) {
-		t.Errorf("SKILL.md does not have expected frontmatter format.\nExpected prefix:\n%s\nGot:\n%s", expectedFrontmatter, string(content))
-	}
-
-	if !strings.Contains(string(content), "## Usage") {
-		t.Errorf("SKILL.md does not contain '## Usage' section")
-	}
-
-	if !strings.Contains(string(content), "## Scripts") {
-		t.Errorf("SKILL.md does not contain '## Scripts' section")
-	}
-
-	if !strings.Contains(string(content), "### hello-sqlite") {
-		t.Errorf("SKILL.md does not contain '### hello-sqlite' tool header")
-	}
-
-	// Check script file
-	scriptFilename := "hello-sqlite.js"
-	scriptPath := filepath.Join(skillPath, "scripts", scriptFilename)
-	if _, err := os.Stat(scriptPath); os.IsNotExist(err) {
-		t.Fatalf("script file not created: %s", scriptPath)
-	}
-
-	scriptContent, err := os.ReadFile(scriptPath)
-	if err != nil {
-		t.Fatalf("failed to read script file: %v", err)
-	}
-	if !strings.Contains(string(scriptContent), "hello-sqlite") {
-		t.Errorf("script file does not contain expected tool name")
-	}
-
-	// Check assets
-	assetPath := filepath.Join(skillPath, "assets", "hello-sqlite.yaml")
-	if _, err := os.Stat(assetPath); os.IsNotExist(err) {
-		t.Fatalf("asset file not created: %s", assetPath)
-	}
-	assetContent, err := os.ReadFile(assetPath)
-	if err != nil {
-		t.Fatalf("failed to read asset file: %v", err)
-	}
-	if !strings.Contains(string(assetContent), "hello-sqlite") {
-		t.Errorf("asset file does not contain expected tool name")
-	}
-}
-
-func TestGenerateSkill_NoConfig(t *testing.T) {
-	tmpDir := t.TempDir()
-	outputDir := filepath.Join(tmpDir, "skills")
-
-	args := []string{
-		"skills-generate",
-		"--output-dir", outputDir,
-		"--name", "test",
-		"--description", "test",
-	}
-
-	_, _, err := invokeCommandWithContext(context.Background(), args)
-	if err == nil {
-		t.Fatal("expected command to fail when no configuration is provided and tools.yaml is missing")
-	}
-
-	// Should not have created the directory if no config was processed
-	if _, err := os.Stat(outputDir); !os.IsNotExist(err) {
-		t.Errorf("output directory should not have been created")
-	}
-}
-
-func TestGenerateSkill_MissingArguments(t *testing.T) {
-	tmpDir := t.TempDir()
-	toolsFilePath := filepath.Join(tmpDir, "tools.yaml")
-	if err := os.WriteFile(toolsFilePath, []byte("tools: {}"), 0644); err != nil {
-		t.Fatalf("failed to write tools file: %v", err)
-	}
-
-	tests := []struct {
-		name string
-		args []string
-	}{
-		{
-			name: "missing name",
-			args: []string{"skills-generate", "--tools-file", toolsFilePath, "--description", "test"},
-		},
-		{
-			name: "missing description",
-			args: []string{"skills-generate", "--tools-file", toolsFilePath, "--name", "test"},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			_, got, err := invokeCommandWithContext(context.Background(), tt.args)
-			if err == nil {
-				t.Fatalf("expected command to fail due to missing arguments, but it succeeded\nOutput: %s", got)
-			}
-		})
-	}
-}

docs/en/getting-started/quickstart/js/genkit/quickstart.js

@@ -53,7 +53,7 @@ export async function main() {
 
   for (const query of queries) {
     conversationHistory.push({ role: "user", content: [{ text: query }] });
-    let response = await ai.generate({
+    const response = await ai.generate({
       messages: conversationHistory,
       tools: tools,
     });

docs/en/how-to/generate_skill.md

@@ -1,112 +0,0 @@
----
-title: "Generate Agent Skills"
-type: docs
-weight: 10
-description: >
-  How to generate agent skills from a toolset.
----
-
-The `skills-generate` command allows you to convert a **toolset** into an **Agent Skill**. A toolset is a collection of tools, and the generated skill will contain metadata and execution scripts for all tools within that toolset, complying with the [Agent Skill specification](https://agentskills.io/specification).
-
-## Before you begin
-
-1. Make sure you have the `toolbox` executable in your PATH.
-2. Make sure you have [Node.js](https://nodejs.org/) installed on your system.
-
-## Generating a Skill from a Toolset
-
-A skill package consists of a `SKILL.md` file (with required YAML frontmatter) and a set of Node.js scripts. Each tool defined in your toolset maps to a corresponding script in the generated Node.js scripts (`.js`) that work across different platforms (Linux, macOS, Windows).
-
-
-### Command Usage
-
-The basic syntax for the command is:
-
-```bash
-toolbox <tool-source> skills-generate \
-  --name <skill-name> \
-  --toolset <toolset-name> \
-  --description <description> \
-  --output-dir <output-directory>
-```
-
-- `<tool-source>`: Can be `--tools-file`, `--tools-files`, `--tools-folder`, and `--prebuilt`. See the [CLI Reference](../reference/cli.md) for details.
-- `--name`: Name of the generated skill.
-- `--description`: Description of the generated skill.
-- `--toolset`: (Optional) Name of the toolset to convert into a skill. If not provided, all tools will be included.
-- `--output-dir`: (Optional) Directory to output generated skills (default: "skills").
-
-{{< notice note >}}
-**Note:** The `<skill-name>` must follow the Agent Skill [naming convention](https://agentskills.io/specification): it must contain only lowercase alphanumeric characters and hyphens, cannot start or end with a hyphen, and cannot contain consecutive hyphens (e.g., `my-skill`, `data-processing`).
-{{< /notice >}}
-
-### Example: Custom Tools File
-
-1. Create a `tools.yaml` file with a toolset and some tools:
-
-   ```yaml
-   tools:
-     tool_a:
-       description: "First tool"
-       run:
-         command: "echo 'Tool A'"
-     tool_b:
-       description: "Second tool"
-       run:
-         command: "echo 'Tool B'"
-   toolsets:
-     my_toolset:
-       tools:
-         - tool_a
-         - tool_b
-   ```
-
-2. Generate the skill:
-
-   ```bash
-   toolbox --tools-file tools.yaml skills-generate \
-     --name "my-skill" \
-     --toolset "my_toolset" \
-     --description "A skill containing multiple tools" \
-     --output-dir "generated-skills"
-   ```
-
-3. The generated skill directory structure:
-
-   ```text
-   generated-skills/
-   └── my-skill/
-       ├── SKILL.md
-       ├── assets/
-       │   ├── tool_a.yaml
-       │   └── tool_b.yaml
-       └── scripts/
-           ├── tool_a.js
-           └── tool_b.js
-   ```
-
-   In this example, the skill contains two Node.js scripts (`tool_a.js` and `tool_b.js`), each mapping to a tool in the original toolset.
-
-### Example: Prebuilt Configuration
-
-You can also generate skills from prebuilt toolsets:
-
-```bash
-toolbox --prebuilt alloydb-postgres-admin skills-generate \
-  --name "alloydb-postgres-admin" \
-  --description "skill for performing administrative operations on alloydb"
-```
-
-## Installing the Generated Skill in Gemini CLI
-
-Once you have generated a skill, you can install it into the Gemini CLI using the `gemini skills install` command.
-
-### Installation Command
-
-Provide the path to the directory containing the generated skill:
-
-```bash
-gemini skills install /path/to/generated-skills/my-skill
-```
-
-Alternatively, use ~/.gemini/skills as the `--output-dir` to generate the skill straight to the Gemini CLI.

docs/en/how-to/invoke_tool.md

@@ -13,22 +13,21 @@ The `invoke` command allows you to invoke tools defined in your configuration di
 
 {{< notice tip >}}
 **Keep configurations minimal:** The `invoke` command initializes *all* resources (sources, tools, etc.) defined in your configuration files during execution. To ensure fast response times, consider using a minimal configuration file containing only the tools you need for the specific invocation.
-{{< /notice >}}
+{{< notice tip >}}
 
-## Before you begin
+## Prerequisites
 
-1. Make sure you have the `toolbox` binary installed or built.
+- You have the `toolbox` binary installed or built.
-2. Make sure you have a valid tool configuration file (e.g., `tools.yaml`).
+- You have a valid tool configuration file (e.g., `tools.yaml`).
 
-### Command Usage
+## Basic Usage
 
 The basic syntax for the command is:
 
 ```bash
-toolbox <tool-source> invoke <tool-name> [params]
+toolbox [--tools-file <path> | --prebuilt <name>] invoke <tool-name> [params]
 ```
 
-- `<tool-source>`: Can be `--tools-file`, `--tools-files`, `--tools-folder`, and `--prebuilt`. See the [CLI Reference](../reference/cli.md) for details.
 - `<tool-name>`: The name of the tool you want to call. This must match the name defined in your `tools.yaml`.
 - `[params]`: (Optional) A JSON string representing the arguments for the tool.
 

docs/en/reference/cli.md

@@ -32,8 +32,7 @@ description: >
 
 ## Sub Commands
 
-<details>
+### `invoke`
-<summary><code>invoke</code></summary>
 
 Executes a tool directly with the provided parameters. This is useful for testing tool configurations and parameters without needing a full client setup.
 
@@ -43,36 +42,8 @@ Executes a tool directly with the provided parameters. This is useful for testin
 toolbox invoke <tool-name> [params]
 ```
 
-**Arguments:**
+- `<tool-name>`: The name of the tool to execute (as defined in your configuration).
-
+- `[params]`: (Optional) A JSON string containing the parameters for the tool.
-- `tool-name`: The name of the tool to execute (as defined in your configuration).
-- `params`: (Optional) A JSON string containing the parameters for the tool.
-
-For more detailed instructions, see [Invoke Tools via CLI](../how-to/invoke_tool.md).
-
-</details>
-
-<details>
-<summary><code>skills-generate</code></summary>
-
-Generates a skill package from a specified toolset. Each tool in the toolset will have a corresponding Node.js execution script in the generated skill.
-
-**Syntax:**
-
-```bash
-toolbox skills-generate --name <name> --description <description> --toolset <toolset> --output-dir <output>
-```
-
-**Flags:**
-
-- `--name`: Name of the generated skill.
-- `--description`: Description of the generated skill.
-- `--toolset`: (Optional) Name of the toolset to convert into a skill. If not provided, all tools will be included.
-- `--output-dir`: (Optional) Directory to output generated skills (default: "skills").
-
-For more detailed instructions, see [Generate Agent Skills](../how-to/generate_skill.md).
-
-</details>
 
 ## Examples
 

internal/cli/skills/command.go

@@ -1,237 +0,0 @@
-// 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 skills
-
-import (
-	"context"
-	_ "embed"
-	"fmt"
-	"os"
-	"path/filepath"
-	"sort"
-
-	"github.com/googleapis/genai-toolbox/internal/log"
-	"github.com/googleapis/genai-toolbox/internal/server"
-	"github.com/googleapis/genai-toolbox/internal/server/resources"
-	"github.com/googleapis/genai-toolbox/internal/tools"
-
-	"github.com/spf13/cobra"
-)
-
-// RootCommand defines the interface for required by skills-generate subcommand.
-// This allows subcommands to access shared resources and functionality without
-// direct coupling to the root command's implementation.
-type RootCommand interface {
-	// Config returns a copy of the current server configuration.
-	Config() server.ServerConfig
-
-	// LoadConfig loads and merges the configuration from files, folders, and prebuilts.
-	LoadConfig(ctx context.Context) error
-
-	// Setup initializes the runtime environment, including logging and telemetry.
-	// It returns the updated context and a shutdown function to be called when finished.
-	Setup(ctx context.Context) (context.Context, func(context.Context) error, error)
-
-	// Logger returns the logger instance.
-	Logger() log.Logger
-}
-
-// Command is the command for generating skills.
-type Command struct {
-	*cobra.Command
-	rootCmd     RootCommand
-	name        string
-	description string
-	toolset     string
-	outputDir   string
-}
-
-// NewCommand creates a new Command.
-func NewCommand(rootCmd RootCommand) *cobra.Command {
-	cmd := &Command{
-		rootCmd: rootCmd,
-	}
-	cmd.Command = &cobra.Command{
-		Use:   "skills-generate",
-		Short: "Generate skills from tool configurations",
-		RunE: func(c *cobra.Command, args []string) error {
-			return cmd.run(c)
-		},
-	}
-
-	cmd.Flags().StringVar(&cmd.name, "name", "", "Name of the generated skill.")
-	cmd.Flags().StringVar(&cmd.description, "description", "", "Description of the generated skill")
-	cmd.Flags().StringVar(&cmd.toolset, "toolset", "", "Name of the toolset to convert into a skill. If not provided, all tools will be included.")
-	cmd.Flags().StringVar(&cmd.outputDir, "output-dir", "skills", "Directory to output generated skills")
-
-	_ = cmd.MarkFlagRequired("name")
-	_ = cmd.MarkFlagRequired("description")
-	return cmd.Command
-}
-
-func (c *Command) run(cmd *cobra.Command) error {
-	ctx, cancel := context.WithCancel(cmd.Context())
-	defer cancel()
-
-	ctx, shutdown, err := c.rootCmd.Setup(ctx)
-	if err != nil {
-		return err
-	}
-	defer func() {
-		_ = shutdown(ctx)
-	}()
-
-	logger := c.rootCmd.Logger()
-
-	// Load and merge tool configurations
-	if err := c.rootCmd.LoadConfig(ctx); err != nil {
-		return err
-	}
-
-	if err := os.MkdirAll(c.outputDir, 0755); err != nil {
-		errMsg := fmt.Errorf("error creating output directory: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-
-	logger.InfoContext(ctx, fmt.Sprintf("Generating skill '%s'...", c.name))
-
-	// Initialize toolbox and collect tools
-	allTools, err := c.collectTools(ctx)
-	if err != nil {
-		errMsg := fmt.Errorf("error collecting tools: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-
-	if len(allTools) == 0 {
-		logger.InfoContext(ctx, "No tools found to generate.")
-		return nil
-	}
-
-	// Generate the combined skill directory
-	skillPath := filepath.Join(c.outputDir, c.name)
-	if err := os.MkdirAll(skillPath, 0755); err != nil {
-		errMsg := fmt.Errorf("error creating skill directory: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-
-	// Generate assets directory
-	assetsPath := filepath.Join(skillPath, "assets")
-	if err := os.MkdirAll(assetsPath, 0755); err != nil {
-		errMsg := fmt.Errorf("error creating assets dir: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-
-	// Generate scripts directory
-	scriptsPath := filepath.Join(skillPath, "scripts")
-	if err := os.MkdirAll(scriptsPath, 0755); err != nil {
-		errMsg := fmt.Errorf("error creating scripts dir: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-
-	// Iterate over keys to ensure deterministic order
-	var toolNames []string
-	for name := range allTools {
-		toolNames = append(toolNames, name)
-	}
-	sort.Strings(toolNames)
-
-	for _, toolName := range toolNames {
-		// Generate YAML config in asset directory
-		minimizedContent, err := generateToolConfigYAML(c.rootCmd.Config(), toolName)
-		if err != nil {
-			errMsg := fmt.Errorf("error generating filtered config for %s: %w", toolName, err)
-			logger.ErrorContext(ctx, errMsg.Error())
-			return errMsg
-		}
-
-		specificToolsFileName := fmt.Sprintf("%s.yaml", toolName)
-		if minimizedContent != nil {
-			destPath := filepath.Join(assetsPath, specificToolsFileName)
-			if err := os.WriteFile(destPath, minimizedContent, 0644); err != nil {
-				errMsg := fmt.Errorf("error writing filtered config for %s: %w", toolName, err)
-				logger.ErrorContext(ctx, errMsg.Error())
-				return errMsg
-			}
-		}
-
-		// Generate wrapper script in scripts directory
-		scriptContent, err := generateScriptContent(toolName, specificToolsFileName)
-		if err != nil {
-			errMsg := fmt.Errorf("error generating script content for %s: %w", toolName, err)
-			logger.ErrorContext(ctx, errMsg.Error())
-			return errMsg
-		}
-
-		scriptFilename := filepath.Join(scriptsPath, fmt.Sprintf("%s.js", toolName))
-		if err := os.WriteFile(scriptFilename, []byte(scriptContent), 0755); err != nil {
-			errMsg := fmt.Errorf("error writing script %s: %w", scriptFilename, err)
-			logger.ErrorContext(ctx, errMsg.Error())
-			return errMsg
-		}
-	}
-
-	// Generate SKILL.md
-	skillContent, err := generateSkillMarkdown(c.name, c.description, allTools)
-	if err != nil {
-		errMsg := fmt.Errorf("error generating SKILL.md content: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-	skillMdPath := filepath.Join(skillPath, "SKILL.md")
-	if err := os.WriteFile(skillMdPath, []byte(skillContent), 0644); err != nil {
-		errMsg := fmt.Errorf("error writing SKILL.md: %w", err)
-		logger.ErrorContext(ctx, errMsg.Error())
-		return errMsg
-	}
-
-	logger.InfoContext(ctx, fmt.Sprintf("Successfully generated skill '%s' with %d tools.", c.name, len(allTools)))
-
-	return nil
-}
-
-func (c *Command) collectTools(ctx context.Context) (map[string]tools.Tool, error) {
-	// Initialize Resources
-	sourcesMap, authServicesMap, embeddingModelsMap, toolsMap, toolsetsMap, promptsMap, promptsetsMap, err := server.InitializeConfigs(ctx, c.rootCmd.Config())
-	if err != nil {
-		return nil, fmt.Errorf("failed to initialize resources: %w", err)
-	}
-
-	resourceMgr := resources.NewResourceManager(sourcesMap, authServicesMap, embeddingModelsMap, toolsMap, toolsetsMap, promptsMap, promptsetsMap)
-
-	result := make(map[string]tools.Tool)
-
-	if c.toolset == "" {
-		return toolsMap, nil
-	}
-
-	ts, ok := resourceMgr.GetToolset(c.toolset)
-	if !ok {
-		return nil, fmt.Errorf("toolset %q not found", c.toolset)
-	}
-
-	for _, t := range ts.Tools {
-		if t != nil {
-			tool := *t
-			result[tool.McpManifest().Name] = tool
-		}
-	}
-
-	return result, nil
-}

internal/cli/skills/generator.go

@@ -1,297 +0,0 @@
-// 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 skills
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"sort"
-	"strings"
-	"text/template"
-
-	"github.com/goccy/go-yaml"
-	"github.com/googleapis/genai-toolbox/internal/server"
-	"github.com/googleapis/genai-toolbox/internal/sources"
-	"github.com/googleapis/genai-toolbox/internal/tools"
-	"github.com/googleapis/genai-toolbox/internal/util/parameters"
-)
-
-const skillTemplate = `---
-name: {{.SkillName}}
-description: {{.SkillDescription}}
----
-
-## Usage
-
-All scripts can be executed using Node.js. Replace ` + "`" + `<param_name>` + "`" + ` and ` + "`" + `<param_value>` + "`" + ` with actual values.
-
-**Bash:**
-` + "`" + `node scripts/<script_name>.js '{"<param_name>": "<param_value>"}'` + "`" + `
-
-**PowerShell:**
-` + "`" + `node scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'` + "`" + `
-
-## Scripts
-
-{{range .Tools}}
-### {{.Name}}
-
-{{.Description}}
-
-{{.ParametersSchema}}
-
----
-{{end}}
-`
-
-type toolTemplateData struct {
-	Name             string
-	Description      string
-	ParametersSchema string
-}
-
-type skillTemplateData struct {
-	SkillName        string
-	SkillDescription string
-	Tools            []toolTemplateData
-}
-
-// generateSkillMarkdown generates the content of the SKILL.md file.
-// It includes usage instructions and a reference section for each tool in the skill,
-// detailing its description and parameters.
-func generateSkillMarkdown(skillName, skillDescription string, toolsMap map[string]tools.Tool) (string, error) {
-	var toolsData []toolTemplateData
-
-	// Order tools based on name
-	var toolNames []string
-	for name := range toolsMap {
-		toolNames = append(toolNames, name)
-	}
-	sort.Strings(toolNames)
-
-	for _, name := range toolNames {
-		tool := toolsMap[name]
-		manifest := tool.Manifest()
-
-		parametersSchema, err := formatParameters(manifest.Parameters)
-		if err != nil {
-			return "", err
-		}
-
-		toolsData = append(toolsData, toolTemplateData{
-			Name:             name,
-			Description:      manifest.Description,
-			ParametersSchema: parametersSchema,
-		})
-	}
-
-	data := skillTemplateData{
-		SkillName:        skillName,
-		SkillDescription: skillDescription,
-		Tools:            toolsData,
-	}
-
-	tmpl, err := template.New("markdown").Parse(skillTemplate)
-	if err != nil {
-		return "", fmt.Errorf("error parsing markdown template: %w", err)
-	}
-
-	var buf strings.Builder
-	if err := tmpl.Execute(&buf, data); err != nil {
-		return "", fmt.Errorf("error executing markdown template: %w", err)
-	}
-
-	return buf.String(), nil
-}
-
-const nodeScriptTemplate = `#!/usr/bin/env node
-
-const { spawn, execSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-const toolName = "{{.Name}}";
-const toolsFileName = "{{.ToolsFileName}}";
-
-function getToolboxPath() {
-    try {
-        const checkCommand = process.platform === 'win32' ? 'where toolbox' : 'which toolbox';
-        const globalPath = execSync(checkCommand, { stdio: 'pipe', encoding: 'utf-8' }).trim();
-        if (globalPath) {
-            return globalPath.split('\n')[0].trim();
-        }
-    } catch (e) {
-        // Ignore error;
-    }
-    const localPath = path.resolve(__dirname, '../../../toolbox');
-    if (fs.existsSync(localPath)) {
-        return localPath;
-    }
-    throw new Error("Toolbox binary not found");
-}
-
-let toolboxBinary;
-try {
-    toolboxBinary = getToolboxPath();
-} catch (err) {
-    console.error("Error:", err.message);
-    process.exit(1);
-}
-
-let configArgs = [];
-if (toolsFileName) {
-  configArgs.push("--tools-file", path.join(__dirname, "..", "assets", toolsFileName));
-}
-
-const args = process.argv.slice(2);
-const toolboxArgs = [...configArgs, "invoke", toolName, ...args];
-
-const child = spawn(toolboxBinary, toolboxArgs, { stdio: 'inherit' });
-
-child.on('close', (code) => {
-  process.exit(code);
-});
-
-child.on('error', (err) => {
-  console.error("Error executing toolbox:", err);
-  process.exit(1);
-});
-`
-
-type scriptData struct {
-	Name          string
-	ToolsFileName string
-}
-
-// generateScriptContent creates the content for a Node.js wrapper script.
-// This script invokes the toolbox CLI with the appropriate configuration
-// (using a generated tools file) and arguments to execute the specific tool.
-func generateScriptContent(name string, toolsFileName string) (string, error) {
-	data := scriptData{
-		Name:          name,
-		ToolsFileName: toolsFileName,
-	}
-
-	tmpl, err := template.New("script").Parse(nodeScriptTemplate)
-	if err != nil {
-		return "", fmt.Errorf("error parsing script template: %w", err)
-	}
-
-	var buf strings.Builder
-	if err := tmpl.Execute(&buf, data); err != nil {
-		return "", fmt.Errorf("error executing script template: %w", err)
-	}
-
-	return buf.String(), nil
-}
-
-// formatParameters converts a list of parameter manifests into a formatted JSON schema string.
-// This schema is used in the skill documentation to describe the input parameters for a tool.
-func formatParameters(params []parameters.ParameterManifest) (string, error) {
-	if len(params) == 0 {
-		return "", nil
-	}
-
-	properties := make(map[string]interface{})
-	var required []string
-
-	for _, p := range params {
-		paramMap := map[string]interface{}{
-			"type":        p.Type,
-			"description": p.Description,
-		}
-		if p.Default != nil {
-			paramMap["default"] = p.Default
-		}
-		properties[p.Name] = paramMap
-		if p.Required {
-			required = append(required, p.Name)
-		}
-	}
-
-	schema := map[string]interface{}{
-		"type":       "object",
-		"properties": properties,
-	}
-	if len(required) > 0 {
-		schema["required"] = required
-	}
-
-	schemaJSON, err := json.MarshalIndent(schema, "", "  ")
-	if err != nil {
-		return "", fmt.Errorf("error generating parameters schema: %w", err)
-	}
-
-	return fmt.Sprintf("#### Parameters\n\n```json\n%s\n```", string(schemaJSON)), nil
-}
-
-// generateToolConfigYAML generates the YAML configuration for a single tool and its dependency (source).
-// It extracts the relevant tool and source configurations from the server config and formats them
-// into a YAML document suitable for inclusion in the skill's assets.
-func generateToolConfigYAML(cfg server.ServerConfig, toolName string) ([]byte, error) {
-	toolCfg, ok := cfg.ToolConfigs[toolName]
-	if !ok {
-		return nil, fmt.Errorf("error finding tool config: %s", toolName)
-	}
-
-	var buf bytes.Buffer
-	encoder := yaml.NewEncoder(&buf)
-
-	// Process Tool Config
-	toolWrapper := struct {
-		Kind   string           `yaml:"kind"`
-		Name   string           `yaml:"name"`
-		Config tools.ToolConfig `yaml:",inline"`
-	}{
-		Kind:   "tools",
-		Name:   toolName,
-		Config: toolCfg,
-	}
-
-	if err := encoder.Encode(toolWrapper); err != nil {
-		return nil, fmt.Errorf("error encoding tool config: %w", err)
-	}
-
-	// Process Source Config
-	var toolMap map[string]interface{}
-	b, err := yaml.Marshal(toolCfg)
-	if err != nil {
-		return nil, fmt.Errorf("error marshaling tool config: %w", err)
-	}
-	if err := yaml.Unmarshal(b, &toolMap); err != nil {
-		return nil, fmt.Errorf("error unmarshaling tool config map: %w", err)
-	}
-
-	if sourceName, ok := toolMap["source"].(string); ok {
-		if sourceCfg, ok := cfg.SourceConfigs[sourceName]; ok {
-			sourceWrapper := struct {
-				Kind   string               `yaml:"kind"`
-				Name   string               `yaml:"name"`
-				Config sources.SourceConfig `yaml:",inline"`
-			}{
-				Kind:   "sources",
-				Name:   sourceName,
-				Config: sourceCfg,
-			}
-
-			if err := encoder.Encode(sourceWrapper); err != nil {
-				return nil, fmt.Errorf("error encoding source config: %w", err)
-			}
-		}
-	}
-
-	return buf.Bytes(), nil
-}

internal/cli/skills/generator_test.go

@@ -1,338 +0,0 @@
-// 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 skills
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"github.com/googleapis/genai-toolbox/internal/server"
-	"github.com/googleapis/genai-toolbox/internal/sources"
-	"github.com/googleapis/genai-toolbox/internal/tools"
-	"github.com/googleapis/genai-toolbox/internal/util/parameters"
-	"go.opentelemetry.io/otel/trace"
-)
-
-type MockToolConfig struct {
-	Type       string                `yaml:"type"`
-	Source     string                `yaml:"source"`
-	Other      string                `yaml:"other"`
-	Parameters parameters.Parameters `yaml:"parameters"`
-}
-
-func (m MockToolConfig) ToolConfigType() string {
-	return m.Type
-}
-
-func (m MockToolConfig) Initialize(map[string]sources.Source) (tools.Tool, error) {
-	return nil, nil
-}
-
-type MockSourceConfig struct {
-	TypeVal string
-	ConnVal string
-}
-
-func (m MockSourceConfig) SourceConfigType() string {
-	return m.TypeVal
-}
-
-func (m MockSourceConfig) Initialize(context.Context, trace.Tracer) (sources.Source, error) {
-	return nil, nil
-}
-
-func (m MockSourceConfig) MarshalYAML() (interface{}, error) {
-	return map[string]interface{}{
-		"connection_string": m.ConnVal,
-		"type":              m.TypeVal,
-	}, nil
-}
-
-func TestFormatParameters(t *testing.T) {
-	tests := []struct {
-		name         string
-		params       []parameters.ParameterManifest
-		wantContains []string
-		wantErr      bool
-	}{
-		{
-			name:         "empty parameters",
-			params:       []parameters.ParameterManifest{},
-			wantContains: []string{""},
-		},
-		{
-			name: "single required string parameter",
-			params: []parameters.ParameterManifest{
-				{
-					Name:        "param1",
-					Description: "A test parameter",
-					Type:        "string",
-					Required:    true,
-				},
-			},
-			wantContains: []string{
-				"## Parameters",
-				"```json",
-				`"type": "object"`,
-				`"properties": {`,
-				`"param1": {`,
-				`"type": "string"`,
-				`"description": "A test parameter"`,
-				`"required": [`,
-				`"param1"`,
-			},
-		},
-		{
-			name: "mixed parameters with defaults",
-			params: []parameters.ParameterManifest{
-				{
-					Name:        "param1",
-					Description: "Param 1",
-					Type:        "string",
-					Required:    true,
-				},
-				{
-					Name:        "param2",
-					Description: "Param 2",
-					Type:        "integer",
-					Default:     42,
-					Required:    false,
-				},
-			},
-			wantContains: []string{
-				`"param1": {`,
-				`"param2": {`,
-				`"default": 42`,
-				`"required": [`,
-				`"param1"`,
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, err := formatParameters(tt.params)
-			if (err != nil) != tt.wantErr {
-				t.Errorf("formatParameters() error = %v, wantErr %v", err, tt.wantErr)
-				return
-			}
-			if tt.wantErr {
-				return
-			}
-
-			if len(tt.params) == 0 {
-				if got != "" {
-					t.Errorf("formatParameters() = %v, want empty string", got)
-				}
-				return
-			}
-
-			for _, want := range tt.wantContains {
-				if !strings.Contains(got, want) {
-					t.Errorf("formatParameters() result missing expected string: %s\nGot:\n%s", want, got)
-				}
-			}
-		})
-	}
-}
-
-func TestGenerateSkillMarkdown(t *testing.T) {
-	toolsMap := map[string]tools.Tool{
-		"tool1": server.MockTool{
-			Description: "First tool",
-			Params: []parameters.Parameter{
-				parameters.NewStringParameter("p1", "d1"),
-			},
-		},
-	}
-
-	got, err := generateSkillMarkdown("MySkill", "My Description", toolsMap)
-	if err != nil {
-		t.Fatalf("generateSkillMarkdown() error = %v", err)
-	}
-
-	expectedSubstrings := []string{
-		"name: MySkill",
-		"description: My Description",
-		"## Usage",
-		"All scripts can be executed using Node.js",
-		"**Bash:**",
-		"`node scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'`",
-		"**PowerShell:**",
-		"`node scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'`",
-		"## Scripts",
-		"### tool1",
-		"First tool",
-		"## Parameters",
-	}
-
-	for _, s := range expectedSubstrings {
-		if !strings.Contains(got, s) {
-			t.Errorf("generateSkillMarkdown() missing substring %q", s)
-		}
-	}
-}
-
-func TestGenerateScriptContent(t *testing.T) {
-	tests := []struct {
-		name          string
-		toolName      string
-		toolsFileName string
-		wantContains  []string
-	}{
-		{
-			name:          "basic script",
-			toolName:      "test-tool",
-			toolsFileName: "",
-			wantContains: []string{
-				`const toolName = "test-tool";`,
-				`const toolsFileName = "";`,
-				`const toolboxArgs = [...configArgs, "invoke", toolName, ...args];`,
-			},
-		},
-		{
-			name:          "script with tools file",
-			toolName:      "complex-tool",
-			toolsFileName: "tools.yaml",
-			wantContains: []string{
-				`const toolName = "complex-tool";`,
-				`const toolsFileName = "tools.yaml";`,
-				`configArgs.push("--tools-file", path.join(__dirname, "..", "assets", toolsFileName));`,
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, err := generateScriptContent(tt.toolName, tt.toolsFileName)
-			if err != nil {
-				t.Fatalf("generateScriptContent() error = %v", err)
-			}
-
-			for _, s := range tt.wantContains {
-				if !strings.Contains(got, s) {
-					t.Errorf("generateScriptContent() missing substring %q\nGot:\n%s", s, got)
-				}
-			}
-		})
-	}
-}
-
-func TestGenerateToolConfigYAML(t *testing.T) {
-	cfg := server.ServerConfig{
-		ToolConfigs: server.ToolConfigs{
-			"tool1": MockToolConfig{
-				Type:   "custom-tool",
-				Source: "src1",
-				Other:  "foo",
-			},
-			"toolNoSource": MockToolConfig{
-				Type: "http",
-			},
-			"toolWithParams": MockToolConfig{
-				Type: "custom-tool",
-				Parameters: []parameters.Parameter{
-					parameters.NewStringParameter("param1", "desc1"),
-				},
-			},
-		},
-		SourceConfigs: server.SourceConfigs{
-			"src1": MockSourceConfig{
-				TypeVal: "postgres",
-				ConnVal: "conn1",
-			},
-		},
-	}
-
-	tests := []struct {
-		name         string
-		toolName     string
-		wantContains []string
-		wantErr      bool
-		wantNil      bool
-	}{
-		{
-			name:     "tool with source",
-			toolName: "tool1",
-			wantContains: []string{
-				"kind: tools",
-				"name: tool1",
-				"type: custom-tool",
-				"source: src1",
-				"other: foo",
-				"---",
-				"kind: sources",
-				"name: src1",
-				"type: postgres",
-				"connection_string: conn1",
-			},
-		},
-		{
-			name:     "tool without source",
-			toolName: "toolNoSource",
-			wantContains: []string{
-				"kind: tools",
-				"name: toolNoSource",
-				"type: http",
-			},
-		},
-		{
-			name:     "tool with parameters",
-			toolName: "toolWithParams",
-			wantContains: []string{
-				"kind: tools",
-				"name: toolWithParams",
-				"type: custom-tool",
-				"parameters:",
-				"- name: param1",
-				"type: string",
-				"description: desc1",
-			},
-		},
-		{
-			name:     "non-existent tool",
-			toolName: "missing-tool",
-			wantErr:  true,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			gotBytes, err := generateToolConfigYAML(cfg, tt.toolName)
-			if (err != nil) != tt.wantErr {
-				t.Errorf("generateToolConfigYAML() error = %v, wantErr %v", err, tt.wantErr)
-				return
-			}
-			if tt.wantErr {
-				return
-			}
-
-			if tt.wantNil {
-				if gotBytes != nil {
-					t.Errorf("generateToolConfigYAML() expected nil, got %s", string(gotBytes))
-				}
-				return
-			}
-
-			got := string(gotBytes)
-			for _, want := range tt.wantContains {
-				if !strings.Contains(got, want) {
-					t.Errorf("generateToolConfigYAML() result missing expected string: %q\nGot:\n%s", want, got)
-				}
-			}
-		})
-	}
-}

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) {
+		errMsg := fmt.Sprintf("error parsing authenticated parameters from ID token: %w", err)
-			s.logger.DebugContext(ctx, fmt.Sprintf("error parsing authenticated parameters from ID token: %s", 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 tbErr util.ToolboxError
-		var statusCode int
 
-		// Upstream API auth error propagation
+		if errors.As(err, &tbErr) {
-		switch {
+			switch tbErr.Category() {
-		case strings.Contains(errStr, "Error 401"):
+			case util.CategoryAgent:
-			statusCode = http.StatusUnauthorized
+				// Agent Errors -> 200 OK
-		case strings.Contains(errStr, "Error 403"):
+				s.logger.DebugContext(ctx, fmt.Sprintf("Tool invocation agent error: %v", err))
-			statusCode = http.StatusForbidden
+				_ = render.Render(w, r, newErrResponse(err, http.StatusOK))
-		}
+				return
 
-		if statusCode == http.StatusUnauthorized || statusCode == http.StatusForbidden {
+			case util.CategoryServer:
-			if clientAuth {
+				// Server Errors -> Check the specific code inside
-				// Propagate the original 401/403 error.
+				var clientServerErr *util.ClientServerError
-				s.logger.DebugContext(ctx, fmt.Sprintf("error invoking tool. Client credentials lack authorization to the source: %v", err))
+				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.
+		} else {
-			internalErr := fmt.Errorf("unexpected auth error occured during Tool invocation: %w", err)
+			// Unknown error -> 500
-			s.logger.ErrorContext(ctx, internalErr.Error())
+			s.logger.ErrorContext(ctx, fmt.Sprintf("Tool invocation unknown error: %v", err))
-			_ = render.Render(w, r, newErrResponse(internalErr, http.StatusInternalServerError))
+			_ = 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)

internal/server/common_test.go

@@ -24,11 +24,13 @@ import (
 	"testing"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/log"
 	"github.com/googleapis/genai-toolbox/internal/prompts"
 	"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"
 )
 
@@ -40,6 +42,140 @@ var (
 	_ prompts.Prompt = MockPrompt{}
 )
 
+// MockTool is used to mock tools in tests
+type MockTool struct {
+	Name                         string
+	Description                  string
+	Params                       []parameters.Parameter
+	manifest                     tools.Manifest
+	unauthorized                 bool
+	requiresClientAuthrorization bool
+}
+
+func (t MockTool) Invoke(context.Context, tools.SourceProvider, parameters.ParamValues, tools.AccessToken) (any, util.ToolboxError) {
+	mock := []any{t.Name}
+	return mock, nil
+}
+
+func (t MockTool) ToConfig() tools.ToolConfig {
+	return nil
+}
+
+// claims is a map of user info decoded from an auth token
+func (t MockTool) ParseParams(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
+	return parameters.ParseParams(t.Params, data, claimsMap)
+}
+
+func (t MockTool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
+	return parameters.EmbedParams(ctx, t.Params, paramValues, embeddingModelsMap, nil)
+}
+
+func (t MockTool) Manifest() tools.Manifest {
+	pMs := make([]parameters.ParameterManifest, 0, len(t.Params))
+	for _, p := range t.Params {
+		pMs = append(pMs, p.Manifest())
+	}
+	return tools.Manifest{Description: t.Description, Parameters: pMs}
+}
+
+func (t MockTool) Authorized(verifiedAuthServices []string) bool {
+	// defaulted to true
+	return !t.unauthorized
+}
+
+func (t MockTool) RequiresClientAuthorization(tools.SourceProvider) (bool, error) {
+	// defaulted to false
+	return t.requiresClientAuthrorization, nil
+}
+
+func (t MockTool) GetParameters() parameters.Parameters {
+	return t.Params
+}
+
+func (t MockTool) McpManifest() tools.McpManifest {
+	properties := make(map[string]parameters.ParameterMcpManifest)
+	required := make([]string, 0)
+	authParams := make(map[string][]string)
+
+	for _, p := range t.Params {
+		name := p.GetName()
+		paramManifest, authParamList := p.McpManifest()
+		properties[name] = paramManifest
+		required = append(required, name)
+
+		if len(authParamList) > 0 {
+			authParams[name] = authParamList
+		}
+	}
+
+	toolsSchema := parameters.McpToolsSchema{
+		Type:       "object",
+		Properties: properties,
+		Required:   required,
+	}
+
+	mcpManifest := tools.McpManifest{
+		Name:        t.Name,
+		Description: t.Description,
+		InputSchema: toolsSchema,
+	}
+
+	if len(authParams) > 0 {
+		mcpManifest.Metadata = map[string]any{
+			"toolbox/authParams": authParams,
+		}
+	}
+
+	return mcpManifest
+}
+
+func (t MockTool) GetAuthTokenHeaderName(tools.SourceProvider) (string, error) {
+	return "Authorization", nil
+}
+
+// MockPrompt is used to mock prompts in tests
+type MockPrompt struct {
+	Name        string
+	Description string
+	Args        prompts.Arguments
+}
+
+func (p MockPrompt) SubstituteParams(vals parameters.ParamValues) (any, error) {
+	return []prompts.Message{
+		{
+			Role:    "user",
+			Content: fmt.Sprintf("substituted %s", p.Name),
+		},
+	}, nil
+}
+
+func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
+	var params parameters.Parameters
+	for _, arg := range p.Args {
+		params = append(params, arg.Parameter)
+	}
+	return parameters.ParseParams(params, data, claimsMap)
+}
+
+func (p MockPrompt) Manifest() prompts.Manifest {
+	var argManifests []parameters.ParameterManifest
+	for _, arg := range p.Args {
+		argManifests = append(argManifests, arg.Manifest())
+	}
+	return prompts.Manifest{
+		Description: p.Description,
+		Arguments:   argManifests,
+	}
+}
+
+func (p MockPrompt) McpManifest() prompts.McpManifest {
+	return prompts.GetMcpManifest(p.Name, p.Description, p.Args)
+}
+
+func (p MockPrompt) ToConfig() prompts.PromptConfig {
+	return nil
+}
+
 var tool1 = MockTool{
 	Name:   "no_params",
 	Params: []parameters.Parameter{},

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()
+			var clientServerErr *util.ClientServerError
-			if errors.Is(err, util.ErrUnauthorized) {
+			if errors.As(err, &clientServerErr) {
-				w.WriteHeader(http.StatusUnauthorized)
+				switch clientServerErr.Code {
-			} else if strings.Contains(errStr, "Error 401") {
+				case http.StatusUnauthorized:
-				w.WriteHeader(http.StatusUnauthorized)
+					w.WriteHeader(http.StatusUnauthorized)
-			} else if strings.Contains(errStr, "Error 403") {
+				case http.StatusForbidden:
-				w.WriteHeader(http.StatusForbidden)
+					w.WriteHeader(http.StatusForbidden)
+				}
 			}
 		}
 	}

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()
+		var tbErr util.ToolboxError
-		// Missing authService tokens.
+
-		if errors.Is(err, util.ErrUnauthorized) {
+		if errors.As(err, &tbErr) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+			switch tbErr.Category() {
-		}
+			case util.CategoryAgent:
-		// Upstream auth error
+				// MCP - Tool execution error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
+				// Return SUCCESS but with IsError: true
-			if clientAuth {
+				text := TextContent{
-				// Error with client credentials should pass down to the client
+					Type: "text",
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+					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)

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()
+		var tbErr util.ToolboxError
-		// Missing authService tokens.
+
-		if errors.Is(err, util.ErrUnauthorized) {
+		if errors.As(err, &tbErr) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+			switch tbErr.Category() {
-		}
+			case util.CategoryAgent:
-		// Upstream auth error
+				// MCP - Tool execution error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
+				// Return SUCCESS but with IsError: true
-			if clientAuth {
+				text := TextContent{
-				// Error with client credentials should pass down to the client
+					Type: "text",
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+					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)

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()
+		var tbErr util.ToolboxError
-		// Missing authService tokens.
+
-		if errors.Is(err, util.ErrUnauthorized) {
+		if errors.As(err, &tbErr) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+			switch tbErr.Category() {
-		}
+			case util.CategoryAgent:
-		// Upstream auth error
+				// MCP - Tool execution error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
+				// Return SUCCESS but with IsError: true
-			if clientAuth {
+				text := TextContent{
-				// Error with client credentials should pass down to the client
+					Type: "text",
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+					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)

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()
+		var tbErr util.ToolboxError
-		// Missing authService tokens.
+
-		if errors.Is(err, util.ErrUnauthorized) {
+		if errors.As(err, &tbErr) {
-			return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+			switch tbErr.Category() {
-		}
+			case util.CategoryAgent:
-		// Upstream auth error
+				// MCP - Tool execution error
-		if strings.Contains(errStr, "Error 401") || strings.Contains(errStr, "Error 403") {
+				// Return SUCCESS but with IsError: true
-			if clientAuth {
+				text := TextContent{
-				// Error with client credentials should pass down to the client
+					Type: "text",
-				return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
+					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)

internal/server/mocks.go

@@ -1,159 +0,0 @@
-// 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 server
-
-import (
-	"context"
-	"fmt"
-
-	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
-	"github.com/googleapis/genai-toolbox/internal/prompts"
-	"github.com/googleapis/genai-toolbox/internal/tools"
-	"github.com/googleapis/genai-toolbox/internal/util/parameters"
-)
-
-// MockTool is used to mock tools in tests
-type MockTool struct {
-	Name                         string
-	Description                  string
-	Params                       []parameters.Parameter
-	manifest                     tools.Manifest
-	unauthorized                 bool
-	requiresClientAuthrorization bool
-}
-
-func (t MockTool) Invoke(context.Context, tools.SourceProvider, parameters.ParamValues, tools.AccessToken) (any, error) {
-	mock := []any{t.Name}
-	return mock, nil
-}
-
-func (t MockTool) ToConfig() tools.ToolConfig {
-	return nil
-}
-
-// claims is a map of user info decoded from an auth token
-func (t MockTool) ParseParams(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
-	return parameters.ParseParams(t.Params, data, claimsMap)
-}
-
-func (t MockTool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {
-	return parameters.EmbedParams(ctx, t.Params, paramValues, embeddingModelsMap, nil)
-}
-
-func (t MockTool) Manifest() tools.Manifest {
-	pMs := make([]parameters.ParameterManifest, 0, len(t.Params))
-	for _, p := range t.Params {
-		pMs = append(pMs, p.Manifest())
-	}
-	return tools.Manifest{Description: t.Description, Parameters: pMs}
-}
-
-func (t MockTool) Authorized(verifiedAuthServices []string) bool {
-	// defaulted to true
-	return !t.unauthorized
-}
-
-func (t MockTool) RequiresClientAuthorization(tools.SourceProvider) (bool, error) {
-	// defaulted to false
-	return t.requiresClientAuthrorization, nil
-}
-
-func (t MockTool) GetParameters() parameters.Parameters {
-	return t.Params
-}
-
-func (t MockTool) McpManifest() tools.McpManifest {
-	properties := make(map[string]parameters.ParameterMcpManifest)
-	required := make([]string, 0)
-	authParams := make(map[string][]string)
-
-	for _, p := range t.Params {
-		name := p.GetName()
-		paramManifest, authParamList := p.McpManifest()
-		properties[name] = paramManifest
-		required = append(required, name)
-
-		if len(authParamList) > 0 {
-			authParams[name] = authParamList
-		}
-	}
-
-	toolsSchema := parameters.McpToolsSchema{
-		Type:       "object",
-		Properties: properties,
-		Required:   required,
-	}
-
-	mcpManifest := tools.McpManifest{
-		Name:        t.Name,
-		Description: t.Description,
-		InputSchema: toolsSchema,
-	}
-
-	if len(authParams) > 0 {
-		mcpManifest.Metadata = map[string]any{
-			"toolbox/authParams": authParams,
-		}
-	}
-
-	return mcpManifest
-}
-
-func (t MockTool) GetAuthTokenHeaderName(tools.SourceProvider) (string, error) {
-	return "Authorization", nil
-}
-
-// MockPrompt is used to mock prompts in tests
-type MockPrompt struct {
-	Name        string
-	Description string
-	Args        prompts.Arguments
-}
-
-func (p MockPrompt) SubstituteParams(vals parameters.ParamValues) (any, error) {
-	return []prompts.Message{
-		{
-			Role:    "user",
-			Content: fmt.Sprintf("substituted %s", p.Name),
-		},
-	}, nil
-}
-
-func (p MockPrompt) ParseArgs(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {
-	var params parameters.Parameters
-	for _, arg := range p.Args {
-		params = append(params, arg.Parameter)
-	}
-	return parameters.ParseParams(params, data, claimsMap)
-}
-
-func (p MockPrompt) Manifest() prompts.Manifest {
-	var argManifests []parameters.ParameterManifest
-	for _, arg := range p.Args {
-		argManifests = append(argManifests, arg.Manifest())
-	}
-	return prompts.Manifest{
-		Description: p.Description,
-		Arguments:   argManifests,
-	}
-}
-
-func (p MockPrompt) McpManifest() prompts.McpManifest {
-	return prompts.GetMcpManifest(p.Name, p.Description, p.Args)
-}
-
-func (p MockPrompt) ToConfig() prompts.PromptConfig {
-	return nil
-}

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.ProcessGcpError(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) {

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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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 {
+	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
+	if !ok || location == "" {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
+	if !ok || cluster == "" {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+		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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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 {
+	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
+	if !ok || location == "" {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
+	if !ok || cluster == "" {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a string", nil)
 	}
 	instance, ok := paramsMap["instance"].(string)
-	if !ok {
+	if !ok || instance == "" {
-		return nil, fmt.Errorf("invalid 'instance' parameter; expected a string")
+		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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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 {
+	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
+	if !ok || location == "" {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
+	if !ok || cluster == "" {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'cluster' parameter; expected a string", nil)
 	}
 	user, ok := paramsMap["user"].(string)
-	if !ok {
+	if !ok || user == "" {
-		return nil, fmt.Errorf("invalid 'user' parameter; expected a string")
+		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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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 {
+	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+		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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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 {
+	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+		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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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 {
+	if !ok || project == "" {
-		return nil, fmt.Errorf("invalid or missing 'project' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'project' parameter; expected a string", nil)
 	}
 	location, ok := paramsMap["location"].(string)
-	if !ok {
+	if !ok || location == "" {
-		return nil, fmt.Errorf("invalid 'location' parameter; expected a string")
+		return nil, util.NewAgentError("invalid or missing 'location' parameter; expected a string", nil)
 	}
 	cluster, ok := paramsMap["cluster"].(string)
-	if !ok {
+	if !ok || cluster == "" {
-		return nil, fmt.Errorf("invalid 'cluster' parameter; expected a string")
+		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.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

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
+			return nil, util.ProcessGcpError(err)
-		} else if op != nil {
+		}
+		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) {

internal/tools/alloydbainl/alloydbainl.go

@@ -17,12 +17,14 @@ package alloydbainl
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	"github.com/jackc/pgx/v5/pgxpool"
 )
@@ -127,10 +129,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	sliceParams := params.AsSlice()
@@ -143,7 +145,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	resp, err := source.RunSQL(ctx, t.Statement, allParamValues)
 	if err != nil {
-		return nil, fmt.Errorf("%w. Query: %v , Values: %v. Toolbox v0.19.0+ is only compatible with AlloyDB AI NL v1.0.3+. Please ensure that you are using the latest AlloyDB AI NL extension", err, t.Statement, allParamValues)
+		return nil, util.NewClientServerError(fmt.Sprintf("error running SQL query: %v. Query: %v , Values: %v. Toolbox v0.19.0+ is only compatible with AlloyDB AI NL v1.0.3+. Please ensure that you are using the latest AlloyDB AI NL extension", err, t.Statement, allParamValues), http.StatusBadRequest, err)
 	}
 	return resp, nil
 }

internal/tools/bigquery/bigqueryanalyzecontribution/bigqueryanalyzecontribution.go

@@ -17,6 +17,7 @@ package bigqueryanalyzecontribution
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
@@ -27,6 +28,7 @@ import (
 	bigqueryds "github.com/googleapis/genai-toolbox/internal/sources/bigquery"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	bqutil "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigquerycommon"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	bigqueryrestapi "google.golang.org/api/bigquery/v2"
 )
@@ -154,21 +156,21 @@ func (t Tool) ToConfig() tools.ToolConfig {
 }
 
 // Invoke runs the contribution analysis.
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	inputData, ok := paramsMap["input_data"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast input_data parameter %s", paramsMap["input_data"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast input_data parameter %s", paramsMap["input_data"]), nil)
 	}
 
 	bqClient, restService, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	modelID := fmt.Sprintf("contribution_analysis_model_%s", strings.ReplaceAll(uuid.New().String(), "-", ""))
@@ -186,7 +188,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			}
 			options = append(options, fmt.Sprintf("DIMENSION_ID_COLS = [%s]", strings.Join(strCols, ", ")))
 		} else {
-			return nil, fmt.Errorf("unable to cast dimension_id_cols parameter %s", paramsMap["dimension_id_cols"])
+			return nil, util.NewAgentError(fmt.Sprintf("unable to cast dimension_id_cols parameter %s", paramsMap["dimension_id_cols"]), nil)
 		}
 	}
 	if val, ok := paramsMap["top_k_insights_by_apriori_support"]; ok {
@@ -195,7 +197,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if val, ok := paramsMap["pruning_method"].(string); ok {
 		upperVal := strings.ToUpper(val)
 		if upperVal != "NO_PRUNING" && upperVal != "PRUNE_REDUNDANT_INSIGHTS" {
-			return nil, fmt.Errorf("invalid pruning_method: %s", val)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid pruning_method: %s", val), nil)
 		}
 		options = append(options, fmt.Sprintf("PRUNING_METHOD = '%s'", upperVal))
 	}
@@ -207,7 +209,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			var connProps []*bigqueryapi.ConnectionProperty
 			session, err := source.BigQuerySession()(ctx)
 			if err != nil {
-				return nil, fmt.Errorf("failed to get BigQuery session: %w", err)
+				return nil, util.NewClientServerError("failed to get BigQuery session", http.StatusInternalServerError, err)
 			}
 			if session != nil {
 				connProps = []*bigqueryapi.ConnectionProperty{
@@ -216,22 +218,22 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			}
 			dryRunJob, err := bqutil.DryRunQuery(ctx, restService, source.BigQueryClient().Project(), source.BigQueryClient().Location, inputData, nil, connProps)
 			if err != nil {
-				return nil, fmt.Errorf("query validation failed: %w", err)
+				return nil, util.ProcessGcpError(err)
 			}
 			statementType := dryRunJob.Statistics.Query.StatementType
 			if statementType != "SELECT" {
-				return nil, fmt.Errorf("the 'input_data' parameter only supports a table ID or a SELECT query. The provided query has statement type '%s'", statementType)
+				return nil, util.NewAgentError(fmt.Sprintf("the 'input_data' parameter only supports a table ID or a SELECT query. The provided query has statement type '%s'", statementType), nil)
 			}
 
 			queryStats := dryRunJob.Statistics.Query
 			if queryStats != nil {
 				for _, tableRef := range queryStats.ReferencedTables {
 					if !source.IsDatasetAllowed(tableRef.ProjectId, tableRef.DatasetId) {
-						return nil, fmt.Errorf("query in input_data accesses dataset '%s.%s', which is not in the allowed list", tableRef.ProjectId, tableRef.DatasetId)
+						return nil, util.NewAgentError(fmt.Sprintf("query in input_data accesses dataset '%s.%s', which is not in the allowed list", tableRef.ProjectId, tableRef.DatasetId), nil)
 					}
 				}
 			} else {
-				return nil, fmt.Errorf("could not analyze query in input_data to validate against allowed datasets")
+				return nil, util.NewAgentError("could not analyze query in input_data to validate against allowed datasets", nil)
 			}
 		}
 		inputDataSource = fmt.Sprintf("(%s)", inputData)
@@ -245,10 +247,10 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			case 2: // dataset.table
 				projectID, datasetID = source.BigQueryClient().Project(), parts[0]
 			default:
-				return nil, fmt.Errorf("invalid table ID format for 'input_data': %q. Expected 'dataset.table' or 'project.dataset.table'", inputData)
+				return nil, util.NewAgentError(fmt.Sprintf("invalid table ID format for 'input_data': %q. Expected 'dataset.table' or 'project.dataset.table'", inputData), nil)
 			}
 			if !source.IsDatasetAllowed(projectID, datasetID) {
-				return nil, fmt.Errorf("access to dataset '%s.%s' (from table '%s') is not allowed", projectID, datasetID, inputData)
+				return nil, util.NewAgentError(fmt.Sprintf("access to dataset '%s.%s' (from table '%s') is not allowed", projectID, datasetID, inputData), nil)
 			}
 		}
 		inputDataSource = fmt.Sprintf("SELECT * FROM `%s`", inputData)
@@ -268,7 +270,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Otherwise, a new session will be created by the first query.
 	session, err := source.BigQuerySession()(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get BigQuery session: %w", err)
+		return nil, util.NewClientServerError("failed to get BigQuery session", http.StatusInternalServerError, err)
 	}
 
 	if session != nil {
@@ -281,15 +283,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	}
 	createModelJob, err := createModelQuery.Run(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to start create model job: %w", err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	status, err := createModelJob.Wait(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to wait for create model job: %w", err)
+		return nil, util.ProcessGcpError(err)
 	}
 	if err := status.Err(); err != nil {
-		return nil, fmt.Errorf("create model job failed: %w", err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	// Determine the session ID to use for subsequent queries.
@@ -300,12 +302,17 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	} else if status.Statistics != nil && status.Statistics.SessionInfo != nil {
 		sessionID = status.Statistics.SessionInfo.SessionID
 	} else {
-		return nil, fmt.Errorf("failed to get or create a BigQuery session ID")
+		return nil, util.NewClientServerError("failed to get or create a BigQuery session ID", http.StatusInternalServerError, nil)
 	}
 
 	getInsightsSQL := fmt.Sprintf("SELECT * FROM ML.GET_INSIGHTS(MODEL %s)", modelID)
 	connProps := []*bigqueryapi.ConnectionProperty{{Key: "session_id", Value: sessionID}}
-	return source.RunSQL(ctx, bqClient, getInsightsSQL, "SELECT", nil, connProps)
+
+	resp, err := source.RunSQL(ctx, bqClient, getInsightsSQL, "SELECT", nil, connProps)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/bigquery/bigqueryconversationalanalytics/bigqueryconversationalanalytics.go

@@ -172,10 +172,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	var tokenStr string
@@ -184,26 +184,26 @@ 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 {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	} else {
 		// Get a token source for the Gemini Data Analytics API.
 		tokenSource, err := source.BigQueryTokenSourceWithScope(ctx, nil)
 		if err != nil {
-			return nil, fmt.Errorf("failed to get token source: %w", err)
+			return nil, util.NewClientServerError("failed to get token source", http.StatusInternalServerError, err)
 		}
 
 		// Use cloud-platform token source for Gemini Data Analytics API
 		if tokenSource == nil {
-			return nil, fmt.Errorf("cloud-platform token source is missing")
+			return nil, util.NewClientServerError("cloud-platform token source is missing", http.StatusInternalServerError, nil)
 		}
 		token, err := tokenSource.Token()
 		if err != nil {
-			return nil, fmt.Errorf("failed to get token from cloud-platform token source: %w", err)
+			return nil, util.NewClientServerError("failed to get token from cloud-platform token source", http.StatusInternalServerError, err)
 		}
 		tokenStr = token.AccessToken
 	}
@@ -218,14 +218,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	var tableRefs []BQTableReference
 	if tableRefsJSON != "" {
 		if err := json.Unmarshal([]byte(tableRefsJSON), &tableRefs); err != nil {
-			return nil, fmt.Errorf("failed to parse 'table_references' JSON string: %w", err)
+			return nil, util.NewAgentError("failed to parse 'table_references' JSON string", err)
 		}
 	}
 
 	if len(source.BigQueryAllowedDatasets()) > 0 {
 		for _, tableRef := range tableRefs {
 			if !source.IsDatasetAllowed(tableRef.ProjectID, tableRef.DatasetID) {
-				return nil, fmt.Errorf("access to dataset '%s.%s' (from table '%s') is not allowed", tableRef.ProjectID, tableRef.DatasetID, tableRef.TableID)
+				return nil, util.NewAgentError(fmt.Sprintf("access to dataset '%s.%s' (from table '%s') is not allowed", tableRef.ProjectID, tableRef.DatasetID, tableRef.TableID), nil)
 			}
 		}
 	}
@@ -258,7 +258,8 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Call the streaming API
 	response, err := getStream(caURL, payload, headers, source.GetMaxQueryResultRows())
 	if err != nil {
-		return nil, fmt.Errorf("failed to get response from conversational analytics API: %w", err)
+		// getStream wraps network errors or non-200 responses
+		return nil, util.NewClientServerError("failed to get response from conversational analytics API", http.StatusInternalServerError, err)
 	}
 
 	return response, nil

internal/tools/bigquery/bigqueryexecutesql/bigqueryexecutesql.go

@@ -18,6 +18,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"strings"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
@@ -152,25 +153,25 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	sql, ok := paramsMap["sql"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast sql parameter %s", paramsMap["sql"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast sql parameter %s", paramsMap["sql"]), nil)
 	}
 	dryRun, ok := paramsMap["dry_run"].(bool)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast dry_run parameter %s", paramsMap["dry_run"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast dry_run parameter %s", paramsMap["dry_run"]), nil)
 	}
 
 	bqClient, restService, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	var connProps []*bigqueryapi.ConnectionProperty
@@ -178,7 +179,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if source.BigQueryWriteMode() == bigqueryds.WriteModeProtected {
 		session, err = source.BigQuerySession()(ctx)
 		if err != nil {
-			return nil, fmt.Errorf("failed to get BigQuery session for protected mode: %w", err)
+			return nil, util.NewClientServerError("failed to get BigQuery session for protected mode", http.StatusInternalServerError, err)
 		}
 		connProps = []*bigqueryapi.ConnectionProperty{
 			{Key: "session_id", Value: session.ID},
@@ -187,7 +188,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	dryRunJob, err := bqutil.DryRunQuery(ctx, restService, bqClient.Project(), bqClient.Location, sql, nil, connProps)
 	if err != nil {
-		return nil, fmt.Errorf("query validation failed: %w", err)
+		return nil, util.NewClientServerError("query validation failed", http.StatusInternalServerError, err)
 	}
 
 	statementType := dryRunJob.Statistics.Query.StatementType
@@ -195,13 +196,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	switch source.BigQueryWriteMode() {
 	case bigqueryds.WriteModeBlocked:
 		if statementType != "SELECT" {
-			return nil, fmt.Errorf("write mode is 'blocked', only SELECT statements are allowed")
+			return nil, util.NewAgentError("write mode is 'blocked', only SELECT statements are allowed", nil)
 		}
 	case bigqueryds.WriteModeProtected:
 		if dryRunJob.Configuration != nil && dryRunJob.Configuration.Query != nil {
 			if dest := dryRunJob.Configuration.Query.DestinationTable; dest != nil && dest.DatasetId != session.DatasetID {
-				return nil, fmt.Errorf("protected write mode only supports SELECT statements, or write operations in the anonymous "+
+				return nil, util.NewAgentError(fmt.Sprintf("protected write mode only supports SELECT statements, or write operations in the anonymous "+
-					"dataset of a BigQuery session, but destination was %q", dest.DatasetId)
+					"dataset of a BigQuery session, but destination was %q", dest.DatasetId), nil)
 			}
 		}
 	}
@@ -209,11 +210,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if len(source.BigQueryAllowedDatasets()) > 0 {
 		switch statementType {
 		case "CREATE_SCHEMA", "DROP_SCHEMA", "ALTER_SCHEMA":
-			return nil, fmt.Errorf("dataset-level operations like '%s' are not allowed when dataset restrictions are in place", statementType)
+			return nil, util.NewAgentError(fmt.Sprintf("dataset-level operations like '%s' are not allowed when dataset restrictions are in place", statementType), nil)
 		case "CREATE_FUNCTION", "CREATE_TABLE_FUNCTION", "CREATE_PROCEDURE":
-			return nil, fmt.Errorf("creating stored routines ('%s') is not allowed when dataset restrictions are in place, as their contents cannot be safely analyzed", statementType)
+			return nil, util.NewAgentError(fmt.Sprintf("creating stored routines ('%s') is not allowed when dataset restrictions are in place, as their contents cannot be safely analyzed", statementType), nil)
 		case "CALL":
-			return nil, fmt.Errorf("calling stored procedures ('%s') is not allowed when dataset restrictions are in place, as their contents cannot be safely analyzed", statementType)
+			return nil, util.NewAgentError(fmt.Sprintf("calling stored procedures ('%s') is not allowed when dataset restrictions are in place, as their contents cannot be safely analyzed", statementType), nil)
 		}
 
 		// Use a map to avoid duplicate table names.
@@ -244,7 +245,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			parsedTables, parseErr := bqutil.TableParser(sql, source.BigQueryClient().Project())
 			if parseErr != nil {
 				// If parsing fails (e.g., EXECUTE IMMEDIATE), we cannot guarantee safety, so we must fail.
-				return nil, fmt.Errorf("could not parse tables from query to validate against allowed datasets: %w", parseErr)
+				return nil, util.NewAgentError("could not parse tables from query to validate against allowed datasets", parseErr)
 			}
 			tableNames = parsedTables
 		}
@@ -254,7 +255,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			if len(parts) == 3 {
 				projectID, datasetID := parts[0], parts[1]
 				if !source.IsDatasetAllowed(projectID, datasetID) {
-					return nil, fmt.Errorf("query accesses dataset '%s.%s', which is not in the allowed list", projectID, datasetID)
+					return nil, util.NewAgentError(fmt.Sprintf("query accesses dataset '%s.%s', which is not in the allowed list", projectID, datasetID), nil)
 				}
 			}
 		}
@@ -264,7 +265,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		if dryRunJob != nil {
 			jobJSON, err := json.MarshalIndent(dryRunJob, "", "  ")
 			if err != nil {
-				return nil, fmt.Errorf("failed to marshal dry run job to JSON: %w", err)
+				return nil, util.NewClientServerError("failed to marshal dry run job to JSON", http.StatusInternalServerError, err)
 			}
 			return string(jobJSON), nil
 		}
@@ -275,10 +276,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Log the query executed for debugging.
 	logger, err := util.LoggerFromContext(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("error getting logger: %s", err)
+		return nil, util.NewClientServerError("error getting logger", http.StatusInternalServerError, err)
 	}
 	logger.DebugContext(ctx, fmt.Sprintf("executing `%s` tool query: %s", resourceType, sql))
-	return source.RunSQL(ctx, bqClient, sql, statementType, nil, connProps)
+	resp, err := source.RunSQL(ctx, bqClient, sql, statementType, nil, connProps)
+	if err != nil {
+		return nil, util.NewClientServerError("error running sql", http.StatusInternalServerError, err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/bigquery/bigqueryforecast/bigqueryforecast.go

@@ -17,6 +17,7 @@ package bigqueryforecast
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
@@ -133,34 +134,34 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	historyData, ok := paramsMap["history_data"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast history_data parameter %v", paramsMap["history_data"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast history_data parameter %v", paramsMap["history_data"]), nil)
 	}
 	timestampCol, ok := paramsMap["timestamp_col"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast timestamp_col parameter %v", paramsMap["timestamp_col"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast timestamp_col parameter %v", paramsMap["timestamp_col"]), nil)
 	}
 	dataCol, ok := paramsMap["data_col"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast data_col parameter %v", paramsMap["data_col"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast data_col parameter %v", paramsMap["data_col"]), nil)
 	}
 	idColsRaw, ok := paramsMap["id_cols"].([]any)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast id_cols parameter %v", paramsMap["id_cols"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast id_cols parameter %v", paramsMap["id_cols"]), nil)
 	}
 	var idCols []string
 	for _, v := range idColsRaw {
 		s, ok := v.(string)
 		if !ok {
-			return nil, fmt.Errorf("id_cols contains non-string value: %v", v)
+			return nil, util.NewAgentError(fmt.Sprintf("id_cols contains non-string value: %v", v), nil)
 		}
 		idCols = append(idCols, s)
 	}
@@ -169,13 +170,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		if h, ok := paramsMap["horizon"].(float64); ok {
 			horizon = int(h)
 		} else {
-			return nil, fmt.Errorf("unable to cast horizon parameter %v", paramsMap["horizon"])
+			return nil, util.NewAgentError(fmt.Sprintf("unable to cast horizon parameter %v", paramsMap["horizon"]), nil)
 		}
 	}
 
 	bqClient, restService, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	var historyDataSource string
@@ -185,7 +186,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			var connProps []*bigqueryapi.ConnectionProperty
 			session, err := source.BigQuerySession()(ctx)
 			if err != nil {
-				return nil, fmt.Errorf("failed to get BigQuery session: %w", err)
+				return nil, util.NewClientServerError("failed to get BigQuery session", http.StatusInternalServerError, err)
 			}
 			if session != nil {
 				connProps = []*bigqueryapi.ConnectionProperty{
@@ -194,22 +195,22 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			}
 			dryRunJob, err := bqutil.DryRunQuery(ctx, restService, source.BigQueryClient().Project(), source.BigQueryClient().Location, historyData, nil, connProps)
 			if err != nil {
-				return nil, fmt.Errorf("query validation failed: %w", err)
+				return nil, util.ProcessGcpError(err)
 			}
 			statementType := dryRunJob.Statistics.Query.StatementType
 			if statementType != "SELECT" {
-				return nil, fmt.Errorf("the 'history_data' parameter only supports a table ID or a SELECT query. The provided query has statement type '%s'", statementType)
+				return nil, util.NewAgentError(fmt.Sprintf("the 'history_data' parameter only supports a table ID or a SELECT query. The provided query has statement type '%s'", statementType), nil)
 			}
 
 			queryStats := dryRunJob.Statistics.Query
 			if queryStats != nil {
 				for _, tableRef := range queryStats.ReferencedTables {
 					if !source.IsDatasetAllowed(tableRef.ProjectId, tableRef.DatasetId) {
-						return nil, fmt.Errorf("query in history_data accesses dataset '%s.%s', which is not in the allowed list", tableRef.ProjectId, tableRef.DatasetId)
+						return nil, util.NewAgentError(fmt.Sprintf("query in history_data accesses dataset '%s.%s', which is not in the allowed list", tableRef.ProjectId, tableRef.DatasetId), nil)
 					}
 				}
 			} else {
-				return nil, fmt.Errorf("could not analyze query in history_data to validate against allowed datasets")
+				return nil, util.NewAgentError("could not analyze query in history_data to validate against allowed datasets", nil)
 			}
 		}
 		historyDataSource = fmt.Sprintf("(%s)", historyData)
@@ -226,11 +227,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 				projectID = source.BigQueryClient().Project()
 				datasetID = parts[0]
 			default:
-				return nil, fmt.Errorf("invalid table ID format for 'history_data': %q. Expected 'dataset.table' or 'project.dataset.table'", historyData)
+				return nil, util.NewAgentError(fmt.Sprintf("invalid table ID format for 'history_data': %q. Expected 'dataset.table' or 'project.dataset.table'", historyData), nil)
 			}
 
 			if !source.IsDatasetAllowed(projectID, datasetID) {
-				return nil, fmt.Errorf("access to dataset '%s.%s' (from table '%s') is not allowed", projectID, datasetID, historyData)
+				return nil, util.NewAgentError(fmt.Sprintf("access to dataset '%s.%s' (from table '%s') is not allowed", projectID, datasetID, historyData), nil)
 			}
 		}
 		historyDataSource = fmt.Sprintf("TABLE `%s`", historyData)
@@ -243,15 +244,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	}
 	sql := fmt.Sprintf(`SELECT * 
 		FROM AI.FORECAST(
-			%s,
+            %s,
-			data_col => '%s',
+            data_col => '%s',
-			timestamp_col => '%s',
+            timestamp_col => '%s',
-			horizon => %d%s)`,
+            horizon => %d%s)`,
 		historyDataSource, dataCol, timestampCol, horizon, idColsArg)
 
 	session, err := source.BigQuerySession()(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get BigQuery session: %w", err)
+		return nil, util.NewClientServerError("failed to get BigQuery session", http.StatusInternalServerError, err)
 	}
 	var connProps []*bigqueryapi.ConnectionProperty
 	if session != nil {
@@ -264,11 +265,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Log the query executed for debugging.
 	logger, err := util.LoggerFromContext(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("error getting logger: %s", err)
+		return nil, util.NewClientServerError("error getting logger", http.StatusInternalServerError, err)
 	}
 	logger.DebugContext(ctx, fmt.Sprintf("executing `%s` tool query: %s", resourceType, sql))
 
-	return source.RunSQL(ctx, bqClient, sql, "SELECT", nil, connProps)
+	resp, err := source.RunSQL(ctx, bqClient, sql, "SELECT", nil, connProps)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/bigquery/bigquerygetdatasetinfo/bigquerygetdatasetinfo.go

@@ -17,6 +17,7 @@ package bigquerygetdatasetinfo
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
 	yaml "github.com/goccy/go-yaml"
@@ -24,6 +25,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	bqutil "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigquerycommon"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	bigqueryrestapi "google.golang.org/api/bigquery/v2"
 )
@@ -120,38 +122,38 @@ type Tool struct {
 func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
-
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
 	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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	projectId, ok := mapParams[projectKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", projectKey)
+		// Updated: Use fmt.Sprintf for formatting, pass nil as cause
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", projectKey), nil)
 	}
 
 	datasetId, ok := mapParams[datasetKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", datasetKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", datasetKey), nil)
 	}
 
 	bqClient, _, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	if !source.IsDatasetAllowed(projectId, datasetId) {
-		return nil, fmt.Errorf("access denied to dataset '%s' because it is not in the configured list of allowed datasets for project '%s'", datasetId, projectId)
+		return nil, util.NewClientServerError(fmt.Sprintf("access denied to dataset '%s' because it is not in the configured list of allowed datasets for project '%s'", datasetId, projectId), http.StatusInternalServerError, nil)
 	}
 
 	dsHandle := bqClient.DatasetInProject(projectId, datasetId)
 
 	metadata, err := dsHandle.Metadata(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get metadata for dataset %s (in project %s): %w", datasetId, projectId, err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	return metadata, nil

internal/tools/bigquery/bigquerygettableinfo/bigquerygettableinfo.go

@@ -17,6 +17,7 @@ package bigquerygettableinfo
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
 	yaml "github.com/goccy/go-yaml"
@@ -24,6 +25,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	bqutil "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigquerycommon"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	bigqueryrestapi "google.golang.org/api/bigquery/v2"
 )
@@ -125,35 +127,35 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	projectId, ok := mapParams[projectKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", projectKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", projectKey), nil)
 	}
 
 	datasetId, ok := mapParams[datasetKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", datasetKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", datasetKey), nil)
 	}
 
 	tableId, ok := mapParams[tableKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", tableKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", tableKey), nil)
 	}
 
 	if !source.IsDatasetAllowed(projectId, datasetId) {
-		return nil, fmt.Errorf("access denied to dataset '%s' because it is not in the configured list of allowed datasets for project '%s'", datasetId, projectId)
+		return nil, util.NewClientServerError(fmt.Sprintf("access denied to dataset '%s' because it is not in the configured list of allowed datasets for project '%s'", datasetId, projectId), http.StatusInternalServerError, nil)
 	}
 
 	bqClient, _, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	dsHandle := bqClient.DatasetInProject(projectId, datasetId)
@@ -161,7 +163,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	metadata, err := tableHandle.Metadata(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get metadata for table %s.%s.%s: %w", projectId, datasetId, tableId, err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	return metadata, nil

internal/tools/bigquery/bigquerylistdatasetids/bigquerylistdatasetids.go

@@ -17,12 +17,14 @@ package bigquerylistdatasetids
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	bigqueryrestapi "google.golang.org/api/bigquery/v2"
 	"google.golang.org/api/iterator"
@@ -120,10 +122,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	if len(source.BigQueryAllowedDatasets()) > 0 {
@@ -132,12 +134,12 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	mapParams := params.AsMap()
 	projectId, ok := mapParams[projectKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", projectKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", projectKey), nil)
 	}
 
 	bqClient, _, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 	datasetIterator := bqClient.Datasets(ctx)
 	datasetIterator.ProjectID = projectId
@@ -149,7 +151,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			break
 		}
 		if err != nil {
-			return nil, fmt.Errorf("unable to iterate through datasets: %w", err)
+			return nil, util.ProcessGcpError(err)
 		}
 
 		// Remove leading and trailing quotes

internal/tools/bigquery/bigquerylisttableids/bigquerylisttableids.go

@@ -17,6 +17,7 @@ package bigquerylisttableids
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	bigqueryapi "cloud.google.com/go/bigquery"
 	yaml "github.com/goccy/go-yaml"
@@ -24,6 +25,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	bqutil "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigquerycommon"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	bigqueryrestapi "google.golang.org/api/bigquery/v2"
 	"google.golang.org/api/iterator"
@@ -123,31 +125,30 @@ type Tool struct {
 func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
-
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
 	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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	projectId, ok := mapParams[projectKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", projectKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", projectKey), nil)
 	}
 
 	datasetId, ok := mapParams[datasetKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", datasetKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", datasetKey), nil)
 	}
 
 	if !source.IsDatasetAllowed(projectId, datasetId) {
-		return nil, fmt.Errorf("access denied to dataset '%s' because it is not in the configured list of allowed datasets for project '%s'", datasetId, projectId)
+		return nil, util.NewClientServerError(fmt.Sprintf("access denied to dataset '%s' because it is not in the configured list of allowed datasets for project '%s'", datasetId, projectId), http.StatusInternalServerError, nil)
 	}
 
 	bqClient, _, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	dsHandle := bqClient.DatasetInProject(projectId, datasetId)
@@ -160,7 +161,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			break
 		}
 		if err != nil {
-			return nil, fmt.Errorf("failed to iterate through tables in dataset %s.%s: %w", projectId, datasetId, err)
+			return nil, util.ProcessGcpError(err)
 		}
 
 		// Remove leading and trailing quotes

internal/tools/bigquery/bigquerysearchcatalog/bigquerysearchcatalog.go

@@ -17,6 +17,7 @@ package bigquerysearchcatalog
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	dataplexapi "cloud.google.com/go/dataplex/apiv1"
@@ -26,6 +27,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	bigqueryds "github.com/googleapis/genai-toolbox/internal/sources/bigquery"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/iterator"
 )
@@ -186,28 +188,31 @@ func ExtractType(resourceString string) string {
 	return typeMap[resourceString[lastIndex+1:]]
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	pageSize := int32(paramsMap["pageSize"].(int))
 	prompt, _ := paramsMap["prompt"].(string)
+
 	projectIdSlice, err := parameters.ConvertAnySliceToTyped(paramsMap["projectIds"].([]any), "string")
 	if err != nil {
-		return nil, fmt.Errorf("can't convert projectIds to array of strings: %s", err)
+		return nil, util.NewAgentError(fmt.Sprintf("can't convert projectIds to array of strings: %s", err), err)
 	}
 	projectIds := projectIdSlice.([]string)
+
 	datasetIdSlice, err := parameters.ConvertAnySliceToTyped(paramsMap["datasetIds"].([]any), "string")
 	if err != nil {
-		return nil, fmt.Errorf("can't convert datasetIds to array of strings: %s", err)
+		return nil, util.NewAgentError(fmt.Sprintf("can't convert datasetIds to array of strings: %s", err), err)
 	}
 	datasetIds := datasetIdSlice.([]string)
+
 	typesSlice, err := parameters.ConvertAnySliceToTyped(paramsMap["types"].([]any), "string")
 	if err != nil {
-		return nil, fmt.Errorf("can't convert types to array of strings: %s", err)
+		return nil, util.NewAgentError(fmt.Sprintf("can't convert types to array of strings: %s", err), err)
 	}
 	types := typesSlice.([]string)
 
@@ -223,17 +228,17 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if source.UseClientAuthorization() {
 		tokenStr, err := accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 		catalogClient, err = dataplexClientCreator(tokenStr)
 		if err != nil {
-			return nil, fmt.Errorf("error creating client from OAuth access token: %w", err)
+			return nil, util.NewClientServerError("error creating client from OAuth access token", http.StatusInternalServerError, err)
 		}
 	}
 
 	it := catalogClient.SearchEntries(ctx, req)
 	if it == nil {
-		return nil, fmt.Errorf("failed to create search entries iterator for project %q", source.BigQueryProject())
+		return nil, util.NewClientServerError(fmt.Sprintf("failed to create search entries iterator for project %q", source.BigQueryProject()), http.StatusInternalServerError, nil)
 	}
 
 	var results []Response
@@ -243,7 +248,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			break
 		}
 		if err != nil {
-			break
+			return nil, util.ProcessGcpError(err)
 		}
 		entrySource := entry.DataplexEntry.GetEntrySource()
 		resp := Response{

internal/tools/bigquery/bigquerysql/bigquerysql.go

@@ -17,6 +17,7 @@ package bigquerysql
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"reflect"
 	"strings"
 
@@ -27,6 +28,7 @@ import (
 	bigqueryds "github.com/googleapis/genai-toolbox/internal/sources/bigquery"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	bqutil "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigquerycommon"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	bigqueryrestapi "google.golang.org/api/bigquery/v2"
 )
@@ -103,11 +105,10 @@ type Tool struct {
 func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
-
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
 	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", http.StatusInternalServerError, err)
 	}
 
 	highLevelParams := make([]bigqueryapi.QueryParameter, 0, len(t.Parameters))
@@ -116,7 +117,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	paramsMap := params.AsMap()
 	newStatement, err := parameters.ResolveTemplateParams(t.TemplateParameters, t.Statement, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract template params %w", err)
+		return nil, util.NewAgentError("unable to extract template params", err)
 	}
 
 	for _, p := range t.Parameters {
@@ -127,13 +128,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		if arrayParam, ok := p.(*parameters.ArrayParameter); ok {
 			arrayParamValue, ok := value.([]any)
 			if !ok {
-				return nil, fmt.Errorf("unable to convert parameter `%s` to []any", name)
+				return nil, util.NewAgentError(fmt.Sprintf("unable to convert parameter `%s` to []any", name), nil)
 			}
 			itemType := arrayParam.GetItems().GetType()
 			var err error
 			value, err = parameters.ConvertAnySliceToTyped(arrayParamValue, itemType)
 			if err != nil {
-				return nil, fmt.Errorf("unable to convert parameter `%s` from []any to typed slice: %w", name, err)
+				return nil, util.NewAgentError(fmt.Sprintf("unable to convert parameter `%s` from []any to typed slice", name), err)
 			}
 		}
 
@@ -161,7 +162,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			lowLevelParam.ParameterType.Type = "ARRAY"
 			itemType, err := bqutil.BQTypeStringFromToolType(arrayParam.GetItems().GetType())
 			if err != nil {
-				return nil, err
+				return nil, util.NewAgentError("unable to get BigQuery type from tool parameter type", err)
 			}
 			lowLevelParam.ParameterType.ArrayType = &bigqueryrestapi.QueryParameterType{Type: itemType}
 
@@ -178,7 +179,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			// Handle scalar types based on their defined type.
 			bqType, err := bqutil.BQTypeStringFromToolType(p.GetType())
 			if err != nil {
-				return nil, err
+				return nil, util.NewAgentError("unable to get BigQuery type from tool parameter type", err)
 			}
 			lowLevelParam.ParameterType.Type = bqType
 			lowLevelParam.ParameterValue.Value = fmt.Sprintf("%v", value)
@@ -190,7 +191,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if source.BigQuerySession() != nil {
 		session, err := source.BigQuerySession()(ctx)
 		if err != nil {
-			return nil, fmt.Errorf("failed to get BigQuery session: %w", err)
+			return nil, util.NewClientServerError("failed to get BigQuery session", http.StatusInternalServerError, err)
 		}
 		if session != nil {
 			// Add session ID to the connection properties for subsequent calls.
@@ -200,17 +201,20 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	bqClient, restService, err := source.RetrieveClientAndService(accessToken)
 	if err != nil {
-		return nil, err
+		return nil, util.NewClientServerError("failed to retrieve BigQuery client", http.StatusInternalServerError, err)
 	}
 
 	dryRunJob, err := bqutil.DryRunQuery(ctx, restService, bqClient.Project(), bqClient.Location, newStatement, lowLevelParams, connProps)
 	if err != nil {
-		return nil, fmt.Errorf("query validation failed: %w", err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	statementType := dryRunJob.Statistics.Query.StatementType
-
+	resp, err := source.RunSQL(ctx, bqClient, newStatement, statementType, highLevelParams, connProps)
-	return source.RunSQL(ctx, bqClient, newStatement, statementType, highLevelParams, connProps)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/bigtable/bigtable.go

@@ -17,12 +17,14 @@ package bigtable
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"cloud.google.com/go/bigtable"
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -96,24 +98,28 @@ type Tool struct {
 func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
-
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
 	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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	newStatement, err := parameters.ResolveTemplateParams(t.TemplateParameters, t.Statement, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract template params %w", err)
+		return nil, util.NewAgentError("unable to extract template params", err)
 	}
 
 	newParams, err := parameters.GetParams(t.Parameters, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract standard params %w", err)
+		return nil, util.NewAgentError("unable to extract standard params", err)
 	}
-	return source.RunSQL(ctx, newStatement, t.Parameters, newParams)
+
+	resp, err := source.RunSQL(ctx, newStatement, t.Parameters, newParams)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cassandra/cassandracql/cassandracql.go

@@ -4,7 +4,7 @@
 // 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
+//  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,
@@ -17,12 +17,14 @@ package cassandracql
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	gocql "github.com/apache/cassandra-gocql-driver/v2"
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -107,23 +109,27 @@ func (t Tool) Authorized(verifiedAuthServices []string) bool {
 }
 
 // Invoke implements tools.Tool.
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	newStatement, err := parameters.ResolveTemplateParams(t.TemplateParameters, t.Statement, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract template params %w", err)
+		return nil, util.NewAgentError("unable to extract template params", err)
 	}
 
 	newParams, err := parameters.GetParams(t.Parameters, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract standard params %w", err)
+		return nil, util.NewAgentError("unable to extract standard params", err)
 	}
-	return source.RunSQL(ctx, newStatement, newParams)
+	resp, err := source.RunSQL(ctx, newStatement, newParams)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 // Manifest implements tools.Tool.

internal/tools/clickhouse/clickhouseexecutesql/clickhouseexecutesql.go

@@ -17,11 +17,13 @@ package clickhouse
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -87,18 +89,22 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token 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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	sql, ok := paramsMap["sql"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to cast sql parameter %s", paramsMap["sql"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast sql parameter %s", paramsMap["sql"]), nil)
 	}
-	return source.RunSQL(ctx, sql, nil)
+	resp, err := source.RunSQL(ctx, sql, nil)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/clickhouse/clickhouselistdatabases/clickhouselistdatabases.go

@@ -17,11 +17,13 @@ package clickhouse
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -86,10 +88,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token 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", http.StatusInternalServerError, err)
 	}
 
 	// Query to list all databases
@@ -97,7 +99,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	out, err := source.RunSQL(ctx, query, nil)
 	if err != nil {
-		return nil, err
+		return nil, util.ProcessGeneralError(err)
 	}
 
 	return out, nil

internal/tools/clickhouse/clickhouselisttables/clickhouselisttables.go

@@ -17,11 +17,13 @@ package clickhouse
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -90,34 +92,37 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token 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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	database, ok := mapParams[databaseKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", databaseKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", databaseKey), nil)
 	}
+
 	// Query to list all tables in the specified database
+	// Note: formatting identifier directly is risky if input is untrusted, but standard for this tool structure.
 	query := fmt.Sprintf("SHOW TABLES FROM %s", database)
 
 	out, err := source.RunSQL(ctx, query, nil)
 	if err != nil {
-		return nil, err
+		return nil, util.ProcessGeneralError(err)
 	}
 
 	res, ok := out.([]any)
 	if !ok {
-		return nil, fmt.Errorf("unable to convert result to list")
+		return nil, util.NewClientServerError("unable to convert result to list", http.StatusInternalServerError, nil)
 	}
+
 	var tables []map[string]any
 	for _, item := range res {
 		tableMap, ok := item.(map[string]any)
 		if !ok {
-			return nil, fmt.Errorf("unexpected type in result: got %T, want map[string]any", item)
+			return nil, util.NewClientServerError(fmt.Sprintf("unexpected type in result: got %T, want map[string]any", item), http.StatusInternalServerError, nil)
 		}
 		tableMap["database"] = database
 		tables = append(tables, tableMap)

internal/tools/clickhouse/clickhousesql/clickhousesql.go

@@ -17,11 +17,13 @@ package clickhouse
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -88,24 +90,28 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token tools.AccessToken) (any, error) {
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, token 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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	newStatement, err := parameters.ResolveTemplateParams(t.TemplateParameters, t.Statement, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract template params: %w", err)
+		return nil, util.NewAgentError("unable to extract template params", err)
 	}
 
 	newParams, err := parameters.GetParams(t.Parameters, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract standard params: %w", err)
+		return nil, util.NewAgentError("unable to extract standard params", err)
 	}
 
-	return source.RunSQL(ctx, newStatement, newParams)
+	resp, err := source.RunSQL(ctx, newStatement, newParams)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudgda/cloudgda.go

@@ -18,11 +18,13 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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,17 +121,16 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-// Invoke executes the tool logic
+func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
-func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, params parameters.ParamValues, accessToken tools.AccessToken) (any, error) {
 	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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	query, ok := paramsMap["query"].(string)
 	if !ok {
-		return nil, fmt.Errorf("query parameter not found or not a string")
+		return nil, util.NewAgentError("query parameter not found or not a string", nil)
 	}
 
 	// Parse the access token if provided
@@ -138,7 +139,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		var err error
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 
@@ -154,9 +155,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	bodyBytes, err := json.Marshal(payload)
 	if err != nil {
-		return nil, fmt.Errorf("failed to marshal request payload: %w", err)
+		return nil, util.NewClientServerError("failed to marshal request payload", http.StatusInternalServerError, err)
 	}
-	return source.RunQuery(ctx, tokenStr, bodyBytes)
+
+	resp, err := source.RunQuery(ctx, tokenStr, bodyBytes)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcarefhirfetchpage/cloudhealthcarefhirfetchpage.go

@@ -17,11 +17,13 @@ package fhirfetchpage
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -93,24 +95,31 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	url, ok := params.AsMap()[pageURLKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", pageURLKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", pageURLKey), nil)
 	}
+
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.FHIRFetchPage(ctx, url, tokenStr)
+
+	resp, err := source.FHIRFetchPage(ctx, url, tokenStr)
+	if err != nil {
+
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcarefhirpatienteverything/cloudhealthcarefhirpatienteverything.go

@@ -17,6 +17,7 @@ package fhirpatienteverything
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	"github.com/goccy/go-yaml"
@@ -24,6 +25,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	"github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/googleapi"
 )
@@ -116,26 +118,27 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
 	if err != nil {
-		return nil, err
+		// ValidateAndFetchStoreID usually returns input validation errors
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	patientID, ok := params.AsMap()[patientIDKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", patientIDKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", patientIDKey), nil)
 	}
 
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 
@@ -143,11 +146,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if val, ok := params.AsMap()[typeFilterKey]; ok {
 		types, ok := val.([]any)
 		if !ok {
-			return nil, fmt.Errorf("invalid '%s' parameter; expected a string array", typeFilterKey)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string array", typeFilterKey), nil)
 		}
 		typeFilterSlice, err := parameters.ConvertAnySliceToTyped(types, "string")
 		if err != nil {
-			return nil, fmt.Errorf("can't convert '%s' to array of strings: %s", typeFilterKey, err)
+			return nil, util.NewAgentError(fmt.Sprintf("can't convert '%s' to array of strings: %s", typeFilterKey, err), err)
 		}
 		if len(typeFilterSlice.([]string)) != 0 {
 			opts = append(opts, googleapi.QueryParameter("_type", strings.Join(typeFilterSlice.([]string), ",")))
@@ -156,13 +159,18 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if since, ok := params.AsMap()[sinceFilterKey]; ok {
 		sinceStr, ok := since.(string)
 		if !ok {
-			return nil, fmt.Errorf("invalid '%s' parameter; expected a string", sinceFilterKey)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", sinceFilterKey), nil)
 		}
 		if sinceStr != "" {
 			opts = append(opts, googleapi.QueryParameter("_since", sinceStr))
 		}
 	}
-	return source.FHIRPatientEverything(storeID, patientID, tokenStr, opts)
+
+	resp, err := source.FHIRPatientEverything(storeID, patientID, tokenStr, opts)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcarefhirpatientsearch/cloudhealthcarefhirpatientsearch.go

@@ -17,6 +17,7 @@ package fhirpatientsearch
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	"github.com/goccy/go-yaml"
@@ -24,6 +25,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	"github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/googleapi"
 )
@@ -150,22 +152,22 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 
@@ -179,14 +181,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			var ok bool
 			summary, ok = v.(bool)
 			if !ok {
-				return nil, fmt.Errorf("invalid '%s' parameter; expected a boolean", summaryKey)
+				return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a boolean", summaryKey), nil)
 			}
 			continue
 		}
 
 		val, ok := v.(string)
 		if !ok {
-			return nil, fmt.Errorf("invalid parameter '%s'; expected a string", k)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid parameter '%s'; expected a string", k), nil)
 		}
 		if val == "" {
 			continue
@@ -205,7 +207,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			}
 			parts := strings.Split(val, "/")
 			if len(parts) != 2 {
-				return nil, fmt.Errorf("invalid '%s' format; expected YYYY-MM-DD/YYYY-MM-DD", k)
+				return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' format; expected YYYY-MM-DD/YYYY-MM-DD", k), nil)
 			}
 			var values []string
 			if parts[0] != "" {
@@ -229,13 +231,17 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		case familyNameKey:
 			opts = append(opts, googleapi.QueryParameter("family", val))
 		default:
-			return nil, fmt.Errorf("unexpected parameter key %q", k)
+			return nil, util.NewAgentError(fmt.Sprintf("unexpected parameter key %q", k), nil)
 		}
 	}
 	if summary {
 		opts = append(opts, googleapi.QueryParameter("_summary", "text"))
 	}
-	return source.FHIRPatientSearch(storeID, tokenStr, opts)
+	resp, err := source.FHIRPatientSearch(storeID, tokenStr, opts)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaregetdataset/cloudhealthcaregetdataset.go

@@ -17,11 +17,13 @@ package gethealthcaredataset
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -90,19 +92,23 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.GetDataset(tokenStr)
+	resp, err := source.GetDataset(tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaregetdicomstore/cloudhealthcaregetdicomstore.go

@@ -17,12 +17,14 @@ package getdicomstore
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -107,23 +109,27 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedDICOMStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.GetDICOMStore(storeID, tokenStr)
+	resp, err := source.GetDICOMStore(storeID, tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaregetdicomstoremetrics/cloudhealthcaregetdicomstoremetrics.go

@@ -17,12 +17,14 @@ package getdicomstoremetrics
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -107,23 +109,27 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedDICOMStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.GetDICOMStoreMetrics(storeID, tokenStr)
+	resp, err := source.GetDICOMStoreMetrics(storeID, tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaregetfhirresource/cloudhealthcaregetfhirresource.go

@@ -17,12 +17,14 @@ package getfhirresource
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -112,32 +114,36 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	resType, ok := params.AsMap()[typeKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", typeKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", typeKey), nil)
 	}
 	resID, ok := params.AsMap()[idKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected a string", idKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", idKey), nil)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.GetFHIRResource(storeID, resType, resID, tokenStr)
+	resp, err := source.GetFHIRResource(storeID, resType, resID, tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaregetfhirstore/cloudhealthcaregetfhirstore.go

@@ -17,12 +17,14 @@ package getfhirstore
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -107,23 +109,27 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.GetFHIRStore(storeID, tokenStr)
+	resp, err := source.GetFHIRStore(storeID, tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaregetfhirstoremetrics/cloudhealthcaregetfhirstoremetrics.go

@@ -17,12 +17,14 @@ package getfhirstoremetrics
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -107,23 +109,27 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.GetFHIRStoreMetrics(storeID, tokenStr)
+	resp, err := source.GetFHIRStoreMetrics(storeID, tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcarelistdicomstores/cloudhealthcarelistdicomstores.go

@@ -17,11 +17,13 @@ package listdicomstores
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -90,19 +92,23 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.ListDICOMStores(tokenStr)
+	resp, err := source.ListDICOMStores(tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcarelistfhirstores/cloudhealthcarelistfhirstores.go

@@ -17,11 +17,13 @@ package listfhirstores
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/healthcare/v1"
 )
@@ -90,19 +92,23 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
-	return source.ListFHIRStores(tokenStr)
+	resp, err := source.ListFHIRStores(tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcareretrieverendereddicominstance/cloudhealthcareretrieverendereddicominstance.go

@@ -17,12 +17,14 @@ package retrieverendereddicominstance
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -117,40 +119,44 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedDICOMStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 	study, ok := params.AsMap()[studyInstanceUIDKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid '%s' parameter; expected a string", studyInstanceUIDKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", studyInstanceUIDKey), nil)
 	}
 	series, ok := params.AsMap()[seriesInstanceUIDKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid '%s' parameter; expected a string", seriesInstanceUIDKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", seriesInstanceUIDKey), nil)
 	}
 	sop, ok := params.AsMap()[sopInstanceUIDKey].(string)
 	if !ok {
-		return nil, fmt.Errorf("invalid '%s' parameter; expected a string", sopInstanceUIDKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", sopInstanceUIDKey), nil)
 	}
 	frame, ok := params.AsMap()[frameNumberKey].(int)
 	if !ok {
-		return nil, fmt.Errorf("invalid '%s' parameter; expected an integer", frameNumberKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected an integer", frameNumberKey), nil)
 	}
-	return source.RetrieveRenderedDICOMInstance(storeID, study, series, sop, frame, tokenStr)
+	resp, err := source.RetrieveRenderedDICOMInstance(storeID, study, series, sop, frame, tokenStr)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaresearchdicominstances/cloudhealthcaresearchdicominstances.go

@@ -17,6 +17,7 @@ package searchdicominstances
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	"github.com/goccy/go-yaml"
@@ -24,6 +25,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/tools"
 	"github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/googleapi"
 )
@@ -131,33 +133,33 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedDICOMStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 
 	opts, err := common.ParseDICOMSearchParameters(params, []string{sopInstanceUIDKey, patientNameKey, patientIDKey, accessionNumberKey, referringPhysicianNameKey, studyDateKey, modalityKey})
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to parse DICOM search parameters", err)
 	}
 	paramsMap := params.AsMap()
 	dicomWebPath := "instances"
 	if studyInstanceUID, ok := paramsMap[studyInstanceUIDKey]; ok {
 		id, ok := studyInstanceUID.(string)
 		if !ok {
-			return nil, fmt.Errorf("invalid '%s' parameter; expected a string", studyInstanceUIDKey)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", studyInstanceUIDKey), nil)
 		}
 		if id != "" {
 			dicomWebPath = fmt.Sprintf("studies/%s/instances", id)
@@ -166,7 +168,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if seriesInstanceUID, ok := paramsMap[seriesInstanceUIDKey]; ok {
 		id, ok := seriesInstanceUID.(string)
 		if !ok {
-			return nil, fmt.Errorf("invalid '%s' parameter; expected a string", seriesInstanceUIDKey)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", seriesInstanceUIDKey), nil)
 		}
 		if id != "" {
 			if dicomWebPath != "instances" {
@@ -176,7 +178,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			}
 		}
 	}
-	return source.SearchDICOM(t.Type, storeID, dicomWebPath, tokenStr, opts)
+	resp, err := source.SearchDICOM(t.Type, storeID, dicomWebPath, tokenStr, opts)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaresearchdicomseries/cloudhealthcaresearchdicomseries.go

@@ -17,12 +17,14 @@ package searchdicomseries
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/googleapi"
 )
@@ -128,40 +130,44 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedDICOMStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 
 	opts, err := common.ParseDICOMSearchParameters(params, []string{seriesInstanceUIDKey, patientNameKey, patientIDKey, accessionNumberKey, referringPhysicianNameKey, studyDateKey, modalityKey})
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to parse DICOM search parameters", err)
 	}
 	paramsMap := params.AsMap()
 	dicomWebPath := "series"
 	if studyInstanceUID, ok := paramsMap[studyInstanceUIDKey]; ok {
 		id, ok := studyInstanceUID.(string)
 		if !ok {
-			return nil, fmt.Errorf("invalid '%s' parameter; expected a string", studyInstanceUIDKey)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid '%s' parameter; expected a string", studyInstanceUIDKey), nil)
 		}
 		if id != "" {
 			dicomWebPath = fmt.Sprintf("studies/%s/series", id)
 		}
 	}
-	return source.SearchDICOM(t.Type, storeID, dicomWebPath, tokenStr, opts)
+	resp, err := source.SearchDICOM(t.Type, storeID, dicomWebPath, tokenStr, opts)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudhealthcare/cloudhealthcaresearchdicomstudies/cloudhealthcaresearchdicomstudies.go

@@ -17,12 +17,14 @@ package searchdicomstudies
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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/tools/cloudhealthcare/common"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 	"google.golang.org/api/googleapi"
 )
@@ -124,28 +126,32 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedDICOMStores())
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to validate store ID", err)
 	}
 	var tokenStr string
 	if source.UseClientAuthorization() {
 		tokenStr, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("error parsing access token: %w", err)
+			return nil, util.NewClientServerError("error parsing access token", http.StatusUnauthorized, err)
 		}
 	}
 	opts, err := common.ParseDICOMSearchParameters(params, []string{studyInstanceUIDKey, patientNameKey, patientIDKey, accessionNumberKey, referringPhysicianNameKey, studyDateKey})
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError("failed to parse DICOM search parameters", err)
 	}
 	dicomWebPath := "studies"
-	return source.SearchDICOM(t.Type, storeID, dicomWebPath, tokenStr, opts)
+	resp, err := source.SearchDICOM(t.Type, storeID, dicomWebPath, tokenStr, opts)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudloggingadmin/cloudloggingadminlistlognames/cloudloggingadminlistlognames.go

@@ -16,11 +16,13 @@ package cloudloggingadminlistlognames
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -89,10 +91,10 @@ type Tool struct {
 	Parameters  parameters.Parameters `yaml:"parameters"`
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	limit := defaultLimit
@@ -100,18 +102,22 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if val, ok := paramsMap["limit"].(int); ok && val > 0 {
 		limit = val
 	} else if ok && val < 0 {
-		return nil, fmt.Errorf("limit must be greater than or equal to 1")
+		return nil, util.NewAgentError("limit must be greater than or equal to 1", nil)
 	}
 
 	tokenString := ""
 	if source.UseClientAuthorization() {
 		tokenString, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("failed to parse access token: %w", err)
+			return nil, util.NewClientServerError("failed to parse access token", http.StatusUnauthorized, err)
 		}
 	}
 
-	return source.ListLogNames(ctx, limit, tokenString)
+	resp, err := source.ListLogNames(ctx, limit, tokenString)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) ParseParams(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {

internal/tools/cloudloggingadmin/cloudloggingadminlistresourcetypes/cloudloggingadminlistresourcetypes.go

@@ -16,11 +16,13 @@ package cloudloggingadminlistresourcetypes
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -84,21 +86,25 @@ type Tool struct {
 	mcpManifest tools.McpManifest
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	tokenString := ""
 	if source.UseClientAuthorization() {
 		tokenString, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("failed to parse access token: %w", err)
+			return nil, util.NewClientServerError("failed to parse access token", http.StatusUnauthorized, err)
 		}
 	}
 
-	return source.ListResourceTypes(ctx, tokenString)
+	resp, err := source.ListResourceTypes(ctx, tokenString)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) ParseParams(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {

internal/tools/cloudloggingadmin/cloudloggingadminquerylogs/cloudloggingadminquerylogs.go

@@ -16,6 +16,7 @@ package cloudloggingadminquerylogs
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"time"
 
 	"github.com/goccy/go-yaml"
@@ -23,6 +24,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	cla "github.com/googleapis/genai-toolbox/internal/sources/cloudloggingadmin"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -104,10 +106,10 @@ type Tool struct {
 	mcpManifest tools.McpManifest
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	// Parse parameters
@@ -119,7 +121,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if val, ok := paramsMap["limit"].(int); ok && val > 0 {
 		limit = val
 	} else if ok && val < 0 {
-		return nil, fmt.Errorf("limit must be greater than or equal to 1")
+		return nil, util.NewAgentError("limit must be greater than or equal to 1", nil)
 	}
 
 	// Check for verbosity of output
@@ -129,7 +131,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	var filter string
 	if f, ok := paramsMap["filter"].(string); ok {
 		if len(f) == 0 {
-			return nil, fmt.Errorf("filter cannot be empty if provided")
+			return nil, util.NewAgentError("filter cannot be empty if provided", nil)
 		}
 		filter = f
 	}
@@ -138,7 +140,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	var startTime string
 	if val, ok := paramsMap["startTime"].(string); ok && val != "" {
 		if _, err := time.Parse(time.RFC3339, val); err != nil {
-			return nil, fmt.Errorf("startTime must be in RFC3339 format (e.g., 2025-12-09T00:00:00Z): %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("startTime must be in RFC3339 format (e.g., 2025-12-09T00:00:00Z): %v", err), err)
 		}
 		startTime = val
 	} else {
@@ -149,7 +151,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	var endTime string
 	if val, ok := paramsMap["endTime"].(string); ok && val != "" {
 		if _, err := time.Parse(time.RFC3339, val); err != nil {
-			return nil, fmt.Errorf("endTime must be in RFC3339 format (e.g., 2025-12-09T23:59:59Z): %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("endTime must be in RFC3339 format (e.g., 2025-12-09T23:59:59Z): %v", err), err)
 		}
 		endTime = val
 	}
@@ -158,7 +160,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if source.UseClientAuthorization() {
 		tokenString, err = accessToken.ParseBearerToken()
 		if err != nil {
-			return nil, fmt.Errorf("failed to parse access token: %w", err)
+			return nil, util.NewClientServerError("failed to parse access token", http.StatusUnauthorized, err)
 		}
 	}
 
@@ -171,7 +173,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		Limit:       limit,
 	}
 
-	return source.QueryLogs(ctx, queryParams, tokenString)
+	resp, err := source.QueryLogs(ctx, queryParams, tokenString)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) ParseParams(data map[string]any, claimsMap map[string]map[string]any) (parameters.ParamValues, error) {

internal/tools/cloudmonitoring/cloudmonitoring.go

@@ -23,6 +23,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"
 )
 
@@ -93,22 +94,26 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	projectID, ok := paramsMap["projectId"].(string)
 	if !ok {
-		return nil, fmt.Errorf("projectId parameter not found or not a string")
+		return nil, util.NewAgentError("projectId parameter not found or not a string", nil)
 	}
 	query, ok := paramsMap["query"].(string)
 	if !ok {
-		return nil, fmt.Errorf("query parameter not found or not a string")
+		return nil, util.NewAgentError("query parameter not found or not a string", nil)
 	}
-	return source.RunQuery(projectID, query)
+	resp, err := source.RunQuery(projectID, query)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlcloneinstance/cloudsqlcloneinstance.go

@@ -17,11 +17,13 @@ package cloudsqlcloneinstance
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	sqladmin "google.golang.org/api/sqladmin/v1"
 )
@@ -124,31 +126,35 @@ 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", http.StatusInternalServerError, err)
 	}
 	paramsMap := params.AsMap()
 
 	project, ok := paramsMap["project"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'project' parameter: %v", paramsMap["project"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'project' parameter: %v", paramsMap["project"]), nil)
 	}
 	sourceInstanceName, ok := paramsMap["sourceInstanceName"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'sourceInstanceName' parameter: %v", paramsMap["sourceInstanceName"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'sourceInstanceName' parameter: %v", paramsMap["sourceInstanceName"]), nil)
 	}
 	destinationInstanceName, ok := paramsMap["destinationInstanceName"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'destinationInstanceName' parameter: %v", paramsMap["destinationInstanceName"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'destinationInstanceName' parameter: %v", paramsMap["destinationInstanceName"]), nil)
 	}
 
 	pointInTime, _ := paramsMap["pointInTime"].(string)
 	preferredZone, _ := paramsMap["preferredZone"].(string)
 	preferredSecondaryZone, _ := paramsMap["preferredSecondaryZone"].(string)
 
-	return source.CloneInstance(ctx, project, sourceInstanceName, destinationInstanceName, pointInTime, preferredZone, preferredSecondaryZone, string(accessToken))
+	resp, err := source.CloneInstance(ctx, project, sourceInstanceName, destinationInstanceName, pointInTime, preferredZone, preferredSecondaryZone, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlcreatebackup/cloudsqlcreatebackup.go

@@ -17,11 +17,13 @@ package cloudsqlcreatebackup
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/sqladmin/v1"
 )
@@ -120,26 +122,30 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	paramsMap := params.AsMap()
 
 	project, ok := paramsMap["project"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'project' parameter: %v", paramsMap["project"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'project' parameter: %v", paramsMap["project"]), nil)
 	}
 	instance, ok := paramsMap["instance"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'instance' parameter: %v", paramsMap["instance"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'instance' parameter: %v", paramsMap["instance"]), nil)
 	}
 
 	location, _ := paramsMap["location"].(string)
 	description, _ := paramsMap["backup_description"].(string)
 
-	return source.InsertBackupRun(ctx, project, instance, location, description, string(accessToken))
+	resp, err := source.InsertBackupRun(ctx, project, instance, location, description, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlcreatedatabase/cloudsqlcreatedatabase.go

@@ -17,11 +17,13 @@ package cloudsqlcreatedatabase
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -117,27 +119,31 @@ 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", http.StatusInternalServerError, 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)
 	}
 	instance, ok := paramsMap["instance"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'instance' parameter")
+		return nil, util.NewAgentError("missing 'instance' parameter", nil)
 	}
 	name, ok := paramsMap["name"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'name' parameter")
+		return nil, util.NewAgentError("missing 'name' parameter", nil)
 	}
-	return source.CreateDatabase(ctx, name, project, instance, string(accessToken))
+	resp, err := source.CreateDatabase(ctx, name, project, instance, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlcreateusers/cloudsqlcreateusers.go

@@ -17,11 +17,13 @@ package cloudsqlcreateusers
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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,30 +121,34 @@ 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", http.StatusInternalServerError, 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)
 	}
 	instance, ok := paramsMap["instance"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'instance' parameter")
+		return nil, util.NewAgentError("missing 'instance' parameter", nil)
 	}
 	name, ok := paramsMap["name"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'name' parameter")
+		return nil, util.NewAgentError("missing 'name' parameter", nil)
 	}
 
 	iamUser, _ := paramsMap["iamUser"].(bool)
 	password, _ := paramsMap["password"].(string)
-	return source.CreateUsers(ctx, project, instance, name, password, iamUser, string(accessToken))
+	resp, err := source.CreateUsers(ctx, project, instance, name, password, iamUser, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlgetinstances/cloudsqlgetinstances.go

@@ -17,11 +17,13 @@ package cloudsqlgetinstances
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -117,23 +119,27 @@ 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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 
 	projectId, ok := paramsMap["projectId"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'projectId' parameter")
+		return nil, util.NewAgentError("missing 'projectId' parameter", nil)
 	}
 	instanceId, ok := paramsMap["instanceId"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'instanceId' parameter")
+		return nil, util.NewAgentError("missing 'instanceId' parameter", nil)
 	}
-	return source.GetInstance(ctx, projectId, instanceId, string(accessToken))
+	resp, err := source.GetInstance(ctx, projectId, instanceId, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqllistdatabases/cloudsqllistdatabases.go

@@ -17,11 +17,13 @@ package cloudsqllistdatabases
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -116,23 +118,27 @@ 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", http.StatusInternalServerError, 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)
 	}
 	instance, ok := paramsMap["instance"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'instance' parameter")
+		return nil, util.NewAgentError("missing 'instance' parameter", nil)
 	}
-	return source.ListDatabase(ctx, project, instance, string(accessToken))
+	resp, err := source.ListDatabase(ctx, project, instance, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqllistinstances/cloudsqllistinstances.go

@@ -17,11 +17,13 @@ package cloudsqllistinstances
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -115,19 +117,23 @@ 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", http.StatusInternalServerError, 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)
 	}
-	return source.ListInstance(ctx, project, string(accessToken))
+	resp, err := source.ListInstance(ctx, project, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlrestorebackup/cloudsqlrestorebackup.go

@@ -17,11 +17,13 @@ package cloudsqlrestorebackup
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/sqladmin/v1"
 )
@@ -120,29 +122,33 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	paramsMap := params.AsMap()
 
 	targetProject, ok := paramsMap["target_project"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'target_project' parameter: %v", paramsMap["target_project"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'target_project' parameter: %v", paramsMap["target_project"]), nil)
 	}
 	targetInstance, ok := paramsMap["target_instance"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'target_instance' parameter: %v", paramsMap["target_instance"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'target_instance' parameter: %v", paramsMap["target_instance"]), nil)
 	}
 	backupID, ok := paramsMap["backup_id"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'backup_id' parameter: %v", paramsMap["backup_id"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'backup_id' parameter: %v", paramsMap["backup_id"]), nil)
 	}
 	sourceProject, _ := paramsMap["source_project"].(string)
 	sourceInstance, _ := paramsMap["source_instance"].(string)
 
-	return source.RestoreBackup(ctx, targetProject, targetInstance, sourceProject, sourceInstance, backupID, string(accessToken))
+	resp, err := source.RestoreBackup(ctx, targetProject, targetInstance, sourceProject, sourceInstance, backupID, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsql/cloudsqlwaitforoperation/cloudsqlwaitforoperation.go

@@ -17,12 +17,14 @@ package cloudsqlwaitforoperation
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"time"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/sqladmin/v1"
 )
@@ -210,21 +212,21 @@ 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", http.StatusInternalServerError, 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)
 	}
 	operationID, 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)
@@ -232,7 +234,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	service, err := source.GetService(ctx, string(accessToken))
 	if err != nil {
-		return nil, err
+		return nil, util.ProcessGcpError(err)
 	}
 
 	delay := t.Delay
@@ -244,13 +246,13 @@ 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.NewClientServerError("timed out waiting for operation", http.StatusRequestTimeout, ctx.Err())
 		default:
 		}
 
 		op, err := source.GetWaitForOperations(ctx, service, project, operationID, cloudSQLConnectionMessageTemplate, delay)
 		if err != nil {
-			return nil, err
+			return nil, util.ProcessGcpError(err)
 		} else if op != nil {
 			return op, nil
 		}
@@ -262,7 +264,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.NewClientServerError("exceeded max retries waiting for operation", http.StatusGatewayTimeout, fmt.Errorf("exceeded max retries"))
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsqlmssql/cloudsqlmssqlcreateinstance/cloudsqlmssqlcreateinstance.go

@@ -17,12 +17,14 @@ package cloudsqlmssqlcreateinstance
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/sqladmin/v1"
 )
@@ -121,33 +123,33 @@ 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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 
 	project, ok := paramsMap["project"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'project' parameter: %s", paramsMap["project"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'project' parameter: %s", paramsMap["project"]), nil)
 	}
 	name, ok := paramsMap["name"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'name' parameter: %s", paramsMap["name"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'name' parameter: %s", paramsMap["name"]), nil)
 	}
 	dbVersion, ok := paramsMap["databaseVersion"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'databaseVersion' parameter: %s", paramsMap["databaseVersion"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'databaseVersion' parameter: %s", paramsMap["databaseVersion"]), nil)
 	}
 	rootPassword, ok := paramsMap["rootPassword"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'rootPassword' parameter: %s", paramsMap["rootPassword"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'rootPassword' parameter: %s", paramsMap["rootPassword"]), nil)
 	}
 	editionPreset, ok := paramsMap["editionPreset"].(string)
 	if !ok {
-		return nil, fmt.Errorf("error casting 'editionPreset' parameter: %s", paramsMap["editionPreset"])
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'editionPreset' parameter: %s", paramsMap["editionPreset"]), nil)
 	}
 	settings := sqladmin.Settings{}
 	switch strings.ToLower(editionPreset) {
@@ -164,9 +166,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		settings.DataDiskSizeGb = 100
 		settings.DataDiskType = "PD_SSD"
 	default:
-		return nil, fmt.Errorf("invalid 'editionPreset': %q. Must be either 'Production' or 'Development'", editionPreset)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid 'editionPreset': %q. Must be either 'Production' or 'Development'", editionPreset), nil)
 	}
-	return source.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, string(accessToken))
+	resp, err := source.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsqlmysql/cloudsqlmysqlcreateinstance/cloudsqlmysqlcreateinstance.go

@@ -17,12 +17,14 @@ package cloudsqlmysqlcreateinstance
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	sqladmin "google.golang.org/api/sqladmin/v1"
 )
@@ -121,33 +123,33 @@ 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", http.StatusInternalServerError, 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)
 	}
 	name, ok := paramsMap["name"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'name' parameter")
+		return nil, util.NewAgentError("missing 'name' parameter", nil)
 	}
 	dbVersion, ok := paramsMap["databaseVersion"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'databaseVersion' parameter")
+		return nil, util.NewAgentError("missing 'databaseVersion' parameter", nil)
 	}
 	rootPassword, ok := paramsMap["rootPassword"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'rootPassword' parameter")
+		return nil, util.NewAgentError("missing 'rootPassword' parameter", nil)
 	}
 	editionPreset, ok := paramsMap["editionPreset"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'editionPreset' parameter")
+		return nil, util.NewAgentError("missing 'editionPreset' parameter", nil)
 	}
 
 	settings := sqladmin.Settings{}
@@ -165,10 +167,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		settings.DataDiskSizeGb = 100
 		settings.DataDiskType = "PD_SSD"
 	default:
-		return nil, fmt.Errorf("invalid 'editionPreset': %q. Must be either 'Production' or 'Development'", editionPreset)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid 'editionPreset': %q. Must be either 'Production' or 'Development'", editionPreset), nil)
 	}
 
-	return source.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, string(accessToken))
+	resp, err := source.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsqlpg/cloudsqlpgcreateinstances/cloudsqlpgcreateinstances.go

@@ -17,12 +17,14 @@ package cloudsqlpgcreateinstances
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	sqladmin "google.golang.org/api/sqladmin/v1"
 )
@@ -121,33 +123,33 @@ 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", http.StatusInternalServerError, 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)
 	}
 	name, ok := paramsMap["name"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'name' parameter")
+		return nil, util.NewAgentError("missing 'name' parameter", nil)
 	}
 	dbVersion, ok := paramsMap["databaseVersion"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'databaseVersion' parameter")
+		return nil, util.NewAgentError("missing 'databaseVersion' parameter", nil)
 	}
 	rootPassword, ok := paramsMap["rootPassword"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'rootPassword' parameter")
+		return nil, util.NewAgentError("missing 'rootPassword' parameter", nil)
 	}
 	editionPreset, ok := paramsMap["editionPreset"].(string)
 	if !ok {
-		return nil, fmt.Errorf("missing 'editionPreset' parameter")
+		return nil, util.NewAgentError("missing 'editionPreset' parameter", nil)
 	}
 
 	settings := sqladmin.Settings{}
@@ -165,9 +167,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		settings.DataDiskSizeGb = 100
 		settings.DataDiskType = "PD_SSD"
 	default:
-		return nil, fmt.Errorf("invalid 'editionPreset': %q. Must be either 'Production' or 'Development'", editionPreset)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid 'editionPreset': %q. Must be either 'Production' or 'Development'", editionPreset), nil)
 	}
-	return source.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, string(accessToken))
+	resp, err := source.CreateInstance(ctx, project, name, dbVersion, rootPassword, settings, string(accessToken))
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/cloudsqlpg/cloudsqlpgupgradeprecheck/cloudsqlpgupgradeprecheck.go

@@ -17,12 +17,14 @@ package cloudsqlpgupgradeprecheck
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"time"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	sqladmin "google.golang.org/api/sqladmin/v1"
 )
@@ -132,31 +134,31 @@ 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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 
 	project, ok := paramsMap["project"].(string)
 	if !ok || project == "" {
-		return nil, fmt.Errorf("missing or empty 'project' parameter")
+		return nil, util.NewAgentError("missing or empty 'project' parameter", nil)
 	}
 	instanceName, ok := paramsMap["instance"].(string)
 	if !ok || instanceName == "" {
-		return nil, fmt.Errorf("missing or empty 'instance' parameter")
+		return nil, util.NewAgentError("missing or empty 'instance' parameter", nil)
 	}
 	targetVersion, ok := paramsMap["targetDatabaseVersion"].(string)
 	if !ok || targetVersion == "" {
 		// This should not happen due to the default value
-		return nil, fmt.Errorf("missing or empty 'targetDatabaseVersion' parameter")
+		return nil, util.NewAgentError("missing or empty 'targetDatabaseVersion' parameter", nil)
 	}
 
 	service, err := source.GetService(ctx, string(accessToken))
 	if err != nil {
-		return nil, fmt.Errorf("failed to get HTTP client from source: %w", err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	reqBody := &sqladmin.InstancesPreCheckMajorVersionUpgradeRequest{
@@ -168,7 +170,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	call := service.Instances.PreCheckMajorVersionUpgrade(project, instanceName, reqBody).Context(ctx)
 	op, err := call.Do()
 	if err != nil {
-		return nil, fmt.Errorf("failed to start pre-check operation: %w", err)
+		return nil, util.ProcessGcpError(err)
 	}
 
 	const pollTimeout = 20 * time.Second
@@ -177,7 +179,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	for time.Now().Before(cutoffTime) {
 		currentOp, err := service.Operations.Get(project, op.Name).Context(ctx).Do()
 		if err != nil {
-			return nil, fmt.Errorf("failed to get operation status: %w", err)
+			return nil, util.ProcessGcpError(err)
 		}
 
 		if currentOp.Status == "DONE" {
@@ -186,7 +188,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 				if currentOp.Error.Errors[0].Code != "" {
 					errMsg = fmt.Sprintf("%s (Code: %s)", errMsg, currentOp.Error.Errors[0].Code)
 				}
-				return nil, fmt.Errorf("%s", errMsg)
+				return nil, util.NewClientServerError(errMsg, http.StatusInternalServerError, fmt.Errorf("pre-check operation failed with error: %s", errMsg))
 			}
 
 			var preCheckItems []*sqladmin.PreCheckResponse
@@ -199,7 +201,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 		select {
 		case <-ctx.Done():
-			return nil, ctx.Err()
+			return nil, util.NewClientServerError("timed out waiting for operation", http.StatusRequestTimeout, ctx.Err())
 		case <-time.After(5 * time.Second):
 		}
 	}

internal/tools/couchbase/couchbase.go

@@ -17,12 +17,14 @@ package couchbase
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/couchbase/gocb/v2"
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -58,7 +60,6 @@ type Config struct {
 	TemplateParameters parameters.Parameters `yaml:"templateParameters"`
 }
 
-// validate interface
 var _ tools.ToolConfig = Config{}
 
 func (cfg Config) ToolConfigType() string {
@@ -72,7 +73,6 @@ func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error)
 	}
 
 	mcpManifest := tools.GetMcpManifest(cfg.Name, cfg.Description, cfg.AuthRequired, allParameters, nil)
-	// finish tool setup
 	t := Tool{
 		Config:      cfg,
 		AllParams:   allParameters,
@@ -82,7 +82,6 @@ func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error)
 	return t, nil
 }
 
-// validate interface
 var _ tools.Tool = Tool{}
 
 type Tool struct {
@@ -96,23 +95,28 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	namedParamsMap := params.AsMap()
 	newStatement, err := parameters.ResolveTemplateParams(t.TemplateParameters, t.Statement, namedParamsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract template params %w", err)
+		return nil, util.NewAgentError("unable to extract template params", err)
 	}
 
 	newParams, err := parameters.GetParams(t.Parameters, namedParamsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract standard params %w", err)
+		return nil, util.NewAgentError("unable to extract standard params", err)
 	}
-	return source.RunSQL(newStatement, newParams)
+
+	resp, err := source.RunSQL(newStatement, newParams)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/dataform/dataformcompilelocal/dataformcompilelocal.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"
 )
 
@@ -86,18 +87,19 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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) {
 	paramsMap := params.AsMap()
 
 	projectDir, ok := paramsMap["project_dir"].(string)
 	if !ok || projectDir == "" {
-		return nil, fmt.Errorf("error casting 'project_dir' to string or invalid value")
+		return nil, util.NewAgentError("error casting 'project_dir' to string or invalid value", nil)
 	}
 
 	cmd := exec.CommandContext(ctx, "dataform", "compile", projectDir, "--json")
 	output, err := cmd.CombinedOutput()
 	if err != nil {
-		return nil, fmt.Errorf("error executing dataform compile: %w\nOutput: %s", err, string(output))
+		// Compilation failures are considered AgentErrors (invalid user code/project)
+		return nil, util.NewAgentError(fmt.Sprintf("error executing dataform compile: %v\nOutput: %s", err, string(output)), err)
 	}
 
 	return strings.TrimSpace(string(output)), nil

internal/tools/dataplex/dataplexlookupentry/dataplexlookupentry.go

@@ -17,12 +17,14 @@ package dataplexlookupentry
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	dataplexpb "cloud.google.com/go/dataplex/apiv1/dataplexpb"
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -110,10 +112,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
@@ -122,10 +124,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	view, _ := paramsMap["view"].(int)
 	aspectTypeSlice, err := parameters.ConvertAnySliceToTyped(paramsMap["aspectTypes"].([]any), "string")
 	if err != nil {
-		return nil, fmt.Errorf("can't convert aspectTypes to array of strings: %s", err)
+		return nil, util.NewAgentError(fmt.Sprintf("can't convert aspectTypes to array of strings: %s", err), err)
 	}
 	aspectTypes := aspectTypeSlice.([]string)
-	return source.LookupEntry(ctx, name, view, aspectTypes, entry)
+	resp, err := source.LookupEntry(ctx, name, view, aspectTypes, entry)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/dataplex/dataplexsearchaspecttypes/dataplexsearchaspecttypes.go

@@ -17,12 +17,14 @@ package dataplexsearchaspecttypes
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"cloud.google.com/go/dataplex/apiv1/dataplexpb"
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -93,16 +95,29 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	paramsMap := params.AsMap()
-	query, _ := paramsMap["query"].(string)
+	query, ok := paramsMap["query"].(string)
-	pageSize, _ := paramsMap["pageSize"].(int)
+	if !ok {
-	orderBy, _ := paramsMap["orderBy"].(string)
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'query' parameter: %v", paramsMap["query"]), nil)
-	return source.SearchAspectTypes(ctx, query, pageSize, orderBy)
+	}
+	pageSize, ok := paramsMap["pageSize"].(int)
+	if !ok {
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'pageSize' parameter: %v", paramsMap["pageSize"]), nil)
+	}
+	orderBy, ok := paramsMap["orderBy"].(string)
+	if !ok {
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'orderBy' parameter: %v", paramsMap["orderBy"]), nil)
+	}
+	resp, err := source.SearchAspectTypes(ctx, query, pageSize, orderBy)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/dataplex/dataplexsearchentries/dataplexsearchentries.go

@@ -17,12 +17,14 @@ package dataplexsearchentries
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"cloud.google.com/go/dataplex/apiv1/dataplexpb"
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -93,16 +95,29 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 	paramsMap := params.AsMap()
-	query, _ := paramsMap["query"].(string)
+	query, ok := paramsMap["query"].(string)
-	pageSize, _ := paramsMap["pageSize"].(int)
+	if !ok {
-	orderBy, _ := paramsMap["orderBy"].(string)
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'query' parameter: %v", paramsMap["query"]), nil)
-	return source.SearchEntries(ctx, query, pageSize, orderBy)
+	}
+	pageSize, ok := paramsMap["pageSize"].(int)
+	if !ok {
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'pageSize' parameter: %v", paramsMap["pageSize"]), nil)
+	}
+	orderBy, ok := paramsMap["orderBy"].(string)
+	if !ok {
+		return nil, util.NewAgentError(fmt.Sprintf("error casting 'orderBy' parameter: %v", paramsMap["orderBy"]), nil)
+	}
+	resp, err := source.SearchEntries(ctx, query, pageSize, orderBy)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/dgraph/dgraph.go

@@ -17,12 +17,14 @@ package dgraph
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
 	"github.com/googleapis/genai-toolbox/internal/sources"
 	"github.com/googleapis/genai-toolbox/internal/sources/dgraph"
 	"github.com/googleapis/genai-toolbox/internal/tools"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -91,12 +93,16 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
-	return source.RunSQL(t.Statement, params, t.IsQuery, t.Timeout)
+	resp, err := source.RunSQL(t.Statement, params, t.IsQuery, t.Timeout)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firebird/firebirdexecutesql/firebirdexecutesql.go

@@ -18,6 +18,7 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
@@ -90,25 +91,30 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
-	sql, ok := paramsMap["sql"].(string)
+	sqlStr, ok := paramsMap["sql"].(string)
 	if !ok {
-		return nil, fmt.Errorf("unable to get cast %s", paramsMap["sql"])
+		return nil, util.NewAgentError(fmt.Sprintf("unable to cast parameter 'sql' to string: %v", paramsMap["sql"]), nil)
 	}
 
 	// Log the query executed for debugging.
 	logger, err := util.LoggerFromContext(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("error getting logger: %s", err)
+		return nil, util.NewClientServerError("error getting logger", http.StatusInternalServerError, err)
 	}
-	logger.DebugContext(ctx, fmt.Sprintf("executing `%s` tool query: %s", resourceType, sql))
+	logger.DebugContext(ctx, fmt.Sprintf("executing `%s` tool query: %s", resourceType, sqlStr))
-	return source.RunSQL(ctx, sql, nil)
+
+	resp, err := source.RunSQL(ctx, sqlStr, nil)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firebird/firebirdsql/firebirdsql.go

@@ -18,12 +18,14 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"net/http"
 	"strings"
 
 	"github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -98,21 +100,21 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
 	statement, err := parameters.ResolveTemplateParams(t.TemplateParameters, t.Statement, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract template params: %w", err)
+		return nil, util.NewAgentError("unable to extract template params", err)
 	}
 
 	newParams, err := parameters.GetParams(t.Parameters, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("unable to extract standard params: %w", err)
+		return nil, util.NewAgentError("unable to extract standard params", err)
 	}
 
 	namedArgs := make([]any, 0, len(newParams))
@@ -127,7 +129,12 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			namedArgs = append(namedArgs, value)
 		}
 	}
-	return source.RunSQL(ctx, statement, namedArgs)
+
+	resp, err := source.RunSQL(ctx, statement, namedArgs)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firestore/firestoreadddocuments/firestoreadddocuments.go

@@ -17,13 +17,15 @@ package firestoreadddocuments
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	firestoreapi "cloud.google.com/go/firestore"
 	yaml "github.com/goccy/go-yaml"
 	"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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -128,32 +130,32 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	// Get collection path
 	collectionPath, ok := mapParams[collectionPathKey].(string)
 	if !ok || collectionPath == "" {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter", collectionPathKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter", collectionPathKey), nil)
 	}
 	// Validate collection path
-	if err := util.ValidateCollectionPath(collectionPath); err != nil {
+	if err := fsUtil.ValidateCollectionPath(collectionPath); err != nil {
-		return nil, fmt.Errorf("invalid collection path: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid collection path: %v", err), err)
 	}
 	// Get document data
 	documentDataRaw, ok := mapParams[documentDataKey]
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter", documentDataKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter", documentDataKey), nil)
 	}
 	// Convert the document data from JSON format to Firestore format
 	// The client is passed to handle referenceValue types
-	documentData, err := util.JSONToFirestoreValue(documentDataRaw, source.FirestoreClient())
+	documentData, err := fsUtil.JSONToFirestoreValue(documentDataRaw, source.FirestoreClient())
 	if err != nil {
-		return nil, fmt.Errorf("failed to convert document data: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("failed to convert document data: %v", err), err)
 	}
 
 	// Get return document data flag
@@ -161,7 +163,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if val, ok := mapParams[returnDocumentDataKey].(bool); ok {
 		returnData = val
 	}
-	return source.AddDocuments(ctx, collectionPath, documentData, returnData)
+	resp, err := source.AddDocuments(ctx, collectionPath, documentData, returnData)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firestore/firestoredeletedocuments/firestoredeletedocuments.go

@@ -17,13 +17,15 @@ package firestoredeletedocuments
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	firestoreapi "cloud.google.com/go/firestore"
 	yaml "github.com/goccy/go-yaml"
 	"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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -94,39 +96,43 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	documentPathsRaw, ok := mapParams[documentPathsKey].([]any)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected an array", documentPathsKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected an array", documentPathsKey), nil)
 	}
 	if len(documentPathsRaw) == 0 {
-		return nil, fmt.Errorf("'%s' parameter cannot be empty", documentPathsKey)
+		return nil, util.NewAgentError(fmt.Sprintf("'%s' parameter cannot be empty", documentPathsKey), nil)
 	}
 
 	// Use ConvertAnySliceToTyped to convert the slice
 	typedSlice, err := parameters.ConvertAnySliceToTyped(documentPathsRaw, "string")
 	if err != nil {
-		return nil, fmt.Errorf("failed to convert document paths: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("failed to convert document paths: %v", err), err)
 	}
 
 	documentPaths, ok := typedSlice.([]string)
 	if !ok {
-		return nil, fmt.Errorf("unexpected type conversion error for document paths")
+		return nil, util.NewAgentError("unexpected type conversion error for document paths", nil)
 	}
 
 	// Validate each document path
 	for i, path := range documentPaths {
-		if err := util.ValidateDocumentPath(path); err != nil {
+		if err := fsUtil.ValidateDocumentPath(path); err != nil {
-			return nil, fmt.Errorf("invalid document path at index %d: %w", i, err)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid document path at index %d: %v", i, err), err)
 		}
 	}
-	return source.DeleteDocuments(ctx, documentPaths)
+	resp, err := source.DeleteDocuments(ctx, documentPaths)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firestore/firestoregetdocuments/firestoregetdocuments.go

@@ -17,13 +17,15 @@ package firestoregetdocuments
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	firestoreapi "cloud.google.com/go/firestore"
 	yaml "github.com/goccy/go-yaml"
 	"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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -94,40 +96,44 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	documentPathsRaw, ok := mapParams[documentPathsKey].([]any)
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter; expected an array", documentPathsKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected an array", documentPathsKey), nil)
 	}
 
 	if len(documentPathsRaw) == 0 {
-		return nil, fmt.Errorf("'%s' parameter cannot be empty", documentPathsKey)
+		return nil, util.NewAgentError(fmt.Sprintf("'%s' parameter cannot be empty", documentPathsKey), nil)
 	}
 
 	// Use ConvertAnySliceToTyped to convert the slice
 	typedSlice, err := parameters.ConvertAnySliceToTyped(documentPathsRaw, "string")
 	if err != nil {
-		return nil, fmt.Errorf("failed to convert document paths: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("failed to convert document paths: %v", err), err)
 	}
 
 	documentPaths, ok := typedSlice.([]string)
 	if !ok {
-		return nil, fmt.Errorf("unexpected type conversion error for document paths")
+		return nil, util.NewAgentError("unexpected type conversion error for document paths", nil)
 	}
 
 	// Validate each document path
 	for i, path := range documentPaths {
-		if err := util.ValidateDocumentPath(path); err != nil {
+		if err := fsUtil.ValidateDocumentPath(path); err != nil {
-			return nil, fmt.Errorf("invalid document path at index %d: %w", i, err)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid document path at index %d: %v", i, err), err)
 		}
 	}
-	return source.GetDocuments(ctx, documentPaths)
+	resp, err := source.GetDocuments(ctx, documentPaths)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firestore/firestoregetrules/firestoregetrules.go

@@ -17,11 +17,13 @@ package firestoregetrules
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/firebaserules/v1"
 )
@@ -92,12 +94,16 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
-	return source.GetRules(ctx)
+	resp, err := source.GetRules(ctx)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firestore/firestorelistcollections/firestorelistcollections.go

@@ -17,13 +17,15 @@ package firestorelistcollections
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	firestoreapi "cloud.google.com/go/firestore"
 	yaml "github.com/goccy/go-yaml"
 	"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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -95,10 +97,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
@@ -107,11 +109,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	parentPath, _ := mapParams[parentPathKey].(string)
 	if parentPath != "" {
 		// Validate parent document path
-		if err := util.ValidateDocumentPath(parentPath); err != nil {
+		if err := fsUtil.ValidateDocumentPath(parentPath); err != nil {
-			return nil, fmt.Errorf("invalid parent document path: %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("invalid parent document path: %v", err), err)
 		}
 	}
-	return source.ListCollections(ctx, parentPath)
+	resp, err := source.ListCollections(ctx, parentPath)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/firestore/firestorequery/firestorequery.go

@@ -18,6 +18,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"strconv"
 	"strings"
 
@@ -26,7 +27,8 @@ 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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -158,16 +160,16 @@ var validOperators = map[string]bool{
 }
 
 // Invoke executes the Firestore query based on the provided parameters
-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", http.StatusInternalServerError, err)
 	}
 	paramsMap := params.AsMap()
 	// Process collection path with template substitution
 	collectionPath, err := parameters.PopulateTemplate("collectionPath", t.CollectionPath, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("failed to process collection path: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("failed to process collection path: %v", err), err)
 	}
 
 	var filter firestoreapi.EntityFilter
@@ -176,13 +178,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		// Apply template substitution to filters
 		filtersJSON, err := parameters.PopulateTemplateWithJSON("filters", t.Filters, paramsMap)
 		if err != nil {
-			return nil, fmt.Errorf("failed to process filters template: %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("failed to process filters template: %v", err), err)
 		}
 
 		// Parse the simplified filter format
 		var simplifiedFilter SimplifiedFilter
 		if err := json.Unmarshal([]byte(filtersJSON), &simplifiedFilter); err != nil {
-			return nil, fmt.Errorf("failed to parse filters: %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("failed to parse filters: %v", err), err)
 		}
 
 		// Convert simplified filter to Firestore filter
@@ -191,17 +193,17 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Process and apply ordering
 	orderBy, err := t.getOrderBy(paramsMap)
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError(fmt.Sprintf("failed to process order by: %v", err), err)
 	}
 	// Process select fields
 	selectFields, err := t.processSelectFields(paramsMap)
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError(fmt.Sprintf("failed to process select fields: %v", err), err)
 	}
 	// Process and apply limit
 	limit, err := t.getLimit(paramsMap)
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError(fmt.Sprintf("failed to process limit: %v", err), err)
 	}
 
 	// prevent panic when accessing orderBy incase it is nil
@@ -215,10 +217,14 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Build the query
 	query, err := source.BuildQuery(collectionPath, filter, selectFields, orderByField, orderByDirection, limit, t.AnalyzeQuery)
 	if err != nil {
-		return nil, err
+		return nil, util.ProcessGcpError(err)
 	}
 	// Execute the query and return results
-	return source.ExecuteQuery(ctx, query, t.AnalyzeQuery)
+	resp, err := source.ExecuteQuery(ctx, query, t.AnalyzeQuery)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 // convertToFirestoreFilter converts simplified filter format to Firestore EntityFilter
@@ -255,7 +261,7 @@ func (t Tool) convertToFirestoreFilter(source compatibleSource, filter Simplifie
 	if filter.Field != "" && filter.Op != "" && filter.Value != nil {
 		if validOperators[filter.Op] {
 			// Convert the value using the Firestore native JSON converter
-			convertedValue, err := util.JSONToFirestoreValue(filter.Value, source.FirestoreClient())
+			convertedValue, err := fsUtil.JSONToFirestoreValue(filter.Value, source.FirestoreClient())
 			if err != nil {
 				// If conversion fails, use the original value
 				convertedValue = filter.Value
@@ -367,7 +373,7 @@ func (t Tool) getLimit(params map[string]any) (int, error) {
 		if processedValue != "" {
 			parsedLimit, err := strconv.Atoi(processedValue)
 			if err != nil {
-				return 0, fmt.Errorf("failed to parse limit value '%s': %w", processedValue, err)
+				return 0, err
 			}
 			limit = parsedLimit
 		}

internal/tools/firestore/firestorequerycollection/firestorequerycollection.go

@@ -18,6 +18,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"strings"
 
 	firestoreapi "cloud.google.com/go/firestore"
@@ -25,7 +26,8 @@ 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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -230,16 +232,16 @@ func (o *OrderByConfig) GetDirection() firestoreapi.Direction {
 }
 
 // Invoke executes the Firestore query based on the provided parameters
-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", http.StatusInternalServerError, err)
 	}
 
 	// Parse parameters
 	queryParams, err := t.parseQueryParameters(params)
 	if err != nil {
-		return nil, err
+		return nil, util.NewAgentError(fmt.Sprintf("failed to parse query parameters: %v", err), err)
 	}
 
 	var filter firestoreapi.EntityFilter
@@ -270,9 +272,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Build the query
 	query, err := source.BuildQuery(queryParams.CollectionPath, filter, nil, orderByField, orderByDirection, queryParams.Limit, queryParams.AnalyzeQuery)
 	if err != nil {
-		return nil, err
+		return nil, util.ProcessGcpError(err)
 	}
-	return source.ExecuteQuery(ctx, query, queryParams.AnalyzeQuery)
+	resp, err := source.ExecuteQuery(ctx, query, queryParams.AnalyzeQuery)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 // queryParameters holds all parsed query parameters
@@ -295,7 +301,7 @@ func (t Tool) parseQueryParameters(params parameters.ParamValues) (*queryParamet
 	}
 
 	// Validate collection path
-	if err := util.ValidateCollectionPath(collectionPath); err != nil {
+	if err := fsUtil.ValidateCollectionPath(collectionPath); err != nil {
 		return nil, fmt.Errorf("invalid collection path: %w", err)
 	}
 

internal/tools/firestore/firestoreupdatedocument/firestoreupdatedocument.go

@@ -17,6 +17,7 @@ package firestoreupdatedocument
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"strings"
 
 	firestoreapi "cloud.google.com/go/firestore"
@@ -24,7 +25,8 @@ 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/tools/firestore/util"
+	fsUtil "github.com/googleapis/genai-toolbox/internal/tools/firestore/util"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 )
 
@@ -138,10 +140,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
@@ -149,18 +151,18 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Get document path
 	documentPath, ok := mapParams[documentPathKey].(string)
 	if !ok || documentPath == "" {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter", documentPathKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter", documentPathKey), nil)
 	}
 
 	// Validate document path
-	if err := util.ValidateDocumentPath(documentPath); err != nil {
+	if err := fsUtil.ValidateDocumentPath(documentPath); err != nil {
-		return nil, fmt.Errorf("invalid document path: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid document path: %v", err), err)
 	}
 
 	// Get document data
 	documentDataRaw, ok := mapParams[documentDataKey]
 	if !ok {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter", documentDataKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter", documentDataKey), nil)
 	}
 
 	// Get update mask if provided
@@ -170,11 +172,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 			// Use ConvertAnySliceToTyped to convert the slice
 			typedSlice, err := parameters.ConvertAnySliceToTyped(updateMaskArray, "string")
 			if err != nil {
-				return nil, fmt.Errorf("failed to convert update mask: %w", err)
+				return nil, util.NewAgentError(fmt.Sprintf("failed to convert update mask: %v", err), err)
 			}
 			updatePaths, ok = typedSlice.([]string)
 			if !ok {
-				return nil, fmt.Errorf("unexpected type conversion error for update mask")
+				return nil, util.NewAgentError("unexpected type conversion error for update mask", nil)
 			}
 		}
 	}
@@ -184,15 +186,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if len(updatePaths) > 0 {
 
 		// Convert document data without delete markers
-		dataMap, err := util.JSONToFirestoreValue(documentDataRaw, source.FirestoreClient())
+		dataMap, err := fsUtil.JSONToFirestoreValue(documentDataRaw, source.FirestoreClient())
 		if err != nil {
-			return nil, fmt.Errorf("failed to convert document data: %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("failed to convert document data: %v", err), err)
 		}
 
 		// Ensure it's a map
 		dataMapTyped, ok := dataMap.(map[string]interface{})
 		if !ok {
-			return nil, fmt.Errorf("document data must be a map")
+			return nil, util.NewAgentError("document data must be a map", nil)
 		}
 
 		for _, path := range updatePaths {
@@ -210,9 +212,9 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		}
 	} else {
 		// Update all fields in the document data (merge)
-		documentData, err = util.JSONToFirestoreValue(documentDataRaw, source.FirestoreClient())
+		documentData, err = fsUtil.JSONToFirestoreValue(documentDataRaw, source.FirestoreClient())
 		if err != nil {
-			return nil, fmt.Errorf("failed to convert document data: %w", err)
+			return nil, util.NewAgentError(fmt.Sprintf("failed to convert document data: %v", err), err)
 		}
 	}
 
@@ -221,7 +223,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if val, ok := mapParams[returnDocumentDataKey].(bool); ok {
 		returnData = val
 	}
-	return source.UpdateDocument(ctx, documentPath, updates, documentData, returnData)
+	resp, err := source.UpdateDocument(ctx, documentPath, updates, documentData, returnData)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 // getFieldValue retrieves a value from a nested map using a dot-separated path

internal/tools/firestore/firestorevalidaterules/firestorevalidaterules.go

@@ -17,11 +17,13 @@ package firestorevalidaterules
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 	"google.golang.org/api/firebaserules/v1"
 )
@@ -106,10 +108,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
@@ -117,9 +119,13 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Get source parameter
 	sourceParam, ok := mapParams[sourceKey].(string)
 	if !ok || sourceParam == "" {
-		return nil, fmt.Errorf("invalid or missing '%s' parameter", sourceKey)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter", sourceKey), nil)
 	}
-	return source.ValidateRules(ctx, sourceParam)
+	resp, err := source.ValidateRules(ctx, sourceParam)
+	if err != nil {
+		return nil, util.ProcessGcpError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/http/http.go

@@ -17,18 +17,18 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"maps"
 	"net/http"
 	"net/url"
 	"slices"
 	"strings"
-
-	"maps"
 	"text/template"
 
 	yaml "github.com/goccy/go-yaml"
 	"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"
 )
 
@@ -226,10 +226,10 @@ func getHeaders(headerParams parameters.Parameters, defaultHeaders map[string]st
 	return allHeaders, nil
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	paramsMap := params.AsMap()
@@ -237,27 +237,35 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Calculate request body
 	requestBody, err := getRequestBody(t.BodyParams, t.RequestBody, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("error populating request body: %s", err)
+		return nil, util.NewAgentError("error populating request body", err)
 	}
 
 	// Calculate URL
 	urlString, err := getURL(source.HttpBaseURL(), t.Path, t.PathParams, t.QueryParams, source.HttpQueryParams(), paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("error populating path parameters: %s", err)
+		return nil, util.NewAgentError("error populating path parameters", err)
 	}
 
-	req, _ := http.NewRequest(string(t.Method), urlString, strings.NewReader(requestBody))
+	req, err := http.NewRequestWithContext(ctx, string(t.Method), urlString, strings.NewReader(requestBody))
+	if err != nil {
+		return nil, util.NewClientServerError("error creating http request", http.StatusInternalServerError, err)
+	}
 
 	// Calculate request headers
 	allHeaders, err := getHeaders(t.HeaderParams, t.Headers, paramsMap)
 	if err != nil {
-		return nil, fmt.Errorf("error populating request headers: %s", err)
+		return nil, util.NewAgentError("error populating request headers", err)
 	}
 	// Set request headers
 	for k, v := range allHeaders {
 		req.Header.Set(k, v)
 	}
-	return source.RunRequest(req)
+
+	resp, err := source.RunRequest(req)
+	if err != nil {
+		return nil, util.ProcessGeneralError(err)
+	}
+	return resp, nil
 }
 
 func (t Tool) EmbedParams(ctx context.Context, paramValues parameters.ParamValues, embeddingModelsMap map[string]embeddingmodels.EmbeddingModel) (parameters.ParamValues, error) {

internal/tools/looker/lookeradddashboardelement/lookeradddashboardelement.go

@@ -16,6 +16,7 @@ package lookeradddashboardelement
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
@@ -134,58 +135,74 @@ var (
 	visType  string = "vis"
 )
 
-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", http.StatusInternalServerError, err)
 	}
 
 	logger, err := util.LoggerFromContext(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("unable to get logger from ctx: %s", err)
+		return nil, util.NewClientServerError("unable to get logger from ctx", http.StatusInternalServerError, err)
 	}
 
 	logger.DebugContext(ctx, "params = ", params)
 
 	wq, err := lookercommon.ProcessQueryArgs(ctx, params)
 	if err != nil {
-		return nil, fmt.Errorf("error building query request: %w", err)
+		return nil, util.NewAgentError("error building query request", err)
 	}
 
 	paramsMap := params.AsMap()
-	dashboard_id := paramsMap["dashboard_id"].(string)
-	title := paramsMap["title"].(string)
 
-	visConfig := paramsMap["vis_config"].(map[string]any)
+	dashboard_id, ok := paramsMap["dashboard_id"].(string)
+	if !ok {
+		return nil, util.NewAgentError("dashboard_id parameter missing or invalid", nil)
+	}
+
+	title, ok := paramsMap["title"].(string)
+	if !ok {
+		title = ""
+	}
+
+	visConfig, ok := paramsMap["vis_config"].(map[string]any)
+	if !ok {
+		visConfig = make(map[string]any)
+	}
 	wq.VisConfig = &visConfig
 
 	sdk, err := source.GetLookerSDK(string(accessToken))
 	if err != nil {
-		return nil, fmt.Errorf("error getting sdk: %w", err)
+		return nil, util.NewClientServerError("error getting sdk", http.StatusInternalServerError, err)
 	}
 
 	qresp, err := sdk.CreateQuery(*wq, "id", source.LookerApiSettings())
 	if err != nil {
-		return nil, fmt.Errorf("error making create query request: %w", err)
+		return nil, util.ProcessGeneralError(err)
 	}
 
 	dashFilters := []any{}
 	if v, ok := paramsMap["dashboard_filters"]; ok {
 		if v != nil {
-			dashFilters = paramsMap["dashboard_filters"].([]any)
+			if df, ok := v.([]any); ok {
+				dashFilters = df
+			}
 		}
 	}
 
 	var filterables []v4.ResultMakerFilterables
 	for _, m := range dashFilters {
-		f := m.(map[string]any)
+		f, ok := m.(map[string]any)
+		if !ok {
+			return nil, util.NewAgentError("invalid dashboard filter structure", nil)
+		}
 		name, ok := f["dashboard_filter_name"].(string)
 		if !ok {
-			return nil, fmt.Errorf("error processing dashboard filter: %w", err)
+			return nil, util.NewAgentError("error processing dashboard filter: missing dashboard_filter_name", nil)
 		}
 		field, ok := f["field"].(string)
 		if !ok {
-			return nil, fmt.Errorf("error processing dashboard filter: %w", err)
+			return nil, util.NewAgentError("error processing dashboard filter: missing field", nil)
 		}
 		listener := v4.ResultMakerFilterablesListen{
 			DashboardFilterName: &name,
@@ -233,7 +250,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	resp, err := sdk.CreateDashboardElement(req, source.LookerApiSettings())
 	if err != nil {
-		return nil, fmt.Errorf("error making create dashboard element request: %w", err)
+		return nil, util.ProcessGeneralError(err)
 	}
 	logger.DebugContext(ctx, "resp = %v", resp)
 

internal/tools/looker/lookeradddashboardfilter/lookeradddashboardfilter.go

@@ -16,6 +16,7 @@ package lookeradddashboardfilter
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
@@ -128,33 +129,54 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	logger, err := util.LoggerFromContext(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("unable to get logger from ctx: %s", err)
+		return nil, util.NewClientServerError("unable to get logger from ctx", http.StatusInternalServerError, err)
 	}
 	logger.DebugContext(ctx, "params = ", params)
 
 	paramsMap := params.AsMap()
-	dashboard_id := paramsMap["dashboard_id"].(string)
+	dashboard_id, ok := paramsMap["dashboard_id"].(string)
-	name := paramsMap["name"].(string)
+	if !ok {
-	title := paramsMap["title"].(string)
+		return nil, util.NewAgentError("dashboard_id parameter missing or invalid", nil)
-	filterType := paramsMap["filter_type"].(string)
+	}
+	name, ok := paramsMap["name"].(string)
+	if !ok {
+		return nil, util.NewAgentError("name parameter missing or invalid", nil)
+	}
+	title, ok := paramsMap["title"].(string)
+	if !ok {
+		return nil, util.NewAgentError("title parameter missing or invalid", nil)
+	}
+	filterType, ok := paramsMap["filter_type"].(string)
+	if !ok {
+		return nil, util.NewAgentError("filter_type parameter missing or invalid", nil)
+	}
+
 	switch filterType {
 	case "date_filter":
 	case "number_filter":
 	case "string_filter":
 	case "field_filter":
 	default:
-		return nil, fmt.Errorf("invalid filter type: %s. Must be one of date_filter, number_filter, string_filter, field_filter", filterType)
+		return nil, util.NewAgentError(fmt.Sprintf("invalid filter type: %s. Must be one of date_filter, number_filter, string_filter, field_filter", filterType), nil)
+	}
+
+	allowMultipleValues, ok := paramsMap["allow_multiple_values"].(bool)
+	if !ok {
+		// defaults should handle this, but safe fallback
+		allowMultipleValues = true
+	}
+	required, ok := paramsMap["required"].(bool)
+	if !ok {
+		required = false
 	}
-	allowMultipleValues := paramsMap["allow_multiple_values"].(bool)
-	required := paramsMap["required"].(bool)
 
 	req := v4.WriteCreateDashboardFilter{
 		DashboardId:         dashboard_id,
@@ -165,9 +187,8 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 		Required:            &required,
 	}
 
-	if v, ok := paramsMap["default_value"]; ok {
+	if v, ok := paramsMap["default_value"]; ok && v != nil {
-		if v != nil {
+		if defaultValue, ok := v.(string); ok {
-			defaultValue := paramsMap["default_value"].(string)
 			req.DefaultValue = &defaultValue
 		}
 	}
@@ -175,15 +196,15 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	if filterType == "field_filter" {
 		model, ok := paramsMap["model"].(string)
 		if !ok || model == "" {
-			return nil, fmt.Errorf("model must be specified for field_filter type")
+			return nil, util.NewAgentError("model must be specified for field_filter type", nil)
 		}
 		explore, ok := paramsMap["explore"].(string)
 		if !ok || explore == "" {
-			return nil, fmt.Errorf("explore must be specified for field_filter type")
+			return nil, util.NewAgentError("explore must be specified for field_filter type", nil)
 		}
 		dimension, ok := paramsMap["dimension"].(string)
 		if !ok || dimension == "" {
-			return nil, fmt.Errorf("dimension must be specified for field_filter type")
+			return nil, util.NewAgentError("dimension must be specified for field_filter type", nil)
 		}
 
 		req.Model = &model
@@ -193,12 +214,12 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	sdk, err := source.GetLookerSDK(string(accessToken))
 	if err != nil {
-		return nil, fmt.Errorf("error getting sdk: %w", err)
+		return nil, util.NewClientServerError("error getting sdk", http.StatusInternalServerError, err)
 	}
 
 	resp, err := sdk.CreateDashboardFilter(req, "name", source.LookerApiSettings())
 	if err != nil {
-		return nil, fmt.Errorf("error making create dashboard filter request: %s", err)
+		return nil, util.ProcessGeneralError(err)
 	}
 	logger.DebugContext(ctx, "resp = %v", resp)
 

internal/tools/looker/lookerconversationalanalytics/lookerconversationalanalytics.go

@@ -215,10 +215,10 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	var tokenStr string
@@ -226,11 +226,11 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Get credentials for the API call
 	// Use cloud-platform token source for Gemini Data Analytics API
 	if t.TokenSource == nil {
-		return nil, fmt.Errorf("cloud-platform token source is missing")
+		return nil, util.NewClientServerError("cloud-platform token source is missing", http.StatusInternalServerError, nil)
 	}
 	token, err := t.TokenSource.Token()
 	if err != nil {
-		return nil, fmt.Errorf("failed to get token from cloud-platform token source: %w", err)
+		return nil, util.NewClientServerError("failed to get token from cloud-platform token source", http.StatusInternalServerError, err)
 	}
 	tokenStr = token.AccessToken
 
@@ -286,7 +286,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	// Call the streaming API
 	response, err := getStream(ctx, caURL, payload, headers)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get response from conversational analytics API: %w", err)
+		return nil, util.NewClientServerError("failed to get response from conversational analytics API", http.StatusInternalServerError, err)
 	}
 
 	return response, nil

internal/tools/looker/lookercreateprojectfile/lookercreateprojectfile.go

@@ -16,12 +16,14 @@ package lookercreateprojectfile
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"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/tools/looker/lookercommon"
+	"github.com/googleapis/genai-toolbox/internal/util"
 	"github.com/googleapis/genai-toolbox/internal/util/parameters"
 
 	"github.com/looker-open-source/sdk-codegen/go/rtl"
@@ -110,29 +112,29 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	sdk, err := source.GetLookerSDK(string(accessToken))
 	if err != nil {
-		return nil, fmt.Errorf("error getting sdk: %w", err)
+		return nil, util.NewClientServerError("error getting sdk", http.StatusInternalServerError, err)
 	}
 
 	mapParams := params.AsMap()
 	projectId, ok := mapParams["project_id"].(string)
 	if !ok {
-		return nil, fmt.Errorf("'project_id' must be a string, got %T", mapParams["project_id"])
+		return nil, util.NewAgentError(fmt.Sprintf("'project_id' must be a string, got %T", mapParams["project_id"]), nil)
 	}
 	filePath, ok := mapParams["file_path"].(string)
 	if !ok {
-		return nil, fmt.Errorf("'file_path' must be a string, got %T", mapParams["file_path"])
+		return nil, util.NewAgentError(fmt.Sprintf("'file_path' must be a string, got %T", mapParams["file_path"]), nil)
 	}
 	fileContent, ok := mapParams["file_content"].(string)
 	if !ok {
-		return nil, fmt.Errorf("'file_content' must be a string, got %T", mapParams["file_content"])
+		return nil, util.NewAgentError(fmt.Sprintf("'file_content' must be a string, got %T", mapParams["file_content"]), nil)
 	}
 
 	req := lookercommon.FileContent{
@@ -142,7 +144,7 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 
 	err = lookercommon.CreateProjectFile(sdk, projectId, req, source.LookerApiSettings())
 	if err != nil {
-		return nil, fmt.Errorf("error making create_project_file request: %s", err)
+		return nil, util.ProcessGeneralError(err)
 	}
 
 	data := make(map[string]any)

internal/tools/looker/lookergetfilters/lookergetfilters.go

@@ -16,6 +16,7 @@ package lookergetfilters
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	yaml "github.com/goccy/go-yaml"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
@@ -109,25 +110,25 @@ func (t Tool) ToConfig() tools.ToolConfig {
 	return t.Config
 }
 
-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", http.StatusInternalServerError, err)
 	}
 
 	logger, err := util.LoggerFromContext(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("unable to get logger from ctx: %s", err)
+		return nil, util.NewClientServerError("unable to get logger from ctx", http.StatusInternalServerError, err)
 	}
 	model, explore, err := lookercommon.ProcessFieldArgs(ctx, params)
 	if err != nil {
-		return nil, fmt.Errorf("error processing model or explore: %w", err)
+		return nil, util.NewAgentError(fmt.Sprintf("error processing model or explore: %v", err), err)
 	}
 
 	fields := lookercommon.FiltersFields
 	sdk, err := source.GetLookerSDK(string(accessToken))
 	if err != nil {
-		return nil, fmt.Errorf("error getting sdk: %w", err)
+		return nil, util.NewClientServerError(fmt.Sprintf("error getting sdk: %v", err), http.StatusInternalServerError, err)
 	}
 	req := v4.RequestLookmlModelExplore{
 		LookmlModelName: *model,
@@ -136,16 +137,16 @@ func (t Tool) Invoke(ctx context.Context, resourceMgr tools.SourceProvider, para
 	}
 	resp, err := sdk.LookmlModelExplore(req, source.LookerApiSettings())
 	if err != nil {
-		return nil, fmt.Errorf("error making get_filters request: %w", err)
+		return nil, util.NewClientServerError(fmt.Sprintf("error making get_filters request: %v", err), http.StatusInternalServerError, err)
 	}
 
 	if err := lookercommon.CheckLookerExploreFields(&resp); err != nil {
-		return nil, fmt.Errorf("error processing get_filters response: %w", err)
+		return nil, util.NewClientServerError(fmt.Sprintf("error processing get_filters response: %v", err), http.StatusInternalServerError, err)
 	}
 
 	data, err := lookercommon.ExtractLookerFieldProperties(ctx, resp.Fields.Filters, source.LookerShowHiddenFields())
 	if err != nil {
-		return nil, fmt.Errorf("error extracting get_filters response: %w", err)
+		return nil, util.NewClientServerError(fmt.Sprintf("error extracting get_filters response: %v", err), http.StatusInternalServerError, err)
 	}
 	logger.DebugContext(ctx, "data = ", data)