feat(prebuilt/cloudsql): Add list instances tool for cloudsql (#1310)

## Description
---
This change introduces a new tool, `cloudsqllistinstance`, to the
`cloudsql` toolset. This tool allows users to list all Cloud SQL
instances within a specified GCP project.

The implementation includes:

- The `cloudsqllistinstance` tool definition and logic, which makes an
authenticated GET request to the `sqladmin.googleapis.com` API.
- The tool takes a single required parameter: `project`.
<img width="654" height="1406" alt="image"
src="https://github.com/user-attachments/assets/7c129a54-acb7-4695-9a0b-215914a6a273"
/>



## PR Checklist
---
> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:
- [x] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md)
- [x] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/langchain-google-alloydb-pg-python/issues/new/choose)
before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea - tracked internally
- [x] Ensure the tests and linter pass
- [x] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)
- [ ] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>

cmd/root.go

@@ -61,6 +61,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhouselistdatabases"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhousesql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudmonitoring"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqllistinstances"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlwaitforoperation"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/couchbase"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/dataplex/dataplexlookupentry"

docs/en/resources/tools/cloudsql/cloudsqllistinstances.md

@@ -0,0 +1,46 @@
+---
+title: Cloud SQL List Instances
+type: docs
+weight: 1
+description: "List Cloud SQL instances in a project.\n"
+---
+
+The `cloud-sql-list-instances` tool lists all Cloud SQL instances in a specified
+Google Cloud project.
+
+{{< notice info >}}
+This tool uses the `cloud-sql-admin` source, which automatically handles authentication on behalf of the user.
+{{< /notice >}}
+
+## Configuration
+
+Here is an example of how to configure the `cloud-sql-list-instances` tool in your
+`tools.yaml` file:
+
+```yaml
+sources:
+  my-cloud-sql-admin-source:
+    kind: cloud-sql-admin
+
+tools:
+  list_my_instances:
+    kind: cloud-sql-list-instances
+    source: my-cloud-sql-admin-source
+    description: Use this tool to list all Cloud SQL instances in a project.
+```
+
+## Parameters
+
+The `cloud-sql-list-instances` tool has one required parameter:
+
+| **field** | **type** | **required** | **description**              |
+| --------- | :------: | :----------: | ---------------------------- |
+| project   |  string  |     true     | The Google Cloud project ID. |
+
+## Reference
+
+| **field**    |  **type** | **required** | **description**                                                                     |
+| ------------ | :-------: | :----------: | ----------------------------------------------------------------------------------- |
+| kind         |   string  |     true     | Must be "cloud-sql-list-instances".                                                 |
+| description  |   string  |     false     | Description of the tool that is passed to the agent.                                |
+| source       |   string  |     true     | The name of the `cloud-sql-admin` source to use for this tool.                      |

internal/tools/cloudsql/cloudsqllistinstances/cloudsqllistinstances.go

