feat(tools/postgres-list-tablespaces): add new postgres-list-tablespaces tool (#1934)

## Description
Adds a postgresql custom list_tablespaces tool, that returns the details
of tablespaces present in database.

<img width="1719" height="698" alt="Screenshot 2025-11-12 at 9 11 13 AM"
src="https://github.com/user-attachments/assets/03964a1b-27e0-4da8-85a2-57db905163ed"
/>
<img width="1077" height="141" alt="Screenshot 2025-11-12 at 9 12 42 AM"
src="https://github.com/user-attachments/assets/f93f5692-eb62-4f30-8192-40c8873d4d00"
/>


> Should include a concise description of the changes (bug or feature),
it's
> impact, along with a summary of the solution

Lists all tablespaces in the database. Returns the tablespace name,
owner name, size in bytes, internal object ID, the access control list
regarding permissions, and any specific tablespace options.

## 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 #1738

Author: srividyareddy786

cmd/root.go

@@ -192,6 +192,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslistschemas"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslistsequences"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslisttables"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslisttablespaces"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslisttriggers"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslistviews"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/postgres/postgreslongrunningtransactions"

cmd/root_test.go

@@ -1488,7 +1488,7 @@ func TestPrebuiltTools(t *testing.T) {
 			wantToolset: server.ToolsetConfigs{
 				"alloydb_postgres_database_tools": tools.ToolsetConfig{
 					Name:      "alloydb_postgres_database_tools",
-					ToolNames: []string{"execute_sql", "list_tables", "list_active_queries", "list_available_extensions", "list_installed_extensions", "list_autovacuum_configurations", "list_memory_configurations", "list_top_bloated_tables", "list_replication_slots", "list_invalid_indexes", "get_query_plan", "list_views", "list_schemas", "database_overview", "list_triggers", "list_indexes", "list_sequences", "long_running_transactions", "list_locks", "replication_stats", "list_query_stats", "get_column_cardinality", "list_publication_tables"},
+					ToolNames: []string{"execute_sql", "list_tables", "list_active_queries", "list_available_extensions", "list_installed_extensions", "list_autovacuum_configurations", "list_memory_configurations", "list_top_bloated_tables", "list_replication_slots", "list_invalid_indexes", "get_query_plan", "list_views", "list_schemas", "database_overview", "list_triggers", "list_indexes", "list_sequences", "long_running_transactions", "list_locks", "replication_stats", "list_query_stats", "get_column_cardinality", "list_publication_tables", "list_tablespaces"},
 				},
 			},
 		},
@@ -1518,7 +1518,7 @@ func TestPrebuiltTools(t *testing.T) {
 			wantToolset: server.ToolsetConfigs{
 				"cloud_sql_postgres_database_tools": tools.ToolsetConfig{
 					Name:      "cloud_sql_postgres_database_tools",
-					ToolNames: []string{"execute_sql", "list_tables", "list_active_queries", "list_available_extensions", "list_installed_extensions", "list_autovacuum_configurations", "list_memory_configurations", "list_top_bloated_tables", "list_replication_slots", "list_invalid_indexes", "get_query_plan", "list_views", "list_schemas", "database_overview", "list_triggers", "list_indexes", "list_sequences", "long_running_transactions", "list_locks", "replication_stats", "list_query_stats", "get_column_cardinality", "list_publication_tables"},
+					ToolNames: []string{"execute_sql", "list_tables", "list_active_queries", "list_available_extensions", "list_installed_extensions", "list_autovacuum_configurations", "list_memory_configurations", "list_top_bloated_tables", "list_replication_slots", "list_invalid_indexes", "get_query_plan", "list_views", "list_schemas", "database_overview", "list_triggers", "list_indexes", "list_sequences", "long_running_transactions", "list_locks", "replication_stats", "list_query_stats", "get_column_cardinality", "list_publication_tables", "list_tablespaces"},
 				},
 			},
 		},
@@ -1618,7 +1618,7 @@ func TestPrebuiltTools(t *testing.T) {
 			wantToolset: server.ToolsetConfigs{
 				"postgres_database_tools": tools.ToolsetConfig{
 					Name:      "postgres_database_tools",
-					ToolNames: []string{"execute_sql", "list_tables", "list_active_queries", "list_available_extensions", "list_installed_extensions", "list_autovacuum_configurations", "list_memory_configurations", "list_top_bloated_tables", "list_replication_slots", "list_invalid_indexes", "get_query_plan", "list_views", "list_schemas", "database_overview", "list_triggers", "list_indexes", "list_sequences", "long_running_transactions", "list_locks", "replication_stats", "list_query_stats", "get_column_cardinality", "list_publication_tables"},
+					ToolNames: []string{"execute_sql", "list_tables", "list_active_queries", "list_available_extensions", "list_installed_extensions", "list_autovacuum_configurations", "list_memory_configurations", "list_top_bloated_tables", "list_replication_slots", "list_invalid_indexes", "get_query_plan", "list_views", "list_schemas", "database_overview", "list_triggers", "list_indexes", "list_sequences", "long_running_transactions", "list_locks", "replication_stats", "list_query_stats", "get_column_cardinality", "list_publication_tables", "list_tablespaces"},
 				},
 			},
 		},

docs/en/reference/prebuilt-tools.md

@@ -51,6 +51,7 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
     *   `list_indexes`: List available user indexes in a PostgreSQL database.
     *   `list_sequences`: List sequences in a PostgreSQL database.
     *   `list_publication_tables`: List publication tables in a PostgreSQL database.
+    *   `list_tablespaces`: Lists tablespaces in the database.
 
 ## AlloyDB Postgres Admin
 
@@ -229,6 +230,7 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
     *   `list_indexes`: List available user indexes in a PostgreSQL database.
     *   `list_sequences`: List sequences in a PostgreSQL database.
     *   `list_publication_tables`: List publication tables in a PostgreSQL database.
+    *   `list_tablespaces`: Lists tablespaces in the database.
 
 ## Cloud SQL for PostgreSQL Observability
 
@@ -535,6 +537,7 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
     *   `list_indexes`: List available user indexes in a PostgreSQL database.
     *   `list_sequences`: List sequences in a PostgreSQL database.
     *   `list_publication_tables`: List publication tables in a PostgreSQL database.
+    *   `list_tablespaces`: Lists tablespaces in the database.
 
 ## Google Cloud Serverless for Apache Spark
 

docs/en/resources/sources/alloydb-pg.md

@@ -80,6 +80,9 @@ cluster][alloydb-free-trial].
 - [`postgres-list-publication-tables`](../tools/postgres/postgres-list-publication-tables.md)
   List publication tables in a PostgreSQL database.
 
