feat(tools/postgres): Add new postgres-list-roles tool (#2038)

## Description
Adds a postgresql custom list_roles tool, that lists all the
user-created roles in the instance. It provides details about each
role's attributes and memberships.


> Should include a concise description of the changes (bug or feature),
it's
> impact, along with a summary of the solution
![Uploading Screenshot 2025-11-26 at 1.16.42 AM.png…]()

<img width="1065" height="145" alt="Screenshot 2025-11-26 at 12 59
56 AM"
src="https://github.com/user-attachments/assets/d90131b1-d369-4108-b4db-ee5dc9aafe38"
/>


## 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)
- [ ] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<1738>

Co-authored-by: Wenxin Du <117315983+duwenxin99@users.noreply.github.com>

docs/en/reference/prebuilt-tools.md

@@ -55,6 +55,7 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
     *   `list_pg_settings`: List configuration parameters for the PostgreSQL server.
     *   `list_database_stats`: Lists the key performance and activity statistics for
         each database in the AlloyDB instance.
+    *   `list_roles`: Lists all the user-created roles in PostgreSQL database.  
 
 ## AlloyDB Postgres Admin
 
@@ -237,6 +238,7 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
     *   `list_pg_settings`: List configuration parameters for the PostgreSQL server.
     *   `list_database_stats`: Lists the key performance and activity statistics for
         each database in the postgreSQL instance.
+    *   `list_roles`: Lists all the user-created roles in PostgreSQL database.  
 
 ## Cloud SQL for PostgreSQL Observability
 
@@ -547,6 +549,7 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
     *   `list_pg_settings`: List configuration parameters for the PostgreSQL server.
     *   `list_database_stats`: Lists the key performance and activity statistics for
         each database in the PostgreSQL server.
+    *   `list_roles`: Lists all the user-created roles in PostgreSQL database.  
 
 ## Google Cloud Serverless for Apache Spark
 

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

@@ -90,6 +90,9 @@ cluster][alloydb-free-trial].
   Lists the key performance and activity statistics for each database in the AlloyDB
   instance.
 
+- [`postgres-list-roles`](../tools/postgres/postgres-list-roles.md)
+  Lists all the user-created roles in 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

@@ -86,6 +86,9 @@ to a database by following these instructions][csql-pg-quickstart].
   Lists the key performance and activity statistics for each database in the postgreSQL
   instance.
 
+- [`postgres-list-roles`](../tools/postgres/postgres-list-roles.md)
+  Lists all the user-created roles in PostgreSQL database..
+
 ### Pre-built Configurations
 
 - [Cloud SQL for Postgres using

docs/en/resources/sources/postgres.md

@@ -81,6 +81,9 @@ reputation for reliability, feature robustness, and performance.
   Lists the key performance and activity statistics for each database in the postgreSQL
   server.
 
+- [`postgres-list-roles`](../tools/postgres/postgres-list-roles.md)
+  Lists all the user-created roles in 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-roles.md

@@ -0,0 +1,70 @@
+---
+title: "postgres-list-roles"
+type: docs
+weight: 1
+description: >
+ The "postgres-list-roles" tool lists user-created roles in a Postgres database.
+aliases:
+- /resources/tools/postgres-list-roles
+---
+
+## About
+
+The `postgres-list-roles` tool lists all the user-created roles in the instance, excluding system roles (like `cloudsql%` or `pg_%`). It provides details about each role's attributes and memberships. 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-roles` lists detailed information as JSON for each role. The tool
+takes the following input parameters:
+
+- `role_name` (optional): A text to filter results by role name. Default: `""`
+- `limit` (optional): The maximum number of roles to return. Default: `50`
+
+## Example
+
+```yaml
+tools:
+  list_indexes:
+    kind: postgres-list-roles
+    source: postgres-source
+    description: |
+      Lists all the user-created roles in the instance . It returns the role name,
+      Object ID, the maximum number of concurrent connections the role can make,
+      along with boolean indicators for: superuser status, privilege inheritance
+      from member roles, ability to create roles, ability to create databases,
+      ability to log in, replication privilege, and the ability to bypass
+      row-level security, the password expiration timestamp, a list of direct
+      members belonging to this role, and a list of other roles/groups that this
+      role is a member of.
+```
+
+The response is a json array with the following elements:
+
+```json
+{
+ "role_name": "Name of the role",
+ "oid": "Object ID of the role",
+ "connection_limit": "Maximum concurrent connections allowed (-1 for no limit)",
+ "is_superuser": "Boolean, true if the role is a superuser",
+ "inherits_privileges": "Boolean, true if the role inherits privileges of roles it is a member of",
+ "can_create_roles": "Boolean, true if the role can create other roles",
+ "can_create_db": "Boolean, true if the role can create databases",
+ "can_login": "Boolean, true if the role can log in",
+ "is_replication_role": "Boolean, true if this is a replication role",
+ "bypass_rls": "Boolean, true if the role bypasses row-level security policies",
+ "valid_until": "Timestamp until the password is valid (null if forever)",
+ "direct_members": ["Array of role names that are direct members of this role"],
+ "member_of": ["Array of role names that this role is a member of"]
+}
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                      |
+|-------------|:--------:|:------------:|------------------------------------------------------|
+| kind        |  string  |     true     | Must be "postgres-list-roles".                     |
+| 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. |