mssql-performance-mcp/TOOLS_REFERENCE.md

MCP server for SQL Server performance tuning and optimization. Provides tools for analyzing slow queries, execution plans, index fragmentation, missing indexes, and more.

# MSSQL Performance MCP - Tools Reference

Quick reference guide for all available tools.

## 🎯 Tool Categories

### 📊 Query Performance
- `get_slow_queries` - Find slow-running queries
- `get_query_store_top_queries` - Historical query analysis
- `get_blocking_queries` - Identify blocking/locks

### 🔍 Index Analysis
- `get_missing_indexes` - Find beneficial indexes
- `get_unused_indexes` - Find wasteful indexes
- `get_index_fragmentation` - Check fragmentation
- `get_index_usage_stats` - Detailed usage metrics
- `generate_index_maintenance_script` - Create maintenance plan

### 📈 System Performance
- `get_wait_statistics` - Analyze wait types
- `get_performance_health_check` - Comprehensive health check
- `get_table_sizes` - Storage analysis

### 📋 Database Health
- `get_database_statistics` - Statistics health check

---

## Tool Details

### 1️⃣ get_slow_queries

**Purpose**: Find CPU and I/O intensive queries

**Key Parameters**:
- `top_n`: Number of queries (default: 20)
- `order_by`: cpu | duration | reads | executions

**Use When**:
- Users report slow performance
- CPU is high
- Daily monitoring

**Returns**:
- Query text
- Execution count
- CPU time (avg, max, total)
- Duration statistics
- Read/write statistics

**Example**:
```
Show me the top 10 queries by CPU time on database 'MyDB'
```

---

### 2️⃣ get_missing_indexes

**Purpose**: Identify indexes that would improve performance

**Key Parameters**:
- `min_impact`: Minimum improvement score (default: 10000)
- `top_n`: Number of recommendations (default: 20)

**Use When**:
- Queries are slow
- Looking for quick wins
- Performance tuning

**Returns**:
- CREATE INDEX statements
- Impact score
- Equality/inequality columns
- Included columns
- Usage statistics

**Priority**:
- > 100,000: Critical
- > 50,000: High
- > 10,000: Medium

**Example**:
```
Find missing indexes with impact > 50000 on 'MyDB'
```

---

### 3️⃣ get_unused_indexes

**Purpose**: Find indexes consuming space without benefit

**Key Parameters**:
- `min_size_mb`: Minimum size to consider (default: 10)

**Use When**:
- Reclaiming storage
- Reducing write overhead
- Monthly maintenance

**Returns**:
- DROP INDEX statements
- Index size
- Usage statistics (0 reads)
- Update counts

**Caution**:
- Review business logic before dropping
- Check if index is for reporting
- Verify with application team

**Example**:
```
Show unused indexes larger than 100 MB
```

---

### 4️⃣ get_index_fragmentation

**Purpose**: Check index fragmentation levels

**Key Parameters**:
- `database`: Required
- `min_fragmentation`: % threshold (default: 10)
- `min_pages`: Minimum page count (default: 1000)

**Use When**:
- Monthly maintenance
- Slow query performance
- Before major operations

**Returns**:
- Fragmentation percentages
- Page counts
- Recommendations (REORGANIZE vs REBUILD)
- Maintenance scripts

**Guidelines**:
- < 10%: No action
- 10-30%: REORGANIZE
- > 30%: REBUILD

**Example**:
```
Check fragmentation for 'MyDB' where > 20%
```

---

### 5️⃣ get_wait_statistics

**Purpose**: Analyze what SQL Server is waiting on

**Key Parameters**:
- `top_n`: Number of wait types (default: 20)

**Use When**:
- Diagnosing performance issues
- Understanding bottlenecks
- Capacity planning

**Returns**:
- Wait types
- Wait times
- Task counts
- Recommendations

**Common Wait Types**:
| Wait Type | Meaning | Action |
|-----------|---------|--------|
| PAGEIOLATCH_SH/EX | Disk I/O | Add memory or faster storage |
| WRITELOG | Log writes | Faster log disk |
| CXPACKET | Parallelism | Adjust MAXDOP |
| LCK_M_* | Locking | Check blocking |
| SOS_SCHEDULER_YIELD | CPU pressure | Add CPU or optimize queries |

**Example**:
```
Show me wait statistics for my server
```

---

### 6️⃣ get_database_statistics

**Purpose**: Check statistics health and age

**Key Parameters**:
- `database`: Required
- `days_old`: Show stats older than N days (default: 7)

**Use When**:
- Query plans are suboptimal
- After bulk data changes
- Monthly maintenance

**Returns**:
- Statistics age
- Modification counts
- UPDATE STATISTICS scripts
- Priority levels

**Impact**:
- Outdated stats → Poor query plans
- High modifications → Need update
- Sample rate matters

**Example**:
```
Show statistics older than 30 days
```

---

### 7️⃣ get_blocking_queries

**Purpose**: Identify current blocking and lock chains

**Key Parameters**:
- None (runs immediately)

**Use When**:
- Users report "hanging" queries
- Emergency performance issues
- Real-time monitoring

**Returns**:
- Blocked session info
- Blocking session info
- Query texts for both
- Wait duration

**Actions**:
- Kill blocker if needed
- Optimize blocking query
- Check transaction scope

**Example**:
```
Show me any blocking happening right now
```