@@ -0,0 +1,192 @@
+// Copyright 2025 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 cloudsqllistinstances
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/goccy/go-yaml"
+	"github.com/googleapis/genai-toolbox/internal/sources"
+	cloudsqladminsrc "github.com/googleapis/genai-toolbox/internal/sources/cloudsqladmin"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+)
+
+const kind string = "cloud-sql-list-instances"
+
+func init() {
+	if !tools.Register(kind, newConfig) {
+		panic(fmt.Sprintf("tool kind %q already registered", kind))
+	}
+}
+
+func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.ToolConfig, error) {
+	actual := Config{Name: name}
+	if err := decoder.DecodeContext(ctx, &actual); err != nil {
+		return nil, err
+	}
+	return actual, nil
+}
+
+// Config defines the configuration for the list-instance tool.
+type Config struct {
+	Name         string   `yaml:"name" validate:"required"`
+	Kind         string   `yaml:"kind" validate:"required"`
+	Source       string   `yaml:"source" validate:"required"`
+	Description  string   `yaml:"description"`
+	AuthRequired []string `yaml:"authRequired"`
+}
+
+// validate interface
+var _ tools.ToolConfig = Config{}
+
+// ToolConfigKind returns the kind of the tool.
+func (cfg Config) ToolConfigKind() string {
+	return kind
+}
+
+// Initialize initializes the tool from the configuration.
+func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error) {
+	rawS, ok := srcs[cfg.Source]
+	if !ok {
+		return nil, fmt.Errorf("no source named %q configured", cfg.Source)
+	}
+	s, ok := rawS.(*cloudsqladminsrc.Source)
+	if !ok {
+		return nil, fmt.Errorf("invalid source for %q tool: source kind must be `cloud-sql-admin`", kind)
+	}
+
+	allParameters := tools.Parameters{
+		tools.NewStringParameter("project", "The project ID"),
+	}
+	paramManifest := allParameters.Manifest()
+
+	inputSchema := allParameters.McpManifest()
+	inputSchema.Required = []string{"project"}
+
+	description := cfg.Description
+	if description == "" {
+		description = "Lists all type of Cloud SQL instances for a project."
+	}
+
+	mcpManifest := tools.McpManifest{
+		Name:        cfg.Name,
+		Description: description,
+		InputSchema: inputSchema,
+	}
+
+	return Tool{
+		Name:         cfg.Name,
+		Kind:         kind,
+		AuthRequired: cfg.AuthRequired,
+		source:       s,
+		AllParams:    allParameters,
+		manifest:     tools.Manifest{Description: description, Parameters: paramManifest, AuthRequired: cfg.AuthRequired},
+		mcpManifest:  mcpManifest,
+	}, nil
+}
+
+// Tool represents the list-instance tool.
+type Tool struct {
+	Name         string   `yaml:"name"`
+	Kind         string   `yaml:"kind"`
+	Description  string   `yaml:"description"`
+	AuthRequired []string `yaml:"authRequired"`
+
+	AllParams   tools.Parameters `yaml:"allParams"`
+	source      *cloudsqladminsrc.Source
+	manifest    tools.Manifest
+	mcpManifest tools.McpManifest
+}
+
+// Invoke executes the tool's logic.
+func (t Tool) Invoke(ctx context.Context, params tools.ParamValues, accessToken tools.AccessToken) (any, error) {
+	paramsMap := params.AsMap()
+
+	project, ok := paramsMap["project"].(string)
+	if !ok {
+		return nil, fmt.Errorf("missing 'project' parameter")
+	}
+
+	client, err := t.source.GetClient(ctx, string(accessToken))
+	if err != nil {
+		return nil, err
+	}
+
+	urlString := fmt.Sprintf("%s/v1/projects/%s/instances", t.source.BaseURL, project)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, urlString, nil)
+	if err != nil {
+		return nil, fmt.Errorf("error creating request: %w", err)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("error making HTTP request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("error reading response body: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("unexpected status code: %d, response body: %s", resp.StatusCode, string(body))
+	}
+
+	var v struct {
+		Items []struct {
+			Name         string `json:"name"`
+			InstanceType string `json:"instanceType"`
+		} `json:"items"`
+	}
+
+	if err := json.Unmarshal(body, &v); err != nil {
+		return nil, fmt.Errorf("error unmarshaling response body: %w", err)
+	}
+
+	if v.Items == nil {
+		return []any{}, nil
+	}
+
+	return v.Items, nil
+}
+
+// ParseParams parses the parameters for the tool.
+func (t Tool) ParseParams(data map[string]any, claims map[string]map[string]any) (tools.ParamValues, error) {
+	return tools.ParseParams(t.AllParams, data, claims)
+}
+
+// Manifest returns the tool's manifest.
+func (t Tool) Manifest() tools.Manifest {
+	return t.manifest
+}
+
+// McpManifest returns the tool's MCP manifest.
+func (t Tool) McpManifest() tools.McpManifest {
+	return t.mcpManifest
+}
+
+// Authorized checks if the tool is authorized.
+func (t Tool) Authorized(verifiedAuthServices []string) bool {
+	return true
+}
+
+func (t Tool) RequiresClientAuthorization() bool {
+	return t.source.UseClientAuthorization()
+}

internal/tools/cloudsql/cloudsqllistinstances/cloudsqllistinstances_test.go

@@ -0,0 +1,71 @@
+// Copyright 2025 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 cloudsqllistinstances
+
+import (
+	"testing"
+
+	"github.com/goccy/go-yaml"
+	"github.com/google/go-cmp/cmp"
+	"github.com/googleapis/genai-toolbox/internal/server"
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+)
+
+func TestParseFromYaml(t *testing.T) {
+	ctx, err := testutils.ContextWithNewLogger()
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	tcs := []struct {
+		desc string
+		in   string
+		want server.ToolConfigs
+	}{
+		{
+			desc: "basic example",
+			in: `
+			tools:
+				list-my-instances:
+					kind: cloud-sql-list-instances
+					description: some description
+					source: some-source
+			`,
+			want: server.ToolConfigs{
+				"list-my-instances": Config{
+					Name:         "list-my-instances",
+					Kind:         "cloud-sql-list-instances",
+					Description:  "some description",
+					AuthRequired: []string{},
+					Source:       "some-source",
+				},
+			},
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			got := struct {
+				Tools server.ToolConfigs `yaml:"tools"`
+			}{}
+			// Parse contents
+			err := yaml.UnmarshalContext(ctx, testutils.FormatYaml(tc.in), &got)
+			if err != nil {
+				t.Fatalf("unable to unmarshal: %s", err)
+			}
+			if diff := cmp.Diff(tc.want, got.Tools); diff != "" {
+				t.Fatalf("incorrect parse: diff %v", diff)
+			}
+		})
+	}
+}

tests/cloudsql/cloudsql_list_instances_test.go

