feat(tools/cloudsqlpg): Add vector assist tools for Cloud SQL Postgres (#2909)

## Description

Adds 4 new mcp tools for Cloud SQL Postgres source related to the vector
assist postgres extension. These tools enable the customers to set up
and optimize production-ready vector workloads by simply expressing your
intent and performance requirements.



| Tool Set | Description |

|:---------------------------------|:------------------------------------------------------------------------
|
| `vectorassist` | Use these skills to set up and optimize
production-ready vector workloads |
| | by simply expressing your intent and performance requirements |


| Tool Name | Description |

|:---------------------------------|:---------------------------------------------------------------|
| `define_spec` | Defines a new vector specification for search
workloads. |
| `modify_spec` | Modifies an existing vector specification. |
| `apply_spec` | Executes SQL recommendations for a vector
specification. |
| `generate_query` | Generates optimized SQL queries for vector
searches. |


## Manual testing

Workflows covered by these tools 

### 1.  Setup vector search in the database

Prompt : Set up the table 'cymbal_products' for vector workloads where I
want to perform a similarity search on the embeddings generated for the
column 'product_description'.

Expected tools to be used in the CUJ : define-spec -> apply-spec

<img width="1282" height="639" alt="Screenshot 2026-04-09 at 2 50 02 PM"
src="https://github.com/user-attachments/assets/0c05fb23-88df-4c26-9dd3-59678ed6cc90"
/>

<img width="1289" height="717" alt="Screenshot 2026-04-09 at 2 52 34 PM"
src="https://github.com/user-attachments/assets/e1a2e4ea-cadc-4692-b0f5-dc4c914710a6"
/>

<img width="1270" height="683" alt="Screenshot 2026-04-09 at 3 04 17 PM"
src="https://github.com/user-attachments/assets/a2ac1349-5815-45c1-abc6-fd8210a5570f"
/>
<img width="1281" height="462" alt="Screenshot 2026-04-09 at 3 06 12 PM"
src="https://github.com/user-attachments/assets/bce60906-2723-4a64-aaa0-9095fc83466b"
/>


### 2. Modify & apply spec

Prompt : Modify the vector specification 'cymbal_products' table to
generate embeddings on the column 'product_description' using the
embedding model 'text-embedding-004'

Expected tools to be used in the CUJ : define-spec -> modify-spec ->
apply-spec

<img width="1180" height="798" alt="Screenshot 2026-04-09 at 9 45 03 PM"
src="https://github.com/user-attachments/assets/d8566527-a04d-4209-b78f-693ffb8e9298"
/>

<img width="1171" height="373" alt="Screenshot 2026-04-09 at 9 35 27 PM"
src="https://github.com/user-attachments/assets/b6c894c3-1c6f-4d4b-85d1-59832d097b4f"
/>

<img width="1175" height="598" alt="Screenshot 2026-04-09 at 9 37 11 PM"
src="https://github.com/user-attachments/assets/45c79bb5-5509-4196-84c9-0e091fd1168f"
/>

<img width="1176" height="622" alt="Screenshot 2026-04-09 at 9 39 12 PM"
src="https://github.com/user-attachments/assets/5eaffd4c-5315-482f-8616-a3c4503a65ef"
/>

### 3.  Find top-k similarity items

Prompt : find the top 10 products from cymbal_products table which have
description similar to this query "What kind of fruit trees grow well
here?"
 
Expected tools to be used in the CUJ : generate-query -> execute-sql

<img width="1273" height="259" alt="Screenshot 2026-04-09 at 3 25 48 PM"
src="https://github.com/user-attachments/assets/79d71a31-a9ce-4948-aa75-d35dc33f4420"
/>

<img width="1275" height="483" alt="Screenshot 2026-04-09 at 3 26 12 PM"
src="https://github.com/user-attachments/assets/2d54327d-c048-457e-9e44-4c710e1523d3"
/>

<img width="1246" height="619" alt="Screenshot 2026-04-09 at 3 27 12 PM"
src="https://github.com/user-attachments/assets/d2a1a021-f179-4d86-9050-50a2dbefac64"
/>




## 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/genai-toolbox/issues/new/choose)
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [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)
- [x] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Wenxin Du <117315983+duwenxin99@users.noreply.github.com>

Author: 3 people

cmd/internal/config_test.go

@@ -1747,6 +1747,10 @@ func TestPrebuiltTools(t *testing.T) {
 					Name:      "replication",
 					ToolNames: []string{"replication_stats", "list_replication_slots", "list_publication_tables", "list_roles", "list_pg_settings", "database_overview"},
 				},
+				"vectorassist": {
+					Name:      "vectorassist",
+					ToolNames: []string{"execute_sql", "define_spec", "modify_spec", "apply_spec", "generate_query"},
+				},
 			},
 		},
 		{

cmd/internal/imports.go

@@ -79,6 +79,10 @@ import (
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlmysql/cloudsqlmysqlcreateinstance"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlpg/cloudsqlpgcreateinstances"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlpg/cloudsqlpgupgradeprecheck"
+	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlpg/vectorassistapplyspec"
+	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlpg/vectorassistdefinespec"
+	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlpg/vectorassistgeneratequery"
+	_ "github.com/googleapis/mcp-toolbox/internal/tools/cloudsqlpg/vectorassistmodifyspec"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/cockroachdb/cockroachdbexecutesql"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/cockroachdb/cockroachdblistschemas"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/cockroachdb/cockroachdblisttables"

docs/CLOUDSQLPG_README.md

@@ -72,6 +72,10 @@ The Cloud SQL for PostgreSQL MCP server provides the following tools:
 | `list_triggers`                  | Lists all non-internal triggers in a database.                 |
 | `list_indexes`                   | Lists available user indexes in the database.                  |
 | `list_sequences`                 | Lists sequences in the database.                               |
+| `define_spec`                    | Defines a new vector specification for search workloads.       |
+| `modify_spec`                    | Modifies an existing vector specification.                     |
+| `apply_spec`                     | Executes SQL recommendations for a vector specification.       | 
+| `generate_query`                 | Generates optimized SQL queries for vector searches.           |
 
 
 ## Custom MCP Server Configuration

docs/en/integrations/cloud-sql-pg/tools/vector-assist-apply-spec.md

@@ -0,0 +1,59 @@
+---
+title: "vector-assist-apply-spec"
+type: docs
+weight: 1
+description: >
+  The "vector-assist-apply-spec" tool automatically executes all SQL recommendations
+  associated with a specific vector specification or table to finalize the
+  vector search setup.
+---
+
+## About
+
+The `vector-assist-apply-spec` tool automatically executes all the SQL recommendations associated with a specific vector specification (spec_id) or table. It runs the necessary commands in the correct sequence to provision the workload, marking each step as applied once successful. 
+
+Use this tool when the user has reviewed the generated recommendations from a defined (or modified) spec and is ready to apply the changes directly to their database instance to finalize the vector search setup. Under the hood, this tool connects to the target database and executes the `vector_assist.apply_spec` function.
+
+## Compatible Sources
+
+{{< compatible-sources >}}
+
+## Requirements
+
+{{< notice tip >}} 
+Ensure that your target PostgreSQL database has the required `vector_assist` extension installed, in order for this tool to execute successfully.
+{{< /notice >}}
+
+## Parameters
+
+The tool takes the following input parameters:
+
+| Parameter     | Type   | Description                                                           | Required |
+| :------------ | :----- | :-------------------------------------------------------------------- | :------- |
+| `spec_id`     | string | Unique ID of the vector specification to apply.                       | No       |
+| `table_name`  | string | Target table name for applying the vector specification.              | No       |
+| `column_name` | string | Text or vector column name to uniquely identify the specification.    | No       |
+| `schema_name` | string | Schema name for the target table.                                     | No       |
+
+> Note
+> Parameters are marked as required or optional based on the vector assist function definitions. 
+> The function may perform further validation on optional parameters to ensure all necessary 
+> data is available before returning a response.
+
+## Example
+
+```yaml
+kind: tool
+name: apply_spec
+type: vector-assist-apply-spec
+source: my-database-source
+description: "This tool automatically executes all the SQL recommendations associated with a specific vector specification (spec_id) or table. It runs the necessary commands in the correct sequence to provision the workload, marking each step as applied once successful. Use this tool when the user has reviewed the generated recommendations from a defined (or modified) spec and is ready to apply the changes directly to their database instance to finalize the vector search setup."
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                      |
+|-------------|:--------:|:------------:|------------------------------------------------------|
+| type        |  string  |     true     | Must be "vector-assist-apply-spec".                 |
+| source      |  string  |     true     | Name of the source the SQL should execute on.        |
+| description |  string  |    false     | Description of the tool that is passed to the agent. |

docs/en/integrations/cloud-sql-pg/tools/vector-assist-define-spec.md

@@ -0,0 +1,73 @@
+---
+title: "vector-assist-define-spec"
+type: docs
+weight: 1
+description: >
+  The "vector-assist-define-spec" tool defines a new vector specification by
+  capturing the user's intent and requirements for a vector search workload,
+  generating SQL recommendations for setting up database, embeddings, and
+  vector indexes.
+---
+
+## About
+
+The `vector-assist-define-spec` tool defines a new vector specification by capturing the user's intent and requirements for a vector search workload. It generates a complete, ordered set of SQL recommendations required to set up the database, embeddings, and vector indexes. 
+
+Use this tool at the very beginning of the vector setup process when an agent or user first wants to configure a table for vector search, generate embeddings, or create a new vector index. Under the hood, this tool connects to the target database and executes the `vector_assist.define_spec` function to generate the necessary specifications.
+
+## Compatible Sources
+
+{{< compatible-sources >}}
+
+## Requirements
+
+{{< notice tip >}} 
+Ensure that your target PostgreSQL database has the required `vector_assist` extension installed, in order for this tool to execute successfully.
+{{< /notice >}}
+
+## Parameters
+
+The tool takes the following input parameters:
+
+| Parameter                | Type    | Description                                                            | Required |
+| :----------------------- | :------ | :--------------------------------------------------------------------- | :------- |
+| `table_name`             | string  | Target table name for setting up the vector workload.                  | Yes      |
+| `schema_name`            | string  | Name of the schema containing the target table.                        | No       |
+| `spec_id`                | string  | Unique ID for the vector specification; auto-generated if omitted.     | No       |
+| `vector_column_name`     | string  | Name of the column containing the vector embeddings.                   | No       |
+| `text_column_name`       | string  | Name of the text column for setting up vector search.                  | No       |
+| `vector_index_type`      | string  | Type of vector index ('hnsw', 'ivfflat', or 'scann').                  | No       |
+| `embeddings_available`   | boolean | Indicates if vector embeddings already exist in the table.             | No       |
+| `num_vectors`            | integer | Expected total number of vectors in the dataset.                       | No       |
+| `dimensionality`         | integer | Dimension of existing vectors or the chosen embedding model.           | No       |
+| `embedding_model`        | string  | Model to be used for generating vector embeddings.                     | No       |
+| `prefilter_column_names` | array   | List of columns to use for prefiltering vector queries.                | No       |
+| `distance_func`          | string  | Distance function for comparing vectors ('cosine', 'ip', 'l2', 'l1').  | No       |
+| `quantization`           | string  | Quantization method for vector indexes ('none', 'halfvec', 'bit').     | No       |
+| `memory_budget_kb`       | integer | Maximum memory (in KB) the index can use during build.                 | No       |
+| `target_recall`          | float   | Target recall rate for standard vector queries using this index.       | No       |
+| `target_top_k`           | integer | Number of top results (top-K) to retrieve per query.                   | No       |
+| `tune_vector_index`      | boolean | Indicates whether automatic tuning is required for the index.          | No       |
+
+> Note
+> Parameters are marked as required or optional based on the vector assist function definitions. 
+> The function may perform further validation on optional parameters to ensure all necessary 
+> data is available before returning a response.
+
+## Example
+
+```yaml
+kind: tool
+name: define_spec
+type: vector-assist-define-spec
+source: my-database-source
+description: "This tool defines a new vector specification by capturing the user's intent and requirements for a vector search workload. This generates a complete, ordered set of SQL recommendations required to set up the database, embeddings, and vector indexes. Use this tool at the very beginning of the vector setup process when a user first wants to configure a table for vector search, generate embeddings, or create a new vector index."
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                      |
+|-------------|:--------:|:------------:|------------------------------------------------------|
+| type        |  string  |     true     | Must be "vector-assist-define-spec".                 |
+| source      |  string  |     true     | Name of the source the SQL should execute on.        |
+| description |  string  |    false     | Description of the tool that is passed to the agent. |

docs/en/integrations/cloud-sql-pg/tools/vector-assist-generate-query.md

@@ -0,0 +1,65 @@
+---
+title: "vector-assist-generate-query"
+type: docs
+weight: 1
+description: >
+  The "vector-assist-generate-query" tool produces optimized SQL queries for
+  vector search, leveraging metadata and specifications to enable semantic
+  and similarity searches.
+---
+
+## About
+
+The `vector-assist-generate-query` tool generates optimized SQL queries for vector search by leveraging the metadata and vector specifications defined in a specific spec_id. It serves as the primary actionable tool for generating the executable SQL required to retrieve relevant results based on vector similarity.
+
+The tool contextually understands requirements such as distance functions, quantization, and filtering to ensure the resulting query is compatible with the corresponding vector index. Additionally, it can automatically handle iterative index scans for filtered queries and calculate the necessary search parameters (like ef_search) to meet a target recall.
+## Compatible Sources
+
+{{< compatible-sources >}}
+
+## Requirements
+
+{{< notice tip >}} 
+Ensure that your target PostgreSQL database has the required `vector_assist` extension installed, in order for this tool to execute successfully.
+{{< /notice >}}
+
+## Parameters
+
+The tool takes the following input parameters:
+
+| Parameter                | Type    | Description                                                         | Required |
+| :----------------------- | :------ | :------------------------------------------------------------------ | :------- |
+| `spec_id`                | string  | Unique ID of the vector spec for query generation.                  | No       |
+| `table_name`             | string  | Target table name for generating the vector query.                  | No       |
+| `schema_name`            | string  | Schema name for the query's target table.                           | No       |
+| `column_name`            | string  | Text or vector column name identifying the specific spec.           | No       |
+| `search_text`            | string  | Text string to search for; embeddings are auto-generated.           | No       |
+| `search_vector`          | string  | Vector to search for; use instead of search_text.                   | No       |
+| `output_column_names`    | array   | List of columns to retrieve in the search results.                  | No       |
+| `top_k`                  | integer | Number of nearest neighbors to return (defaults to 10).             | No       |
+| `filter_expressions`     | array   | List of filter expressions applied to the vector query.             | No       |
+| `target_recall`          | float   | Target recall rate, overriding the spec-level default.              | No       |
+| `iterative_index_search` | boolean | Enables iterative search for filtered queries to guarantee results. | No       |
+
+> Note
+> Parameters are marked as required or optional based on the vector assist function definitions. 
+> The function may perform further validation on optional parameters to ensure all necessary 
+> data is available before returning a response.
+
+## Example
+
+```yaml
+kind: tool
+name: generate_query
+type: vector-assist-generate-query
+source: my-database-source
+description: "This tool generates optimized SQL queries for vector search by leveraging the metadata and vector specifications defined in a specific spec_id. It may return a single query or a sequence of multiple SQL queries that can be executed sequentially. Use this tool when a user wants to perform semantic or similarity searches on their data. It serves as the primary actionable tool to invoke for generating the executable SQL required to retrieve relevant results based on vector similarity."
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                      |
+|-------------|:--------:|:------------:|------------------------------------------------------|
+| type        |  string  |     true     | Must be "vector-assist-generate-query".                 |
+| source      |  string  |     true     | Name of the source the SQL should execute on.        |
+| description |  string  |    false     | Description of the tool that is passed to the agent. |

docs/en/integrations/cloud-sql-pg/tools/vector-assist-modify-spec.md

@@ -0,0 +1,72 @@
+---
+title: "vector-assist-modify-spec"
+type: docs
+weight: 1
+description: >
+  The "vector-assist-modify-spec" tool modifies an existing vector specification
+  with new parameters or overrides, recalculating the generated SQL
+  recommendations to match the updated requirements.
+---
+
+## About
+
+The `vector-assist-modify-spec` tool modifies an existing vector specification (identified by a required `spec_id`) with new parameters or overrides. Upon modification, it automatically recalculates and refreshes the list of generated recommendations by `vector_assist.define-spec` to match the updated spec requirements. 
+
+Use this tool when a user or agent wants to adjust or fine-tune the configuration of an already defined vector spec (such as changing the target recall, embedding model, or quantization) before actually executing the setup commands. Under the hood, this tool connects to the target database and executes the `vector_assist.modify_spec` function to generate the updated specifications.
+
+## Compatible Sources
+
+{{< compatible-sources >}}
+
+## Requirements
+
+{{< notice tip >}} 
+Ensure that your target PostgreSQL database has the required `vector_assist` extension installed, and that the `vector_assist.modify_spec` function is available in order for this tool to execute successfully.
+{{< /notice >}}
+
+## Parameters
+
+The tool takes the following input parameters:
+
+| Parameter                | Type    | Description                                                            | Required |
+| :----------------------- | :------ | :--------------------------------------------------------------------- | :------- |
+| `spec_id`                | string  | Unique ID of the vector specification to modify.                       | Yes      |
+| `table_name`             | string  | New table name for the vector workload setup.                          | No       |
+| `schema_name`            | string  | New schema name containing the target table.                           | No       |
+| `vector_column_name`     | string  | New name for the column containing vector embeddings.                  | No       |
+| `text_column_name`       | string  | New name for the text column for vector search.                        | No       |
+| `vector_index_type`      | string  | New vector index type ('hnsw', 'ivfflat', or 'scann').                 | No       |
+| `embeddings_available`   | boolean | Update if vector embeddings already exist in the table.                | No       |
+| `num_vectors`            | integer | Update the expected total number of vectors.                           | No       |
+| `dimensionality`         | integer | Update the dimension of vectors or the embedding model.                | No       |
+| `embedding_model`        | string  | Update the model used for generating vector embeddings.                | No       |
+| `prefilter_column_names` | array   | Update the columns used for prefiltering vector queries.               | No       |
+| `distance_func`          | string  | Update the distance function ('cosine', 'ip', 'l2', 'l1').             | No       |
+| `quantization`           | string  | Update the quantization method ('none', 'halfvec', 'bit').             | No       |
+| `memory_budget_kb`       | integer | Update maximum memory (in KB) for index building.                      | No       |
+| `target_recall`          | float   | Update the target recall rate for the index.                           | No       |
+| `target_top_k`           | integer | Update the number of top results (top-K) to retrieve.                  | No       |
+| `tune_vector_index`      | boolean | Update whether automatic tuning is required for the index.             | No       |
+
+> Note
+> Parameters are marked as required or optional based on the vector assist function definitions. 
+> The function may perform further validation on optional parameters to ensure all necessary 
+> data is available before returning a response.
+
+## Example
+
+```yaml
+kind: tool
+name: modify_spec
+type: vector-assist-modify-spec
+source: my-database-source
+description: "This tool modifies an existing vector specification (identified by a required spec_id) with new parameters or overrides. Upon modification, it automatically recalculates and refreshes the list of generated SQL recommendations to match the updated requirements. Use this tool when a user wants to adjust or fine-tune the configuration of an already defined vector spec (such as changing the target recall, embedding model, or quantization) before actually executing the setup commands."
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                      |
+|-------------|:--------:|:------------:|------------------------------------------------------|
+| type        |  string  |     true     | Must be "vector-assist-modify-spec".                 |
+| source      |  string  |     true     | Name of the source the SQL should execute on.        |
+| description |  string  |    false     | Description of the tool that is passed to the agent. |