---

### 8️⃣ get_query_store_top_queries

**Purpose**: Historical query performance analysis

**Key Parameters**:
- `database`: Required
- `hours_back`: History depth (default: 24)
- `top_n`: Number of queries (default: 20)
- `order_by`: cpu | duration | logical_reads | executions

**Use When**:
- Analyzing trends
- Comparing time periods
- Finding regressions
- Historical diagnosis

**Requires**:
- Query Store enabled

**Returns**:
- Query text
- Aggregated statistics
- Execution trends
- Time ranges

**Example**:
```
Show top CPU queries from Query Store for last 48 hours
```

---

### 9️⃣ get_index_usage_stats

**Purpose**: Detailed index utilization analysis

**Key Parameters**:
- `schema`: Filter by schema (optional)
- `table`: Filter by table (optional)

**Use When**:
- Analyzing specific tables
- Understanding index effectiveness
- Before creating new indexes

**Returns**:
- Seeks, scans, lookups
- Update counts
- Read/write ratios
- Last access times
- Index sizes

**Interpretation**:
- High seeks: Good
- High scans: Consider indexes
- High updates, low reads: Unused?
- 0 reads: Unused index

**Example**:
```
Show index usage for table 'Items' in schema 'Item'
```

---

### 🔟 get_table_sizes

**Purpose**: Storage consumption analysis

**Key Parameters**:
- `database`: Required
- `top_n`: Number of tables (default: 50)

**Use When**:
- Capacity planning
- Understanding growth
- Identifying large tables

**Returns**:
- Table sizes (data + indexes)
- Row counts
- Used vs unused space
- Index counts

**Planning**:
- Track growth trends
- Plan for scale
- Archive old data

**Example**:
```
Show me the 20 largest tables
```

---

### 1️⃣1️⃣ get_performance_health_check

**Purpose**: Comprehensive health assessment

**Key Parameters**:
- None (comprehensive scan)

**Use When**:
- Daily monitoring
- Initial assessment
- Executive reports

**Returns**:
- CPU consumers
- Wait statistics
- Missing indexes summary
- Fragmentation summary
- Database size
- Server uptime

**Frequency**:
- Daily: Production
- Weekly: Development
- Before/after: Changes

**Example**:
```
Run a full health check on 'MyDB'
```

---

### 1️⃣2️⃣ generate_index_maintenance_script

**Purpose**: Create index maintenance plan

**Key Parameters**:
- `database`: Required
- `reorganize_threshold`: % for REORGANIZE (default: 10)
- `rebuild_threshold`: % for REBUILD (default: 30)
- `online`: Use ONLINE option (default: true)

**Use When**:
- Planning maintenance windows
- Automating maintenance
- After fragmentation check

**Returns**:
- Complete T-SQL script
- Comments with fragmentation %
- Progress tracking commands

**Considerations**:
- ONLINE requires Enterprise Edition
- SORT_IN_TEMPDB needs tempdb space
- Schedule during low-usage

**Example**:
```
Generate maintenance script with ONLINE rebuilds for 'MyDB'
```

---

## 🎯 Recommended Workflows

### Daily Monitoring
```
1. get_performance_health_check
2. get_wait_statistics (if issues found)
3. get_slow_queries (if CPU high)
4. get_blocking_queries (if users complain)
```

### Weekly Tuning
```
1. get_missing_indexes (high impact)
2. get_unused_indexes (review)
3. get_index_fragmentation
4. generate_index_maintenance_script
```

### Monthly Maintenance
```
1. get_performance_health_check (baseline)
2. get_database_statistics (update old stats)
3. get_index_fragmentation (full scan)
4. get_table_sizes (capacity planning)
5. generate_index_maintenance_script (execute)
```

### Emergency Response
```
1. get_blocking_queries (immediate)
2. get_wait_statistics (understand bottleneck)
3. get_slow_queries (top 5 by CPU)
4. get_performance_health_check (context)
```

---

## 📊 Output Formats

All tools return JSON with:
```json
{
  "tool": "tool_name",
  "count": number_of_results,
  "data_property": [array_of_results]
}
```

Claude will format this nicely in tables, lists, or summaries.

---

## 🔐 Security Notes

**Required Permissions**:
```sql
GRANT VIEW SERVER STATE TO [monitoring_user];
GRANT VIEW DATABASE STATE TO [monitoring_user];
GRANT VIEW DEFINITION TO [monitoring_user];
```

**Best Practices**:
- Use dedicated monitoring account
- Grant minimum permissions
- Enable SQL Server auditing
- Rotate passwords regularly
- Use integrated security when possible

---

## 🚀 Performance Tips

- **Connection Pooling**: Enabled automatically (max 10 connections)
- **Parallel Queries**: Ask Claude to "check multiple databases"
- **Filtering**: Use schema/table filters to narrow results
- **Time Ranges**: Use Query Store for historical analysis

---

## 📈 Interpreting Results

### High Impact = Urgent
- Improvement measure > 100,000
- Fragmentation > 50%
- Wait time > 30% of total

### Medium Impact = Plan
- Improvement measure 10,000-100,000
- Fragmentation 30-50%
- Wait time 10-30%

### Low Impact = Monitor
- Improvement measure < 10,000
- Fragmentation < 30%
- Wait time < 10%

---

**Quick Tip**: Start with `get_performance_health_check` and drill down based on findings!