@@ -0,0 +1,190 @@
+// Copyright 2025 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 cloudsql
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"reflect"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqllistinstances"
+	"github.com/googleapis/genai-toolbox/tests"
+)
+
+type transport struct {
+	transport http.RoundTripper
+	url       *url.URL
+}
+
+func (t *transport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if strings.HasPrefix(req.URL.String(), "https://sqladmin.googleapis.com") {
+		req.URL.Scheme = t.url.Scheme
+		req.URL.Host = t.url.Host
+	}
+	return t.transport.RoundTrip(req)
+}
+
+func TestListInstance(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/projects/test-project/instances" {
+			http.Error(w, fmt.Sprintf("unexpected path: got %q", r.URL.Path), http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintln(w, `{"items": [{"name": "test-instance", "instanceType": "CLOUD_SQL_INSTANCE"}]}`)
+	}))
+	defer server.Close()
+
+	serverURL, err := url.Parse(server.URL)
+	if err != nil {
+		t.Fatalf("failed to parse server URL: %v", err)
+	}
+
+	originalTransport := http.DefaultClient.Transport
+	if originalTransport == nil {
+		originalTransport = http.DefaultTransport
+	}
+	http.DefaultClient.Transport = &transport{
+		transport: originalTransport,
+		url:       serverURL,
+	}
+	t.Cleanup(func() {
+		http.DefaultClient.Transport = originalTransport
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	var args []string
+
+	toolsFile := getListInstanceToolsConfig()
+	cmd, cleanup, err := tests.StartCmd(ctx, toolsFile, args...)
+	if err != nil {
+		t.Fatalf("command initialization returned an error: %s", err)
+	}
+	defer cleanup()
+
+	waitCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	out, err := testutils.WaitForString(waitCtx, regexp.MustCompile("Server ready to serve"), cmd.Out)
+	if err != nil {
+		t.Logf("toolbox command logs: \n%s", out)
+		t.Fatalf("toolbox didn't start successfully: %s", err)
+	}
+
+	tcs := []struct {
+		name        string
+		toolName    string
+		body        string
+		want        string
+		expectError bool
+	}{
+		{
+			name:     "successful operation",
+			toolName: "list-instances",
+			body:     `{"project": "test-project"}`,
+			want:     `[{"name":"test-instance","instanceType":"CLOUD_SQL_INSTANCE"}]`,
+		},
+		{
+			name:        "failed operation",
+			toolName:    "list-instances-fail",
+			body:        `{"project": "test-project"}`,
+			expectError: true,
+		},
+	}
+
+	for _, tc := range tcs {
+		t.Run(tc.name, func(t *testing.T) {
+			api := fmt.Sprintf("http://127.0.0.1:5000/api/tool/%s/invoke", tc.toolName)
+			req, err := http.NewRequest(http.MethodPost, api, bytes.NewBufferString(tc.body))
+			if err != nil {
+				t.Fatalf("unable to create request: %s", err)
+			}
+			req.Header.Add("Content-type", "application/json")
+			resp, err := http.DefaultClient.Do(req)
+			if err != nil {
+				t.Fatalf("unable to send request: %s", err)
+			}
+			defer resp.Body.Close()
+
+			if tc.expectError {
+				if resp.StatusCode == http.StatusOK {
+					t.Fatal("expected error but got status 200")
+				}
+				return
+			}
+
+			if resp.StatusCode != http.StatusOK {
+				bodyBytes, _ := io.ReadAll(resp.Body)
+				t.Fatalf("response status code is not 200, got %d: %s", resp.StatusCode, string(bodyBytes))
+			}
+
+			var result struct {
+				Result string `json:"result"`
+			}
+			if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+				t.Fatalf("failed to decode response: %v", err)
+			}
+
+			var got, want any
+			if err := json.Unmarshal([]byte(result.Result), &got); err != nil {
+				t.Fatalf("failed to unmarshal result: %v", err)
+			}
+			if err := json.Unmarshal([]byte(tc.want), &want); err != nil {
+				t.Fatalf("failed to unmarshal want: %v", err)
+			}
+
+			if !reflect.DeepEqual(got, want) {
+				t.Fatalf("unexpected result: got %+v, want %+v", got, want)
+			}
+		})
+	}
+}
+
+func getListInstanceToolsConfig() map[string]any {
+	return map[string]any{
+		"sources": map[string]any{
+			"my-cloud-sql-source": map[string]any{
+				"kind": "cloud-sql-admin",
+			},
+			"my-invalid-cloud-sql-source": map[string]any{
+				"kind":           "cloud-sql-admin",
+				"useClientOAuth": true,
+			},
+		},
+		"tools": map[string]any{
+			"list-instances": map[string]any{
+				"kind":   "cloud-sql-list-instances",
+				"source": "my-cloud-sql-source",
+			},
+			"list-instances-fail": map[string]any{
+				"kind":        "cloud-sql-list-instances",
+				"description": "list instances",
+				"source":      "my-invalid-cloud-sql-source",
+			},
+		},
+	}
+}