mcp-dbutils 0.20.1__tar.gz → 0.21.0__tar.gz

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.21.0](https://github.com/donghao1393/mcp-dbutils/compare/v0.20.1...v0.21.0) (2025-05-01)
+
+
+### Features
+
+* 优化数据库工具描述以提高LLM理解能力 ([#81](https://github.com/donghao1393/mcp-dbutils/issues/81)) ([232cd3e](https://github.com/donghao1393/mcp-dbutils/commit/232cd3ed247ed95248932001c99ed529819cddf8))
+
 ## [0.20.1](https://github.com/donghao1393/mcp-dbutils/compare/v0.20.0...v0.20.1) (2025-04-30)
 
 

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-dbutils
-Version: 0.20.1
+Version: 0.21.0
 Summary: MCP Database Utilities Service
 Author: Dong Hao
 License-Expression: MIT
@@ -125,14 +125,17 @@ MCP Database Utilities 是一个多功能的 MCP 服务，它使您的 AI 能够
 
 MCP 数据库工具提供了多种工具，使 AI 能够与您的数据库交互：
 
-- **dbutils-list-connections**：列出配置中的所有可用数据库连接
-- **dbutils-list-tables**：列出数据库中的所有表
-- **dbutils-run-query**：执行 SQL 查询（仅 SELECT）
-- **dbutils-get-stats**：获取表统计信息
-- **dbutils-list-constraints**：列出表约束
-- **dbutils-explain-query**：获取查询执行计划
-- **dbutils-get-performance**：获取数据库性能指标
-- **dbutils-analyze-query**：分析查询以进行优化
+- **dbutils-list-connections**：列出配置中的所有可用数据库连接，包括数据库类型、主机、端口和数据库名称等详细信息，同时隐藏密码等敏感信息。
+- **dbutils-list-tables**：列出指定数据库连接中的所有表，包括表名、URI和可用的表描述，按数据库类型分组以便于识别。
+- **dbutils-run-query**：执行只读SQL查询（仅SELECT），支持包括JOIN、GROUP BY和聚合函数在内的复杂查询，返回包含列名和数据行的结构化结果。
+- **dbutils-describe-table**：提供表结构的详细信息，包括列名、数据类型、是否可为空、默认值和注释，以易于阅读的格式呈现。
+- **dbutils-get-ddl**：获取创建指定表的完整DDL（数据定义语言）语句，包括所有列定义、约束和索引。
+- **dbutils-list-indexes**：列出指定表上的所有索引，包括索引名称、类型（唯一/非唯一）、索引方法和包含的列，按索引名称分组。
+- **dbutils-get-stats**：获取表的统计信息，包括估计行数、平均行长度、数据大小和索引大小。
+- **dbutils-list-constraints**：列出表上的所有约束，包括主键、外键、唯一约束和检查约束，对于外键约束还显示引用的表和列。
+- **dbutils-explain-query**：获取SQL查询的执行计划，显示数据库引擎将如何处理查询，包括访问方法、连接类型和估计成本。
+- **dbutils-get-performance**：获取数据库连接的性能指标，包括查询计数、平均执行时间、内存使用情况和错误统计。
+- **dbutils-analyze-query**：分析SQL查询的性能特性，提供执行计划、实际执行时间和具体的优化建议。
 
 有关这些工具的详细说明和使用示例，请参阅[使用指南](docs/zh/usage.md)。
 

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/README.md

@@ -100,14 +100,17 @@ MCP Database Utilities 是一个多功能的 MCP 服务，它使您的 AI 能够
 
 MCP 数据库工具提供了多种工具，使 AI 能够与您的数据库交互：
 
-- **dbutils-list-connections**：列出配置中的所有可用数据库连接
-- **dbutils-list-tables**：列出数据库中的所有表
-- **dbutils-run-query**：执行 SQL 查询（仅 SELECT）
-- **dbutils-get-stats**：获取表统计信息
-- **dbutils-list-constraints**：列出表约束
-- **dbutils-explain-query**：获取查询执行计划
-- **dbutils-get-performance**：获取数据库性能指标
-- **dbutils-analyze-query**：分析查询以进行优化
+- **dbutils-list-connections**：列出配置中的所有可用数据库连接，包括数据库类型、主机、端口和数据库名称等详细信息，同时隐藏密码等敏感信息。
+- **dbutils-list-tables**：列出指定数据库连接中的所有表，包括表名、URI和可用的表描述，按数据库类型分组以便于识别。
+- **dbutils-run-query**：执行只读SQL查询（仅SELECT），支持包括JOIN、GROUP BY和聚合函数在内的复杂查询，返回包含列名和数据行的结构化结果。
+- **dbutils-describe-table**：提供表结构的详细信息，包括列名、数据类型、是否可为空、默认值和注释，以易于阅读的格式呈现。
+- **dbutils-get-ddl**：获取创建指定表的完整DDL（数据定义语言）语句，包括所有列定义、约束和索引。
+- **dbutils-list-indexes**：列出指定表上的所有索引，包括索引名称、类型（唯一/非唯一）、索引方法和包含的列，按索引名称分组。
+- **dbutils-get-stats**：获取表的统计信息，包括估计行数、平均行长度、数据大小和索引大小。
+- **dbutils-list-constraints**：列出表上的所有约束，包括主键、外键、唯一约束和检查约束，对于外键约束还显示引用的表和列。
+- **dbutils-explain-query**：获取SQL查询的执行计划，显示数据库引擎将如何处理查询，包括访问方法、连接类型和估计成本。
+- **dbutils-get-performance**：获取数据库连接的性能指标，包括查询计数、平均执行时间、内存使用情况和错误统计。
+- **dbutils-analyze-query**：分析SQL查询的性能特性，提供执行计划、实际执行时间和具体的优化建议。
 
 有关这些工具的详细说明和使用示例，请参阅[使用指南](docs/zh/usage.md)。
 

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/README_EN.md

@@ -73,14 +73,19 @@ We offer multiple installation methods, including uvx, Docker, and Smithery. For
 
 MCP Database Utilities provides several tools that your AI can use:
 
-- **dbutils-list-connections**: Lists all available database connections in your configuration
-- **dbutils-list-tables**: Lists all tables in a database
-- **dbutils-run-query**: Executes a SQL query (SELECT only)
-- **dbutils-get-stats**: Gets statistics about a table
-- **dbutils-list-constraints**: Lists table constraints
-- **dbutils-explain-query**: Gets query execution plan
-- **dbutils-get-performance**: Gets database performance metrics
-- **dbutils-analyze-query**: Analyzes queries for optimization
+- **dbutils-list-connections**: Lists all available database connections with detailed information including database type, host, port, and database name, while hiding sensitive information like passwords.
+- **dbutils-list-tables**: Lists all tables in the specified database connection with table names, URIs, and available descriptions, grouped by database type for easy identification.
+- **dbutils-run-query**: Executes read-only SQL queries (SELECT only) with support for complex queries including JOINs, GROUP BY, and aggregate functions, returning structured results with column names and data rows.
+- **dbutils-describe-table**: Provides detailed information about a table's structure, including column names, data types, nullability, default values, and comments in an easy-to-read format.
+- **dbutils-get-ddl**: Retrieves the complete DDL (Data Definition Language) statement for creating the specified table, including all column definitions, constraints, and indexes.
+- **dbutils-list-indexes**: Lists all indexes on the specified table, including index names, types (unique/non-unique), index methods, and included columns, grouped by index name.
+- **dbutils-get-stats**: Retrieves statistical information about the table, including estimated row count, average row length, data size, and index size.
+- **dbutils-list-constraints**: Lists all constraints on the table, including primary keys, foreign keys, unique constraints, and check constraints, with referenced tables and columns for foreign keys.
+- **dbutils-explain-query**: Provides the execution plan for a SQL query, showing how the database engine will process the query, including access methods, join types, and estimated costs.
+- **dbutils-get-performance**: Retrieves performance metrics for the database connection, including query count, average execution time, memory usage, and error statistics.
+- **dbutils-analyze-query**: Analyzes the performance characteristics of a SQL query, providing execution plan, actual execution time, and specific optimization recommendations.
+
+For detailed descriptions and usage examples of these tools, see the [Usage Guide](docs/en/usage.md).
 
 
 

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/docs/en/usage.md

@@ -1,8 +1,5 @@
 # Usage Guide
 
-*English | [中文](../zh/usage.md) | [Français](../fr/usage.md) | [Español](../es/usage.md) | [العربية](../ar/usage.md) | [Русский](../ru/usage.md)*
-
-
 *English | [中文](../zh/usage.md) | [Français](../fr/usage.md) | [Español](../es/usage.md) | [العربية](../ar/usage.md) | [Русский](../ru/usage.md)*
 
 This document provides detailed instructions for using the MCP Database Utilities, helping you fully leverage its capabilities for data analysis with AI.
@@ -22,7 +19,7 @@ MCP Database Utilities provides several tools that your AI can use:
 
 ### dbutils-list-connections
 
-Lists all available database connections defined in your configuration.
+Lists all available database connections defined in the configuration with detailed information including database type, host, port, and database name, while hiding sensitive information like passwords. The optional check_status parameter allows verifying if each connection is available, though this may increase response time. Use this tool when you need to understand available database resources or diagnose connection issues.
 
 **Example Interaction**:
 
@@ -48,7 +45,7 @@ Lists all available database connections defined in your configuration.
 
 ### dbutils-list-tables
 
-Lists all tables in the specified database.
+Lists all tables in the specified database connection with table names, URIs, and available descriptions. Results are grouped by database type and clearly labeled for easy identification. Use this tool when you need to understand database structure or locate specific tables. Only works within the allowed connection scope.
 
 **Example Interaction**:
 
@@ -63,7 +60,7 @@ Lists all tables in the specified database.
 
 ### dbutils-run-query
 
-Executes SQL queries on the specified database (SELECT operations only).
+Executes read-only SQL queries on the specified database connection. For security, only SELECT statements are supported. Returns structured results with column names and data rows. Supports complex queries including JOINs, GROUP BY, ORDER BY, and aggregate functions. Use this tool when you need to analyze data, validate hypotheses, or extract specific information. Query execution is protected by resource limits and timeouts to prevent system resource overuse.
 
 **Example Interaction**:
 
@@ -71,9 +68,49 @@ Executes SQL queries on the specified database (SELECT operations only).
 
 **AI**: "Let me check that for you. According to the data, there have been 42 new customer registrations in the last 30 days."
 
+### dbutils-describe-table
+
+Provides detailed information about a table's structure, including column names, data types, nullability, default values, and comments. Results are formatted as an easy-to-read hierarchy that clearly displays all column attributes. Use this tool when you need to understand table structure in depth, analyze data models, or prepare queries. Supports all major database types with consistent output format.
+
+**Example Interaction**:
+
+**You**: "Describe the structure of the customers table."
+
+**AI**: "The customers table has the following structure:
+- id: integer, primary key, not null, auto-increment
+- name: varchar(100), not null
+- email: varchar(100), unique, not null
+- registration_date: date, not null, default: current_date
+- status: enum('active','inactive','suspended'), default: 'active'
+- last_login: timestamp, nullable"
+
+### dbutils-get-ddl
+
+Retrieves the complete DDL (Data Definition Language) statement for creating the specified table. Returns the original CREATE TABLE statement including all column definitions, constraints, indexes, and table options. This tool is valuable when you need to understand the complete table structure, replicate table structure, or perform database migrations. Note that DDL statement format varies by database type.
+
+**Example Interaction**:
+
+**You**: "Get the DDL for the products table."
+
+**AI**: "Here's the DDL statement for the products table:
+```sql
+CREATE TABLE products (
+  id INT NOT NULL AUTO_INCREMENT,
+  name VARCHAR(200) NOT NULL,
+  description TEXT,
+  price DECIMAL(10,2) NOT NULL,
+  category_id INT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  INDEX idx_category (category_id),
+  CONSTRAINT fk_category FOREIGN KEY (category_id) REFERENCES categories(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```"
+
 ### dbutils-get-stats
 
-Gets statistics about a table, such as row count, size, and column statistics.
+Retrieves statistical information about the table, including estimated row count, average row length, data size, index size, and column information. These statistics are valuable for understanding table size, growth trends, and storage characteristics. Use this tool when you need to perform capacity planning, performance optimization, or database maintenance. Note that the precision and availability of statistics may vary by database type.
 
 **Example Interaction**:
 
@@ -87,9 +124,38 @@ Gets statistics about a table, such as row count, size, and column statistics.
   * category: 8 distinct categories
   * price: average $45.99, min $5.99, max $299.99"
 
+### dbutils-list-indexes
+
+Lists all indexes on the specified table, including index names, types (unique/non-unique), index methods (e.g., B-tree), and included columns. Results are grouped by index name, clearly showing the structure of multi-column indexes. Use this tool when you need to optimize query performance, understand table access patterns, or diagnose performance issues.
+
+**Example Interaction**:
+
+**You**: "List all indexes on the orders table."
+
+**AI**: "The orders table has the following indexes:
+1. **PRIMARY** (Primary Key Index)
+   - Column: order_id
+   - Type: Unique
+   - Method: B-tree
+
+2. **idx_customer** (Regular Index)
+   - Column: customer_id
+   - Type: Non-unique
+   - Method: B-tree
+
+3. **idx_order_date** (Regular Index)
+   - Column: order_date
+   - Type: Non-unique
+   - Method: B-tree
+
+4. **idx_status_created** (Composite Index)
+   - Columns: status, created_at
+   - Type: Non-unique
+   - Method: B-tree"
+
 ### dbutils-list-constraints
 
-Lists constraints for a table, such as primary keys, foreign keys, etc.
+Lists all constraints on the table, including primary keys, foreign keys, unique constraints, and check constraints. Results are grouped by constraint type, clearly showing constraint names and involved columns. For foreign key constraints, referenced tables and columns are also displayed. Use this tool when you need to understand data integrity rules, table relationships, or data validation logic.
 
 **Example Interaction**:
 
@@ -103,7 +169,7 @@ Lists constraints for a table, such as primary keys, foreign keys, etc.
 
 ### dbutils-explain-query
 
-Gets the query execution plan and cost estimates.
+Provides the execution plan for a SQL query, showing how the database engine will process the query. Returns detailed execution plan including access methods, join types, sort operations, and estimated costs. Also provides actual execution statistics where available. Use this tool when you need to optimize query performance, understand complex query behavior, or diagnose slow queries. Note that execution plan format varies by database type.
 
 **Example Interaction**:
 
@@ -117,7 +183,7 @@ Gets the query execution plan and cost estimates.
 
 ### dbutils-get-performance
 
-Gets database performance metrics.
+Retrieves performance metrics for the database connection, including query count, average execution time, memory usage, and error statistics. These metrics reflect the resource usage of the current session and help monitor and optimize database operations. Use this tool when you need to evaluate query efficiency, identify performance bottlenecks, or monitor resource usage.
 
 **Example Interaction**:
 
@@ -131,7 +197,7 @@ Gets database performance metrics.
 
 ### dbutils-analyze-query
 
-Analyzes SQL query performance and provides optimization suggestions.
+Analyzes the performance characteristics of a SQL query, providing execution plan, actual execution time, and optimization suggestions. The tool executes the query (SELECT statements only) and measures performance, then provides specific optimization recommendations based on the results, such as adding indexes, restructuring join conditions, or adjusting query structure. Use this tool when you need to improve query performance, understand performance bottlenecks, or learn query optimization techniques.
 
 **Example Interaction**:
 

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/docs/zh/usage.md

@@ -19,7 +19,7 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 ### dbutils-list-connections
 
-列出配置中定义的所有可用数据库连接。
+列出配置中的所有可用数据库连接，包括数据库类型、主机、端口和数据库名称等详细信息，同时隐藏密码等敏感信息。可选参数check_status允许验证每个连接是否可用，但这可能会增加响应时间。当您需要了解可用的数据库资源或诊断连接问题时使用此工具。
 
 **示例交互**：
 
@@ -45,7 +45,7 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 ### dbutils-list-tables
 
-列出指定数据库中的所有表。
+列出指定数据库连接中的所有表，包括表名、URI和可用的表描述。结果按数据库类型分组并清晰标记，便于快速识别。当您需要了解数据库结构或查找特定表时使用此工具。只在允许的连接范围内工作。
 
 **示例交互**：
 
@@ -60,7 +60,7 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 ### dbutils-run-query
 
-在指定数据库上执行 SQL 查询（仅限 SELECT 操作）。
+在指定数据库连接上执行只读SQL查询。为确保安全，仅支持SELECT语句。查询结果以结构化格式返回，包含列名和数据行。支持复杂查询，包括JOIN、GROUP BY、ORDER BY和聚合函数。当您需要分析数据、验证假设或提取特定信息时使用此工具。查询执行受到资源限制和超时保护，以防止过度消耗系统资源。
 
 **示例交互**：
 
@@ -68,9 +68,49 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 **AI**："让我为您查询。根据数据，过去 30 天内有 42 位新客户注册。"
 
+### dbutils-describe-table
+
+获取表结构的详细信息，包括列名、数据类型、是否可为空、默认值和注释。结果格式化为易读的层次结构，清晰显示每列的所有属性。当您需要深入了解表结构、分析数据模型或准备查询时使用此工具。支持所有主要数据库类型，并保持一致的输出格式。
+
+**示例交互**：
+
+**您**："描述 customers 表的结构。"
+
+**AI**："customers 表的结构如下：
+- id: 整数, 主键, 非空, 自增
+- name: 字符串(100), 非空
+- email: 字符串(100), 唯一, 非空
+- registration_date: 日期, 非空, 默认值: 当前日期
+- status: 枚举('active','inactive','suspended'), 默认值: 'active'
+- last_login: 时间戳, 可为空"
+
+### dbutils-get-ddl
+
+获取创建指定表的完整DDL（数据定义语言）语句。返回原始的CREATE TABLE语句，包括所有列定义、约束、索引和表选项。当您需要理解表的完整结构、复制表结构或进行数据库迁移时，此工具非常有用。DDL语句格式会根据数据库类型而有所不同。
+
+**示例交互**：
+
+**您**："获取 products 表的 DDL。"
+
+**AI**："products 表的 DDL 语句如下：
+```sql
+CREATE TABLE products (
+  id INT NOT NULL AUTO_INCREMENT,
+  name VARCHAR(200) NOT NULL,
+  description TEXT,
+  price DECIMAL(10,2) NOT NULL,
+  category_id INT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  INDEX idx_category (category_id),
+  CONSTRAINT fk_category FOREIGN KEY (category_id) REFERENCES categories(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```"
+
 ### dbutils-get-stats
 
-获取表的统计信息，如行数、大小和列统计数据。
+获取表的统计信息，包括估计行数、平均行长度、数据大小、索引大小和列信息。这些统计数据对于了解表的大小、增长趋势和存储特性非常有价值。当您需要进行容量规划、性能优化或数据库维护时使用此工具。统计信息的精确度和可用性可能因数据库类型而异。
 
 **示例交互**：
 
@@ -84,9 +124,38 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
   * category：共 8 个不同类别
   * price：平均价格 $45.99，最低 $5.99，最高 $299.99"
 
+### dbutils-list-indexes
+
+列出指定表上的所有索引，包括索引名称、类型（唯一/非唯一）、索引方法（如B树）和包含的列。结果按索引名称分组，清晰显示多列索引的结构。当您需要优化查询性能、理解表的访问模式或诊断性能问题时使用此工具。
+
+**示例交互**：
+
+**您**："列出 orders 表的所有索引。"
+
+**AI**："orders 表有以下索引：
+1. **PRIMARY** (主键索引)
+   - 列: order_id
+   - 类型: 唯一索引
+   - 方法: B树
+
+2. **idx_customer** (普通索引)
+   - 列: customer_id
+   - 类型: 非唯一索引
+   - 方法: B树
+
+3. **idx_order_date** (普通索引)
+   - 列: order_date
+   - 类型: 非唯一索引
+   - 方法: B树
+
+4. **idx_status_created** (复合索引)
+   - 列: status, created_at
+   - 类型: 非唯一索引
+   - 方法: B树"
+
 ### dbutils-list-constraints
 
-列出表的约束条件，如主键、外键等。
+列出表上的所有约束，包括主键、外键、唯一约束和检查约束。结果按约束类型分组，清晰显示约束名称和涉及的列。对于外键约束，还会显示引用的表和列。当您需要理解数据完整性规则、表间关系或数据验证逻辑时使用此工具。
 
 **示例交互**：
 
@@ -100,7 +169,7 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 ### dbutils-explain-query
 
-获取查询执行计划和成本估算。
+获取SQL查询的执行计划，显示数据库引擎将如何处理查询。返回详细的执行计划，包括访问方法、连接类型、排序操作和估计成本。同时提供实际执行统计（如可用）。当您需要优化查询性能、理解复杂查询的行为或诊断慢查询时使用此工具。执行计划格式会根据数据库类型而有所不同。
 
 **示例交互**：
 
@@ -114,7 +183,7 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 ### dbutils-get-performance
 
-获取数据库性能指标。
+获取数据库连接的性能指标，包括查询计数、平均执行时间、内存使用情况和错误统计。这些指标反映了当前会话的资源使用情况，有助于监控和优化数据库操作。当您需要评估查询效率、识别性能瓶颈或监控资源使用时使用此工具。
 
 **示例交互**：
 
@@ -128,7 +197,7 @@ MCP 数据库工具提供了几个您的 AI 可以使用的工具：
 
 ### dbutils-analyze-query
 
-分析 SQL 查询的性能并提供优化建议。
+分析SQL查询的性能特性，提供执行计划、实际执行时间和优化建议。工具会执行查询（仅限SELECT语句）并测量性能，然后基于结果提供具体的优化建议，如添加索引、重构连接条件或调整查询结构。当您需要提高查询性能、理解性能瓶颈或学习查询优化技术时使用此工具。
 
 **示例交互**：
 

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-dbutils"
-version = "0.20.1"
+version = "0.21.0"
 description = "MCP Database Utilities Service"
 readme = "README.md"
 license = "MIT"

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/src/mcp_dbutils/base.py

@@ -444,7 +444,7 @@ class ConnectionServer:
         return [
             types.Tool(
                 name="dbutils-list-connections",
-                description="List all available database connections defined in the configuration",
+                description="Lists all available database connections defined in the configuration with detailed information including database type, host, port, and database name, while hiding sensitive information like passwords. The optional check_status parameter allows verifying if each connection is available, though this may increase response time. Use this tool when you need to understand available database resources or diagnose connection issues.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -459,7 +459,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-run-query",
-                description="Execute read-only SQL query on database connection",
+                description="Executes read-only SQL queries on the specified database connection. For security, only SELECT statements are supported. Returns structured results with column names and data rows. Supports complex queries including JOINs, GROUP BY, ORDER BY, and aggregate functions. Use this tool when you need to analyze data, validate hypotheses, or extract specific information. Query execution is protected by resource limits and timeouts to prevent system resource overuse.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -477,7 +477,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-list-tables",
-                description="List all available tables in the specified database connection",
+                description="Lists all tables in the specified database connection. Results include table names, URIs, and available table descriptions. Results are grouped by database type and clearly labeled for easy identification. Use this tool when you need to understand database structure or locate specific tables. Only works within the allowed connection scope.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -491,7 +491,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-describe-table",
-                description="Get detailed information about a table's structure",
+                description="Provides detailed information about a table's structure, including column names, data types, nullability, default values, and comments. Results are formatted as an easy-to-read hierarchy that clearly displays all column attributes. Use this tool when you need to understand table structure in depth, analyze data models, or prepare queries. Supports all major database types with consistent output format.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -509,7 +509,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-get-ddl",
-                description="Get DDL statement for creating the table",
+                description="Retrieves the complete DDL (Data Definition Language) statement for creating the specified table. Returns the original CREATE TABLE statement including all column definitions, constraints, indexes, and table options. This tool is valuable when you need to understand the complete table structure, replicate table structure, or perform database migrations. Note that DDL statement format varies by database type.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -527,7 +527,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-list-indexes",
-                description="List all indexes on the specified table",
+                description="Lists all indexes on the specified table, including index names, types (unique/non-unique), index methods (e.g., B-tree), and included columns. Results are grouped by index name, clearly showing the structure of multi-column indexes. Use this tool when you need to optimize query performance, understand table access patterns, or diagnose performance issues.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -545,7 +545,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-get-stats",
-                description="Get table statistics like row count and size",
+                description="Retrieves statistical information about the table, including estimated row count, average row length, data size, index size, and column information. These statistics are valuable for understanding table size, growth trends, and storage characteristics. Use this tool when you need to perform capacity planning, performance optimization, or database maintenance. Note that the precision and availability of statistics may vary by database type.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -563,7 +563,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-list-constraints",
-                description="List all constraints (primary key, foreign keys, etc) on the table",
+                description="Lists all constraints on the table, including primary keys, foreign keys, unique constraints, and check constraints. Results are grouped by constraint type, clearly showing constraint names and involved columns. For foreign key constraints, referenced tables and columns are also displayed. Use this tool when you need to understand data integrity rules, table relationships, or data validation logic.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -581,7 +581,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-explain-query",
-                description="Get execution plan for a SQL query",
+                description="Provides the execution plan for a SQL query, showing how the database engine will process the query. Returns detailed execution plan including access methods, join types, sort operations, and estimated costs. Also provides actual execution statistics where available. Use this tool when you need to optimize query performance, understand complex query behavior, or diagnose slow queries. Note that execution plan format varies by database type.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -599,7 +599,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-get-performance",
-                description="Get database performance statistics",
+                description="Retrieves performance metrics for the database connection, including query count, average execution time, memory usage, and error statistics. These metrics reflect the resource usage of the current session and help monitor and optimize database operations. Use this tool when you need to evaluate query efficiency, identify performance bottlenecks, or monitor resource usage.",
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -613,7 +613,7 @@ class ConnectionServer:
             ),
             types.Tool(
                 name="dbutils-analyze-query",
-                description="Analyze a SQL query for performance",
+                description="Analyzes the performance characteristics of a SQL query, providing execution plan, actual execution time, and optimization suggestions. The tool executes the query (SELECT statements only) and measures performance, then provides specific optimization recommendations based on the results, such as adding indexes, restructuring join conditions, or adjusting query structure. Use this tool when you need to improve query performance, understand performance bottlenecks, or learn query optimization techniques.",
                 inputSchema={
                     "type": "object",
                     "properties": {

{mcp_dbutils-0.20.1 → mcp_dbutils-0.21.0}/tests/unit/test_base_server.py

@@ -159,12 +159,12 @@ class TestConnectionServerTools:
 
         # Verify the first tool is dbutils-list-connections
         assert tools[0].name == "dbutils-list-connections"
-        assert "List all available database connections" in tools[0].description
+        assert "Lists all available database connections" in tools[0].description
 
         # Verify dbutils-run-query is also in the tools
         run_query_tools = [tool for tool in tools if tool.name == "dbutils-run-query"]
         assert len(run_query_tools) == 1
-        assert "Execute read-only SQL query" in run_query_tools[0].description
+        assert "Executes read-only SQL queries" in run_query_tools[0].description
 
         # Check that all tools have the required properties
         for tool in tools: