feat(tools/mysql): add list-table-stats-tool to list table statistics in MySQL and Cloud SQL MySQL source. (#2938)

## Description

Add the list_table_stats tool to MySQL to list table statistics.
The tool display table level statistics for troubleshooting performance
issues, finding hottest tables and monitoring table growth.


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

---------

Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com>

Author: sumeetdhingra-google

cmd/internal/config_test.go

@@ -1763,7 +1763,7 @@ func TestPrebuiltTools(t *testing.T) {
 				},
 				"monitor": tools.ToolsetConfig{
 					Name:      "monitor",
-					ToolNames: []string{"get_query_plan", "list_active_queries", "get_query_metrics", "get_system_metrics", "list_table_fragmentation", "list_tables_missing_unique_indexes"},
+					ToolNames: []string{"get_query_plan", "list_active_queries", "get_query_metrics", "get_system_metrics", "list_table_fragmentation", "list_table_stats", "list_tables_missing_unique_indexes"},
 				},
 				"lifecycle": tools.ToolsetConfig{
 					Name:      "lifecycle",
@@ -1847,7 +1847,7 @@ func TestPrebuiltTools(t *testing.T) {
 				},
 				"monitor": tools.ToolsetConfig{
 					Name:      "monitor",
-					ToolNames: []string{"get_query_plan", "list_active_queries", "list_table_fragmentation", "list_tables_missing_unique_indexes"},
+					ToolNames: []string{"get_query_plan", "list_active_queries", "list_table_fragmentation", "list_table_stats", "list_tables_missing_unique_indexes"},
 				},
 			},
 		},

cmd/internal/imports.go