+- [`postgres-list-tablespaces`](../tools/postgres/postgres-list-tablespaces.md)
+  List tablespaces in an AlloyDB for PostgreSQL database.
+
 ### Pre-built Configurations
 
 - [AlloyDB using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_mcp/)

docs/en/resources/sources/cloud-sql-pg.md

@@ -76,6 +76,9 @@ to a database by following these instructions][csql-pg-quickstart].
 - [`postgres-list-publication-tables`](../tools/postgres/postgres-list-publication-tables.md)
   List publication tables in a PostgreSQL database.
 
+- [`postgres-list-tablespaces`](../tools/postgres/postgres-list-tablespaces.md)
+  List tablespaces in a PostgreSQL database.
+
 ### Pre-built Configurations
 
 - [Cloud SQL for Postgres using

docs/en/resources/sources/postgres.md

@@ -71,6 +71,9 @@ reputation for reliability, feature robustness, and performance.
 - [`postgres-list-publication-tables`](../tools/postgres/postgres-list-publication-tables.md)
   List publication tables in a PostgreSQL database.
 
+- [`postgres-list-tablespaces`](../tools/postgres/postgres-list-tablespaces.md)
+  List tablespaces in a PostgreSQL database.
+
 ### Pre-built Configurations
 
 - [PostgreSQL using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/postgres_mcp/)

docs/en/resources/tools/postgres/postgres-list-tablespaces.md

@@ -0,0 +1,56 @@
+---
+title: "postgres-list-tablespaces"
+type: docs
+weight: 1
+description: >
+ The "postgres-list-tablespaces" tool lists tablespaces in a Postgres database.
+aliases:
+- /resources/tools/postgres-list-tablespaces
+---
+
+## About
+
+The `postgres-list-tablespaces` tool lists available tablespaces in the database. It's compatible with any of the following sources:
+
+- [alloydb-postgres](../../sources/alloydb-pg.md)
+- [cloud-sql-postgres](../../sources/cloud-sql-pg.md)
+- [postgres](../../sources/postgres.md)
+
+`postgres-list-tablespaces` lists detailed information as JSON for tablespaces. The tool takes the following input parameters:
+
+- `tablespace_name` (optional): A text to filter results by tablespace name. Default: `""`
+- `limit` (optional): The maximum number of tablespaces to return. Default: `50`
+
+## Example
+
+```yaml
+tools:
+  list_tablespaces:
+    kind: postgres-list-tablespaces
+    source: postgres-source
+    description: |
+      Lists all tablespaces in the database. Returns the tablespace name,
+      owner name, size in bytes(if the current user has CREATE privileges on
+      the tablespace, otherwise NULL), internal object ID, the access control
+      list regarding permissions, and any specific tablespace options.
+```
+The response is a json array with the following elements:
+
+```json
+{
+ "tablespace_name": "name of the tablespace",
+ "owner_username": "owner of the tablespace",
+ "size_in_bytes": "size in bytes if the current user has CREATE privileges on the tablespace, otherwise NULL",
+ "oid": "Object ID of the tablespace",
+ "spcacl": "Access privileges",
+ "spcoptions": "Tablespace-level options (e.g., seq_page_cost, random_page_cost)"
+}
+```
+
+## Reference
+
+| **field**   | **type** | **required**  | **description**                                      |
+|-------------|:--------:|:-------------:|------------------------------------------------------|
+| kind        |  string  |     true      | Must be "postgres-list-tablespaces".                      |
+| 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. |

internal/prebuiltconfigs/tools/alloydb-postgres.yaml

@@ -175,7 +175,7 @@ tools:
     list_schemas:
         kind: postgres-list-schemas
         source: alloydb-pg-source
-    
+
     list_indexes:
         kind: postgres-list-indexes
         source: alloydb-pg-source
@@ -204,6 +204,10 @@ tools:
         kind: postgres-list-publication-tables
         source: alloydb-pg-source
 
+    list_tablespaces:
+        kind: postgres-list-tablespaces
+        source: alloydb-pg-source
+
 toolsets:
     alloydb_postgres_database_tools:
         - execute_sql
@@ -229,3 +233,4 @@ toolsets:
         - list_query_stats
         - get_column_cardinality
         - list_publication_tables
+        - list_tablespaces

internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml

@@ -177,7 +177,7 @@ tools:
     list_schemas:
         kind: postgres-list-schemas
         source: cloudsql-pg-source
-
+    
     database_overview:
         kind: postgres-database-overview
         source: cloudsql-pg-source
@@ -206,6 +206,10 @@ tools:
         kind: postgres-list-publication-tables
         source: cloudsql-pg-source
 
+    list_tablespaces:
+        kind: postgres-list-tablespaces
+        source: cloudsql-pg-source
+
 toolsets:
     cloud_sql_postgres_database_tools:
         - execute_sql
@@ -231,3 +235,4 @@ toolsets:
         - list_query_stats
         - get_column_cardinality
         - list_publication_tables
+        - list_tablespaces

internal/prebuiltconfigs/tools/postgres.yaml

@@ -176,7 +176,7 @@ tools:
     list_schemas:
         kind: postgres-list-schemas
         source: postgresql-source
-
+    
     database_overview:
         kind: postgres-database-overview
         source: postgresql-source
@@ -205,6 +205,10 @@ tools:
         kind: postgres-list-publication-tables
         source: postgresql-source
 
+    list_tablespaces:
+        kind: postgres-list-tablespaces
+        source: postgresql-source
+
 toolsets:
     postgres_database_tools:
         - execute_sql
@@ -230,3 +234,4 @@ toolsets:
         - list_query_stats
         - get_column_cardinality
         - list_publication_tables
+        - list_tablespaces