@@ -182,6 +182,7 @@ import (
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/mysql/mysqllisttablefragmentation"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/mysql/mysqllisttables"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/mysql/mysqllisttablesmissinguniqueindexes"
+	_ "github.com/googleapis/mcp-toolbox/internal/tools/mysql/mysqllisttablestats"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/mysql/mysqlsql"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/neo4j/neo4jcypher"
 	_ "github.com/googleapis/mcp-toolbox/internal/tools/neo4j/neo4jexecutecypher"

docs/CLOUDSQLMYSQL_README.md

@@ -61,6 +61,7 @@ The Cloud SQL for MySQL MCP server provides the following tools:
 | `list_tables`                        | Lists detailed schema information for user-created tables.              |
 | `list_tables_missing_unique_indexes` | Find tables that do not have primary or unique key constraint.          |
 | `list_table_fragmentation`           | List table fragmentation in MySQL.                                      |
+| `list_table_stats`                   | List table statistics in MySQL.                                         |
 
 ## Custom MCP Server Configuration
 

docs/en/integrations/cloud-sql-mysql/prebuilt-configs/cloud-sql-for-mysql.md

@@ -30,3 +30,4 @@ description: "Details of the Cloud SQL for MySQL prebuilt configuration."
     *   `list_tables_missing_unique_indexes`: Looks for tables that do not have
         primary or unique key contraint.
     *   `list_table_fragmentation`: Displays table fragmentation in MySQL.
+    *   `list_table_stats`: Displays table statistics in MySQL.

docs/en/integrations/mysql/prebuilt-configs/mysql.md

@@ -25,3 +25,4 @@ description: "Details of the MySQL prebuilt configuration."
     *   `list_tables_missing_unique_indexes`: Looks for tables that do not have
         primary or unique key contraint.
     *   `list_table_fragmentation`: Displays table fragmentation in MySQL.
+    *   `list_table_stats`: Displays table statistics in MySQL.

docs/en/integrations/mysql/tools/mysql-list-table-stats.md

@@ -0,0 +1,80 @@
+---
+title: "mysql-list-table-stats"
+type: docs
+weight: 1
+description: >
+  A "mysql-list-table-stats" tool report table statistics including table size, total latency, rows read, rows written, read and write latency for entire instance, a specified database, or a specified table.
+---
+
+## About
+
+A `mysql-list-table-stats` tool generates table-level performance and resource consumption statistics to facilitate bottleneck identification and workload analysis.
+
+`mysql-list-table-stats` outputs detailed table-level resource consumption including estimated row counts, table size, a complete breakdown of CRUD activity (rows fetched, inserted, updated, and deleted), and IO statistics such as total, read, write and miscellaneous latency. The output is a JSON formatted array of the top 10 MySQL tables ranked by total latency. 
+
+Below are some use cases for `mysql-list-table-stats`
+- **Finding hottest tables**: Identify tables with highest total latency, read or writes based on the `sort_by` column. 
+- **Finding tables with most reads**: Identify tables with highest reads by sorting on `rows_fetched`. 
+- **Monitoring growth**: Track `row_count` and `size_MB` of table over time to estimate growth."
+
+## Compatible Sources
+
+{{< compatible-sources others="integrations/cloud-sql-mysql">}}
+
+## Requirements
+
+- `performance_schema` should be turned ON for this tool to work. 
+
+## Parameters
+
+This tool takes 4 optional input parameters:
+
+- `table_schema` (optional): The database where table stats check is to be
+  executed. Check all tables visible to the current database if not specified.
+- `table_name` (optional): Name of the table to be checked. Check all tables
+  visible to the current user if not specified.
+- `sort_by` (optional): The column to sort by. Valid values are `row_count`, `rows_fetched`, `rows_inserted`, `rows_updated`, `rows_deleted`, `total_latency_secs` (defaults to `total_latency_secs`)
+- `limit` (optional): Max rows to return, default 10.
+
+## Example
+
+```yaml
+kind: tools
+name: list_table_stats
+type: mysql-list-table-stats
+source: my-mysql-instance
+description: Display table statistics including table size, total latency, rows read, rows written, read and write latency for entire instance, a specified database, or a specified table. Specifying a database name or table name filters the output to that specific db or table. Results are limited to 10 by default.
+```
+
+## Output Format
+ 
+The response is a json array with the following fields:
+```json
+[
+  {
+  "table_schema": "The schema/database this table belongs to",
+  "table_name": "Name of this table",
+  "size_MB": "Size of the table data in MB",
+  "row_count": "Number of rows in the table",
+  "total_latency_secs": "total latency in secs",
+  "rows_fetched": "total number of rows fetched",
+  "rows_inserted": "total number of rows inserted",
+  "rows_updated": "total number of rows updated",
+  "rows_deleted": "total number of rows deleted",
+  "io_reads": "total number of io read requests",
+  "io_read_latency": "io read latency in seconds",
+  "io_write_latency": "io write latency in seconds",
+  "io_misc_latency": "io misc latency in seconds",
+  }
+]
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                    |
+|-------------|:--------:|:------------:|----------------------------------------------------|
+| type        |  string  |     true     | Must be "mysql-list-table-stats".                  |
+| source      |  string  |     true     | Name of the source the SQL should execute on.      |
+| description |  string  |     true     | Description of the tool that is passed to the LLM. |
+
+

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

@@ -44,6 +44,10 @@ tools:
     kind: mysql-list-tables
     source: cloud-sql-mysql-source
     description: "Lists detailed schema information (object type, columns, constraints, indexes, triggers, comment) as JSON for user-created tables (ordinary or partitioned). Filters by a comma-separated list of names. If names are omitted, lists all tables in user schemas."
+  list_table_stats:
+    kind: mysql-list-table-stats
+    source: cloud-sql-mysql-source
+    description: "Display table statistics including table size, total latency, rows read, rows written, read and write latency for entire instance, a specified database, or a specified table. Specifying a database name or table name filters the output to that specific db or table. Results are limited to 10 by default."
   list_tables_missing_unique_indexes:
     kind: mysql-list-tables-missing-unique-indexes
     source: cloud-sql-mysql-source
@@ -148,6 +152,7 @@ toolsets:
     - get_query_metrics
     - get_system_metrics
     - list_table_fragmentation
+    - list_table_stats
     - list_tables_missing_unique_indexes
   lifecycle:
     - create_backup

internal/prebuiltconfigs/tools/mysql.yaml

@@ -43,6 +43,10 @@ tools:
     kind: mysql-list-tables
     source: mysql-source
     description: "Lists detailed schema information (object type, columns, constraints, indexes, triggers, comment) as JSON for user-created tables (ordinary or partitioned). Filters by a comma-separated list of names. If names are omitted, lists all tables in user schemas."
+  list_table_stats:
+    kind: mysql-list-table-stats
+    source: mysql-source
+    description: "Display table statistics including table size, total latency, rows read, rows written, read and write latency for entire instance, a specified database, or a specified table. Specifying a database name or table name filters the output to that specific db or table. Results are limited to 10 by default."
   list_tables_missing_unique_indexes:
     kind: mysql-list-tables-missing-unique-indexes
     source: mysql-source
@@ -61,4 +65,5 @@ toolsets:
     - get_query_plan
     - list_active_queries
     - list_table_fragmentation
+    - list_table_stats
     - list_tables_missing_unique_indexes

internal/sources/cloudsqlmysql/cloud_sql_mysql.go

@@ -102,6 +102,10 @@ func (s *Source) MySQLPool() *sql.DB {
 	return s.Pool
 }
 
+func (s *Source) MySQLDatabase() string {
+	return s.Database
+}
+
 func (s *Source) RunSQL(ctx context.Context, statement string, params []any) (any, error) {
 	results, err := s.MySQLPool().QueryContext(ctx, statement, params...)
 	if err != nil {

internal/sources/mysql/mysql.go

@@ -101,6 +101,10 @@ func (s *Source) MySQLPool() *sql.DB {
 	return s.Pool
 }
 
+func (s *Source) MySQLDatabase() string {
+	return s.Database
+}
+
 func (s *Source) RunSQL(ctx context.Context, statement string, params []any) (any, error) {
 	results, err := s.MySQLPool().QueryContext(ctx, statement, params...)
 	if err != nil {