What can you do with this server?

This server provides a secure, read-only (or write-enabled) MCP interface to Microsoft SQL Server, enabling querying, schema exploration, performance monitoring, and lock/deadlock analysis. * Query execution – Run read-only SQL (SELECT/WITH, temp-table batches, whitelisted EXEC) via mssql_query; supports pagination and JSON/Markdown output. * Database discovery – List databases, tables (with row counts/sizes), sample data, and test connectivity. * Schema introspection – Get table schemas, foreign-key relationships, views, stored procedures (with definitions/parameters), and search object definitions for text fragments. * Performance tuning – Analyze index usage, fragmentation (with rebuild/reorganize recommendations), top expensive queries (by CPU, duration, reads, etc.), overall performance health, and storage usage. * Lock & blocking analysis – View current locks, find blocking chains with lead blockers, and retrieve recent deadlock events from system_health. * Resource monitoring – Track CPU, memory, sessions, and top resource-consuming queries. * Security & compliance – Two-layer read-only enforcement, parameterized queries, audit logging, and blocking of dangerous server-level statements (even in write mode).

How do I use MS SQL Server MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MS SQL Server MCP Server show me the top 5 customers by order amount" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

MS SQL Server MCP Server

by PiyapatRag

Overview Schema Related Servers Score Discussions

JavaScript

Remote

MS SQL Server MCP Server

npm version npm downloads node license Sponsor

A secure, read-only Model Context Protocol (MCP) server for Microsoft SQL Server with built-in performance monitoring and lock detection.

📦 npm: @piyapat/mssql-mcp-server

Requirements

Node.js 22 or newer. Raised from 18 in v2.0.2: mssql 12 depends on tedious 20, which requires Node 22.
SQL Server 2019 (15.x), 2022 (16.x), or 2025 (17.x) — all editions including Express. Azure SQL Database works for the query/schema tools; see the per-edition notes from mssql_test_connection.

Related MCP server: mssql-explorer-mcp

Quick Start with npx

You can run this MCP server directly without installation using npx:

npx @piyapat/mssql-mcp-server

Installation

Option 1: Use with npx (Recommended for Testing)

# Run directly with environment variables
MSSQL_SERVER=localhost \
MSSQL_DATABASE=mydb \
MSSQL_USER=readonly \
MSSQL_PASSWORD=password \
npx @piyapat/mssql-mcp-server

Option 2: Global Installation

# Install globally
npm install -g @piyapat/mssql-mcp-server

# Run
mssql-mcp-server

Option 3: Local Installation

# Clone and install
git clone https://github.com/PiyapatRag/mssql-mcp-server.git
cd mssql-mcp-server
npm install
npm run build

# Run
npm start

Configuration

Step 1: Create a `.env` file (Recommended)

Credentials live in a .env file — not hard-coded in the MCP client's JSON config:

cp .env.example .env
# then edit .env with your credentials

The server looks for a .env file in this order (first found wins):

The path in MSSQL_ENV_FILE (explicit override)
.env in the current working directory
.env in the project root (next to package.json)

Variables already set in the MCP client's "env" block always take precedence over the .env file, and .env is git-ignored.

Step 2: Point Claude Desktop at the server

Edit your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

With a .env in the project root, no credentials are needed in the JSON at all:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["C:\\path\\to\\mssql-mcp-server\\build\\index.js"]
    }
  }
}

If the .env lives somewhere else, pass only its path:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["C:\\path\\to\\mssql-mcp-server\\build\\index.js"],
      "env": {
        "MSSQL_ENV_FILE": "C:\\secure\\location\\mssql.env"
      }
    }
  }
}

Setting variables directly in the "env" block still works (and overrides the .env file) — useful for npx setups or running several servers against different databases.

Environment Variables

Variable	Description	Default	Required
`MSSQL_SERVER`	SQL Server hostname or IP	`localhost`	Yes
`MSSQL_DATABASE`	Database name	-	Yes
`MSSQL_USER`	SQL Server username (or domain user when `MSSQL_DOMAIN` is set)	-	Yes
`MSSQL_PASSWORD`	Password	-	Yes
`MSSQL_DOMAIN`	Windows/NTLM domain. When set, Windows Authentication is used instead of SQL authentication	-	No
`MSSQL_PORT`	SQL Server port	`1433`	No
`MSSQL_ENCRYPT`	Encrypt the connection (true/false). Only a literal `false` disables it	`true`	No
`MSSQL_TRUST_CERT`	Skip certificate validation (true/false). Opt-in — leave off in production	`false`	No
`MSSQL_READ_ONLY`	`true` = read-only allow-list validation. `false` = write mode: INSERT/UPDATE/DELETE/DDL allowed, but server-level dangerous statements stay blocked	`true`	No
`MSSQL_ALLOWED_PROCEDURES`	Comma-separated whitelist of stored procedures `EXEC` may call in read-only mode, e.g. `dbo.GetReport,dbo.GetCustomerSummary`. Empty/unset disables `EXEC` entirely.	-	No
`MSSQL_ENV_FILE`	Explicit path to a `.env` file	-	No
`MSSQL_REQUEST_TIMEOUT`	Query timeout in ms	`30000`	No
`MSSQL_POOL_MAX`	Max pooled connections	`10`	No
`MSSQL_AUDIT_LOG`	Log every tool call to stderr as one JSON line (tool, mode, truncated query, row counts, duration, outcome). Set `false` to disable	`true`	No
`MSSQL_VERBOSE_ERRORS`	Return the driver's full error text to the client. Off by default: errors are capped to their first line so a failing query can't be used to map the schema. Full detail always goes to stderr	`false`	No

Server Modes

Read-only mode (`MSSQL_READ_ONLY=true`, default)

mssql_query accepts only:

A single SELECT / WITH...SELECT
A multi-statement batch led by DECLARE, INSERT, or CREATE TABLE #... that writes only to session-local #temp tables / @table variables — e.g. INSERT INTO #t SELECT ... or CREATE TABLE #t (...); INSERT INTO #t ...; SELECT * FROM #t. CREATE INDEX ... ON #t, TRUNCATE/ALTER/DROP TABLE #t are also allowed inside such batches. Global ##temp tables are never allowed (they are visible to every session, so they count as persistent).
EXEC of a whitelisted procedure whose definition does not write to a persistent table

Everything else is rejected: writes/DDL on persistent objects, dynamic SQL, EXEC inside batches (prevents bypassing the procedure whitelist), DBCC, and stacked statements after a SELECT/WITH/EXEC.

Write mode (`MSSQL_READ_ONLY=false`)

INSERT / UPDATE / DELETE / DDL are permitted, but these are always blocked regardless of mode:

xp_cmdshell, xp_reg* (read and write), xp_dirtree, xp_fileexist, sp_OA*, sp_configure, RECONFIGURE, SHUTDOWN, KILL, DROP DATABASE, ALTER DATABASE, RESTORE, BULK INSERT, CREATE ASSEMBLY, CREATE/ALTER/DROP LOGIN/USER/CREDENTIAL/CERTIFICATE, ALTER SERVER, ALTER SERVER ROLE/ALTER ROLE, sp_addrolemember/sp_addsrvrolemember/ sp_droprolemember, sp_addlinkedserver, EXECUTE AS, sp_executesql, GRANT/DENY/REVOKE, OPENROWSET/OPENDATASOURCE/OPENQUERY, and the server-side file readers fn_get_audit_file, fn_xe_file_target_read_file, fn_trace_gettable, sp_readerrorlog/xp_readerrorlog.

⚠️ Use write mode only with a SQL login whose own permissions are equally limited — the database login remains the primary security boundary.

Key Features

Security First

✅ Two-layer read-only enforcement - A database read-only login (primary) plus an application-level allow-list (defense-in-depth). The app accepts SELECT / WITH...SELECT, DECLARE batches that write only to #temp tables / @table variables, and EXEC of whitelisted procedures whose definitions never write to a persistent table
✅ Quote-aware SQL scanning - Comments and literals are removed in a single left-to-right pass that tracks quote state, so a -- or ; hidden inside a string literal cannot smuggle a second statement past the analyzer
✅ Parameterized queries - Built-in SQL injection protection
✅ SSL/TLS by default - Encryption and certificate validation are opt-out, not opt-in
✅ Streamed result paging - Rows are streamed and the read is cancelled one row past the requested page, so a large SELECT can't exhaust the server's memory
✅ Audit trail - Every tool call is logged to stderr as one JSON line (MSSQL_AUDIT_LOG)
✅ Connection pooling - Optimized resource management

Performance Monitoring

📊 Real-time lock detection - Identify blocking and deadlock situations
📈 Resource usage tracking - CPU, memory, and query performance metrics
🔍 Top query analysis - Find resource-intensive queries
⚡ Session monitoring - Track active and blocked sessions

Database Exploration

🗂️ Schema introspection - Tables, columns, keys, and constraints
📝 Stored procedure analysis - View definitions and parameters
🔎 Intelligent querying - Natural language to SQL with Claude

Available Tools (19)

Core

Tool	Description
`mssql_query`	Execute SQL. Read-only validation by default; write mode via `MSSQL_READ_ONLY=false` (dangerous server-level statements always blocked). Pagination + JSON/Markdown output.
`mssql_test_connection`	Test connectivity; returns server/edition/version, database, login, and current mode.
`mssql_list_databases`	All databases with state, recovery model, compatibility level.
`mssql_list_tables`	Tables with row count and size (MB), optionally filtered by schema.
`mssql_sample_data`	Preview rows from a table (default 10, max 100) — no SQL needed, injection-safe.

Schema exploration

Tool	Description
`mssql_get_schema`	Columns, data types, PK/FK per table.
`mssql_get_relationships`	Foreign-key graph: from/to table+column, delete/update actions.
`mssql_get_views`	Views with full SQL definitions.
`mssql_get_stored_procedures`	Stored procedures with parameters and full definitions.
`mssql_search_definitions`	Search the source of all procs/views/functions/triggers for a text fragment — impact analysis for legacy systems.

Performance & storage

Tool	Description
`mssql_analyze_indexes`	Index usage stats (seeks/scans/updates) + optimizer-suggested missing indexes.
`mssql_index_fragmentation`	Fragmentation per index with REBUILD (≥ 30%) / REORGANIZE (5–30%) recommendations and ready-to-run `ALTER INDEX` statements (`ONLINE = ON` added automatically on editions that support it).
`mssql_top_queries`	Most expensive queries ranked by `cpu`, `duration`, `reads`, `writes`, `memory` (grant size), or `executions` — totals, averages, and SQL text.
`mssql_performance_health`	Health check: top wait stats (benign waits filtered), memory counters (PLE, grants pending, total vs target), workload counters, plus rule-based tuning recommendations.
`mssql_analyze_storage`	Largest tables by size + database file sizes.
`mssql_monitor_usage`	Sessions, CPU, buffer cache, top queries by CPU.

Locks, blocking & deadlocks

Supported on SQL Server 2019 (15.x), 2022 (16.x), and 2025 (17.x) — all editions including Express. Output includes the detected server version/edition and warns when running on an older version (best-effort). Requires VIEW SERVER STATE.

Version & edition compatibility:

	Express	Standard	Enterprise / Developer / Eval	Azure SQL MI	Azure SQL DB
Query / schema / storage tools	✅	✅	✅	✅	✅
`mssql_monitor_locks` / `mssql_find_blocking`	✅	✅	✅	✅	✅
`mssql_get_deadlocks` (`system_health` XE)	✅	✅	✅	✅	❌ (tool explains alternatives)
`mssql_list_databases` / `mssql_monitor_usage`	✅	✅	✅	✅	⚠️ limited scope

Rows/columns above apply to SQL Server 2019, 2022, and 2025. Older versions (2016/2017) mostly work but are reported as best-effort in the tool output. mssql_test_connection reports the detected edition class and its engine limits (e.g. Express: 10 GB/database, ~1.4 GB buffer pool, 4 cores).

Tool	Description
`mssql_monitor_locks`	Raw view of current locks and waits per session.
`mssql_find_blocking`	Blocking chains (victim ← blocker), lead-blocker identification incl. idle sessions holding open transactions, with SQL text of both sides.
`mssql_get_deadlocks`	Recent deadlock events from the built-in `system_health` Extended Events session: victims, involved queries, and full deadlock-graph XML. `source: "ring_buffer"` (fast, recent) or `"file"` (further back).

Claude Examples:

"Show me the top 10 customers by order count"
"Which tables are the largest, and which indexes are unused?"
"Which sessions are blocked right now, and who is the root blocker?"
"Were there any deadlocks last night, and which query caused them?"
"Find every stored procedure that references the CustomerOrders table"

Security Setup

Read-only is enforced in two layers. The database login is the primary guard — even a write statement that reached the server cannot execute. The application-level allow-list (classifyQuery in src/index.ts) is defense-in-depth: it accepts only read-only entry points and rejects everything else (writes, DDL, dynamic SQL, stacked queries). Because it allow-lists the leading keyword rather than blocking words, columns or aliases named Create, Update, CreatedDate, etc. are not blocked.

Create Read-Only SQL User (Recommended)

A ready-to-run script is provided at scripts/create-readonly-login.sql — edit the placeholders and run it as a sysadmin. It applies the least-privilege setup below:

-- 1. Create login
CREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!';

-- 2. Switch to your database
USE YourDatabase;

-- 3. Create user
CREATE USER mcp_readonly FOR LOGIN mcp_readonly;

-- 4. Grant read permissions
ALTER ROLE db_datareader ADD MEMBER mcp_readonly;

-- 4b. Explicitly DENY writes (defense-in-depth)
ALTER ROLE db_denydatawriter ADD MEMBER mcp_readonly;

-- 5. Grant monitoring permissions
GRANT VIEW SERVER STATE TO mcp_readonly;
GRANT VIEW DATABASE STATE TO mcp_readonly;
GRANT VIEW DEFINITION TO mcp_readonly;

-- 6. Verify permissions
SELECT
    dp.name AS DatabaseUser,
    dp.type_desc,
    r.name AS RoleName
FROM sys.database_principals dp
LEFT JOIN sys.database_role_members drm ON dp.principal_id = drm.member_principal_id
LEFT JOIN sys.database_principals r ON drm.role_principal_id = r.principal_id
WHERE dp.name = 'mcp_readonly';

Development

Build

npm run build

Watch Mode

npm run dev

Testing Locally

# Set environment variables
export MSSQL_SERVER=localhost
export MSSQL_DATABASE=testdb
export MSSQL_USER=sa
export MSSQL_PASSWORD=password

# Run
npm start

Troubleshooting

"command not found" Error with npx

If you get an error running with npx:

Ensure Node.js 22+ is installed:

node --version

Clear npm cache:

npm cache clean --force

Try with full package name:

npx --package=@piyapat/mssql-mcp-server mssql-mcp-server

Connection Errors

Error: Login failed for user

-- Check authentication mode (must be Mixed Mode)
USE master;
GO
EXEC xp_instance_regread
  N'HKEY_LOCAL_MACHINE',
  N'Software\Microsoft\MSSQLServer\MSSQLServer',
  N'LoginMode';
GO
-- Should return 2 for Mixed Mode

Error: Cannot connect to server

Verify SQL Server Browser service is running
Check firewall allows port 1433
Ensure TCP/IP protocol is enabled in SQL Server Configuration Manager

Permission Errors

-- Grant additional permissions if needed
USE YourDatabase;
GRANT EXECUTE TO mcp_readonly;  -- If you need to call stored procedures
GRANT SHOWPLAN TO mcp_readonly; -- For execution plans

Reporting a Vulnerability

Please don't open a public issue for a security bug. Use GitHub private vulnerability reporting, or the maintainer address on the npm package page. Scope, response targets, and safe-harbor terms are in SECURITY.md.

The guard battery in scripts/security-validation.mjs runs the real compiled analyzer against ~100 attack cases and runs in CI — npm run test:security reproduces it locally.

Security Acknowledgements

🙏 Thank you to Kietgboiz17 (kietgboiz17@gmail.com) for the security review, vulnerability report, and red-teaming that hardened this project — including the read-only guard bypass fixed in 2.0.2 and the additional guard hardening in 2.0.3. See CHANGELOG.md and SECURITY_REVIEW.md.

Best Practices

Always use read-only accounts in production
Keep encryption on (MSSQL_ENCRYPT=true, MSSQL_TRUST_CERT=false) — both are the default
Monitor regularly - Set up regular monitoring checks
Limit result sets - Use maxRows; rows are streamed, so a page is all that is read
Index optimization - Monitor slow queries and add indexes
Regular maintenance - Keep statistics updated
Audit access - Keep MSSQL_AUDIT_LOG on and retain the server's stderr log

Contributing

Contributions are welcome — see CONTRIBUTING.md for development setup, pull-request guidelines, and the release process. Version history is tracked in CHANGELOG.md.

License

MIT License - Feel free to use and modify for your needs.

Built With

@modelcontextprotocol/sdk - MCP SDK
mssql - SQL Server client for Node.js

Support

For issues:

Check the Troubleshooting section
Review SQL Server error logs
Verify Claude Desktop logs
Check database permissions

Built for Claude Desktop • Security First • Performance Focused

Available Tools

17 tools

mssql_analyze_indexesA

Read-only

Analyze index usage (seeks/scans/lookups/updates per index) and list potentially missing indexes suggested by the query optimizer. Optionally filter usage stats by table name.

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	No	Optional: only show index usage for this table.
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the tool is read-only. The description adds valuable behavioral context (e.g., it returns seeks/scans/lookups/updates and missing index suggestions) beyond the annotations, without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core purpose and listing the key outputs (seeks/scans/lookups/updates and missing indexes). Every word adds value, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has 2 parameters, no output schema. The description explains the output (index usage metrics and missing index suggestions) but does not detail the response format or how missing indexes are presented. Still, it covers the main functionality adequately for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning: it rephrases the tableName parameter as 'Optionally filter usage stats by table name' and response_format is self-explanatory. No substantive enrichment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes index usage and lists missing indexes, with optional table filtering. It is distinct from siblings like mssql_index_fragmentation (focuses on fragmentation) and mssql_get_schema, but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies it should be used for analyzing index performance and finding optimization opportunities, but provides no explicit 'when to use' or 'when not to use' guidance, nor does it mention alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_analyze_storageA

Read-only

Analyze storage: largest tables by size (row count, total/used MB) and database file sizes. Useful for capacity planning and finding space hogs.

ParametersJSON Schema

Name	Required	Description	Default
`topTables`	No	Number of largest tables to return (default: 20)
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description does not contradict them. It adds value by detailing what is analyzed (largest tables, file sizes) beyond the annotations. No additional behavioral traits are disclosed, but the description is consistent and provides useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that effectively communicates the tool's purpose and output. It is front-loaded with the key action and resource, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description explicitly lists the output elements (row count, total/used MB for tables, database file sizes). It covers the needed context for an analysis tool with simple parameters. Parameter coverage is complete, and the description is sufficient for understanding what the tool returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, meaning both parameters (topTables, response_format) have descriptions in the input schema. The description does not add significant meaning beyond what the schema provides; it only implies that topTables refers to largest tables by size. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it analyzes storage, specifically largest tables by size (row count, total/used MB) and database file sizes. This is a specific verb+resource combination that distinguishes it from siblings like mssql_analyze_indexes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'useful for capacity planning and finding space hogs', providing a clear context for use. However, it does not explicitly state when not to use it or suggest alternatives, which would improve guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_find_blockingA

Read-only

Find current blocking chains: which sessions are blocked, by whom, on what resource, and for how long. Identifies lead blockers (including idle sessions holding open transactions) with their SQL text. Supported: SQL Server 2019 (15.x), 2022 (16.x), 2025 (17.x) — all editions including Express. Requires VIEW SERVER STATE.

ParametersJSON Schema

Name	Required	Description	Default
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds that it requires VIEW SERVER STATE permission, providing important behavioral context. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences), front-loads the core purpose, and includes version support and permission requirement without extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers what the tool does and what it returns (lead blockers with SQL text). No output schema exists, so the description provides sufficient context for a focused diagnostic tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with a single parameter (response_format) and enum. The description does not add further meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Find current blocking chains', specifying what it identifies (sessions, blocked, by whom, resource, duration) and lead blockers with SQL text. This is specific and distinct from sibling tools like mssql_monitor_locks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions version support and required permission (VIEW SERVER STATE), providing some usage context. However, it does not explicitly state when to use this tool over alternatives like mssql_monitor_locks or mssql_get_deadlocks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_get_deadlocksA

Read-only

Retrieve recent deadlock events from the built-in system_health Extended Events session, including the full deadlock graph XML, victim sessions, and the queries involved. Source 'ring_buffer' (default, fast, recent events only) or 'file' (reads system_health .xel files, further back but slower). Supported: SQL Server 2019 (15.x), 2022 (16.x), 2025 (17.x) — all editions including Express. Requires VIEW SERVER STATE.

ParametersJSON Schema

Name	Required	Description	Default
`source`	No	'ring_buffer' = in-memory recent events (fast). 'file' = system_health event files (older history, slower).	ring_buffer
`maxEvents`	No	Maximum number of deadlock events to return (default: 5, max: 25)
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate read-only and non-destructive. The description expands with version support, permission requirement (VIEW SERVER STATE), and source behavior. Adds significant value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, front-loaded with main purpose, then efficiently covers sources, version support, and permissions. Every sentence is informative with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three optional parameters and no output schema, the description covers return content, version support, permission, and source behavior. Complete for a deadlock retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and parameter descriptions are already detailed. The description adds context about source trade-offs (fast vs far back) not fully captured in schema enum descriptions. Overall adds value but not critical.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (retrieve), the resource (deadlock events from system_health session), and specifies included content (deadlock graph XML, victim sessions, queries). It distinguishes from sibling tools, none of which are about deadlocks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on choosing between 'ring_buffer' and 'file' sources based on recency and speed. Also mentions supported versions and required permission. Lacks explicit when-not-to-use or alternatives, but no direct sibling alternatives exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_get_relationshipsA

Read-onlyIdempotent

Get foreign key relationships between tables: constraint name, from/to table and column, and delete/update actions. Optionally filter by table name (matches either side).

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	No	Optional: only show relationships involving this table.
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description only adds minor context (filtering behavior). No contradictions, but no additional behavioral traits like performance impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core purpose and then the optional filter. No superfluous words, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the return fields. It implies the output includes all relationships when no filter is applied. Lacks explicit statement about default behavior (all relationships) but is sufficient for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters are fully described in the schema (100% coverage). The description adds value by clarifying that tableName matches on either side of the relationship, which is not evident from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves foreign key relationships and lists the specific fields returned (constraint name, tables/columns, actions). It distinguishes from siblings like mssql_get_schema or mssql_list_tables by focusing on foreign key constraints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions optional filtering by table name, but does not provide guidance on when to use this tool versus alternatives like mssql_get_schema. No exclusions or prerequisites are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_get_schemaA

Read-onlyIdempotent

Get database schema information including tables, columns, data types, primary keys, and foreign keys. Optionally filter by table name.

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	No	Optional: specific table name to get schema for. If not provided, returns all tables.
`response_format`	No	Response format: 'json' for machine-readable, 'markdown' for human-readable (default: markdown)	markdown

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds what data is returned but does not disclose additional behavioral traits (e.g., performance impact, system table queries). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core purpose and then adds optional detail. Every word adds value, with no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description sufficiently covers the tool's functionality for a simple read-only schema retrieval tool. It mentions the key return components and optional filtering. However, it could be slightly more complete by noting that the output format can be specified (already in param schema) and that all tables are returned if no filter is given (already in param schema).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for both parameters (tableName and response_format). The description adds context about the returned data (tables, columns, types, keys) that is not in the schema, enhancing understanding beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves database schema information including tables, columns, data types, primary keys, and foreign keys, with optional table name filtering. This distinguishes it from sibling tools like mssql_get_relationships, mssql_get_views, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. While the purpose is clear, it lacks guidance like 'For relationships only, use mssql_get_relationships' or 'Use this for a full schema overview.' Usage is implied but not spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_get_stored_proceduresA

Read-onlyIdempotent

List stored procedures in the database with their definitions and parameters. Optionally filter by procedure name.

ParametersJSON Schema

Name	Required	Description	Default
`procedureName`	No	Optional: specific procedure name to get details for. If not provided, returns all procedures.
`response_format`	No	Response format: 'json' for machine-readable, 'markdown' for human-readable (default: markdown)	markdown

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this as read-only and idempotent. The description adds that it returns definitions and parameters, which provides extra context. No behavioral traits beyond annotations are disclosed, but no contradictions either.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first conveys the main purpose, the second adds a key option. Every sentence is necessary, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should ideally hint at the return structure. It mentions 'definitions and parameters' but lacks specifics. For a simple listing tool with safe annotations, this is somewhat adequate but could benefit from more detail about what the output contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are fully described. The description adds a brief explanation for the optional filter and clarifies the response_format enum values, but does not add significant meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists stored procedures with definitions and parameters, using a specific verb and resource. It distinguishes from siblings like mssql_get_views or mssql_get_schema by focusing on stored procedures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions optional filtering by procedure name, giving a hint about usage. However, it does not explicitly state when to use this tool versus alternatives (e.g., mssql_get_schema or mssql_query), nor does it provide any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_get_viewsA

Read-onlyIdempotent

List views in the database with their full SQL definitions. Optionally filter by view name to get a single view's definition.

ParametersJSON Schema

Name	Required	Description	Default
`viewName`	No	Optional: specific view name to get the definition for.
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns full SQL definitions but no further behavioral context like permissions or performance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, concise and front-loaded. Every sentence adds value with no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with complete annotations and schema, the description is adequate. It explains the return content (full SQL definitions). Minor: no mention of result format beyond response_format parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The tool description repeats the filtering functionality but adds no new meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists views with their full SQL definitions and optionally filters by view name. It distinguishes from sibling tools that focus on relationships, indexes, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit when-to-use or alternatives, but the purpose is specific enough to infer appropriate use cases. No guidance on when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_index_fragmentationA

Read-only

Analyze index fragmentation and recommend maintenance: REBUILD (fragmentation ≥ 30%), REORGANIZE (5–30%), or OK (< 5%). Generates ready-to-run ALTER INDEX statements (ONLINE=ON suggested automatically on editions that support it). Small indexes below minPageCount are excluded since fragmentation there is harmless.

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	No	Optional: analyze only this table.
`minPageCount`	No	Ignore indexes smaller than this many pages (default: 100 ≈ 800 KB).
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond annotations (readOnlyHint=true, destructiveHint=false) by explaining that it generates ready-to-run ALTER INDEX statements (not executing them), suggests ONLINE=ON on supported editions, and excludes small indexes. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, clearly structured. The first sentence covers core functionality and thresholds; the second provides details on output and edge cases. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully covers what the tool does, how to use it (input parameters), what it produces (ALTER INDEX statements), and important edge cases (small indexes). Given the simplicity (3 optional params, no output schema, read-only), it is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the purpose of minPageCount (harmless fragmentation below threshold) and the format options. This enriches the meaning beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it analyzes index fragmentation and recommends maintenance actions with specific thresholds (REBUILD ≥30%, REORGANIZE 5-30%, OK <5%). It also mentions generating ALTER INDEX statements and excluding small indexes. This distinguishes it from sibling tools like mssql_analyze_indexes or mssql_performance_health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool (to check fragmentation and get maintenance scripts) and includes thresholds. It implicitly excludes small indexes via minPageCount, but does not explicitly state when not to use it or compare to alternatives like mssql_analyze_indexes. However, the guidance is sufficient for most cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_list_databasesA

Read-onlyIdempotent

List all databases on the SQL Server instance with state, recovery model, compatibility level, and creation date.

ParametersJSON Schema

Name	Required	Description	Default
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly and idempotent. Description adds specifics about returned data (state, recovery model, compatibility level, creation date), beyond annotation details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundant words, efficiently conveys tool action and output contents.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation, description covers key output attributes. No output schema, but return values are implied. Slightly lacking in specifying that it returns a list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (response_format) with 100% schema description coverage. Tool description adds no additional parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List all databases' with specific attributes (state, recovery model, etc.), distinguishing it from sibling tools like mssql_list_tables or mssql_get_schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like mssql_get_schema or mssql_analyze_storage, and no exclusion criteria provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_list_tablesA

Read-onlyIdempotent

List tables in the current database with schema, row count, and size in MB. Optionally filter by schema name.

ParametersJSON Schema

Name	Required	Description	Default
`schemaName`	No	Optional: filter tables by schema (e.g. 'dbo'). Default: all schemas.
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns schema, row count, size in MB, providing useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single sentence, front-loaded with core purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool with clear annotations and full schema coverage, the description is sufficiently complete. It explains output fields and optional filter, no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Description only restates that schemaName filter is optional, adding no new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it lists tables with schema, row count, and size in MB, and allows optional filtering. This distinguishes it from sibling tools like mssql_get_views or mssql_get_schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description mentions optional schema filter but does not explicitly state when to use this tool versus alternatives. However, the purpose is clear enough for selection among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_monitor_locksA

Read-only

Monitor database locks, blocking sessions, and potential deadlocks. Shows lock types, resources, and wait times.

ParametersJSON Schema

Name	Required	Description	Default
`response_format`	No	Response format: 'json' for machine-readable, 'markdown' for human-readable (default: markdown)	markdown

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, so the tool is safe. The description adds context about outputs (lock types, resources, wait times) beyond the annotation, enhancing transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff. Information is front-loaded and every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity monitoring tool with no output schema, the description adequately covers what it monitors and shows. It could mention that it returns a snapshot, but overall complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter response_format, with enum and default descriptions. The tool description does not add further parameter meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool monitors database locks, blocking sessions, and deadlocks, with specific outputs. It distinguishes from siblings like mssql_find_blocking and mssql_get_deadlocks, but could be more explicit about its broader scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or when to prefer mssql_find_blocking or mssql_get_deadlocks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_monitor_usageB

Read-only

Get database resource usage statistics including CPU, memory, active sessions, and top resource-consuming queries.

ParametersJSON Schema

Name	Required	Description	Default
`topQueries`	No	Number of top CPU-consuming queries to return (default: 10)
`response_format`	No	Response format: 'json' for machine-readable, 'markdown' for human-readable (default: markdown)	markdown

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's role is light. It adds context about the types of statistics returned (CPU, memory, sessions, top queries), which is useful. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with verb, no filler. Every word is necessary and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (2 optional params, no output schema), the description covers the key data returned. It could optionally mention the time window or aggregation level, but overall it provides sufficient context for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description adds no additional semantic detail beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves database resource usage statistics including CPU, memory, sessions, and top queries. It is specific and actionable, but does not explicitly differentiate it from sibling tools like mssql_top_queries or mssql_performance_health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. For example, it doesn't explain that for detailed query-level analysis one should use mssql_top_queries. Agents receive no contextual hints for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_performance_healthA

Read-only

Overall performance health check: top wait statistics (with benign waits filtered out), memory counters (Page Life Expectancy, memory grants pending, total vs target memory), workload counters (batch requests, compilations), and rule-based optimization recommendations (e.g. high CXPACKET → review MAXDOP, PAGEIOLATCH → check I/O and indexes, LCK_M → run mssql_find_blocking).

ParametersJSON Schema

Name	Required	Description	Default
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, destructiveHint=false. Description expands on what is read (wait stats, memory, workload) and adds behavioral details like filtering benign waits and offering recommendations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence includes all necessary details without excessive verbosity. Well-structured and front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description adequately covers return categories (wait stats, memory, workload, recommendations). References sibling tools for further action. Complete for a summary health check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter (response_format) with 100% schema coverage; description does not add additional semantics beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly identifies it as an overall performance health check, listing specific areas (wait stats, memory, workload, recommendations). It distinguishes itself from siblings by mentioning rule-based recommendations that reference other tools like mssql_find_blocking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for an overall health check. Provides context by referencing sibling tools for specific scenarios (e.g., LCK_M → mssql_find_blocking). Does not explicitly state when not to use or provide exclusions, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_queryA

Read-onlyIdempotent

Execute a read-only SQL query against the MS SQL Server database. Accepts: a single SELECT / WITH...SELECT; a multi-statement batch led by DECLARE, INSERT, or CREATE TABLE # that writes ONLY to session-local #temp tables or @table variables (global ##temp is never allowed); or EXEC of a whitelisted stored procedure whose definition does not write to a persistent table. Writes to real tables, DDL on persistent objects, dynamic SQL, EXEC inside batches, and DBCC are blocked (server runs with MSSQL_READ_ONLY=true). Returns results as JSON or Markdown.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	The SQL to execute. Must be read-only: a SELECT/WITH query, a DECLARE batch using only #temp/@table targets, or EXEC of an allowed read-only stored procedure.
`offset`	No	Row offset for pagination (default: 0)
`maxRows`	No	Maximum number of rows to return per page (default: 100, max: 1000)
`response_format`	No	Response format: 'json' for machine-readable, 'markdown' for human-readable (default: json)	json

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral context beyond annotations (readOnlyHint, idempotentHint, destructiveHint), explaining allowed query patterns, blocked operations, server configuration (MSSQL_READ_ONLY=true), and response formats. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph that front-loads the main purpose. It is informative but could be more concise by splitting into bullet points or shortening examples. Nonetheless, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of SQL execution and no output schema, the description covers allowed queries, blocked operations, and response formats. It lacks details on error handling or pagination behavior, which would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3. The description reinforces the query parameter's allowed forms, adding detail beyond the schema's brief description. However, it does not add new semantics for offset, maxRows, or response_format beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a read-only SQL query against MS SQL Server, and distinguishes it from sibling tools by specifying exact allowed query types (SELECT, WITH...SELECT, temp-table batches, whitelisted procs) and blocked operations (writes, DDL, dynamic SQL).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly details when to use (read-only queries) and when not (writes, DDL, dynamic SQL, DBCC), providing clear constraints. It implicitly guides the agent to select this tool for read queries versus sibling tools for schema or analysis.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_sample_dataA

Read-onlyIdempotent

Retrieve sample rows from a table (default 10, max 100). Safe way to preview data without writing SQL. Accepts 'table' or 'schema.table'.

ParametersJSON Schema

Name	Required	Description	Default
`rows`	No	Number of rows to sample (default: 10, max: 100)
`tableName`	Yes	Table name, optionally schema-qualified (e.g. 'Orders' or 'dbo.Orders').
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it's a safe preview, reinforces non-destructive behavior, and provides row limits – all consistent with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no extraneous text. Key information (purpose, defaults, safety) is front-loaded for quick parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, and safety adequately. No output schema, but description doesn't need to detail return format beyond what schema provides. Minor gap: doesn't specify sampling method (e.g., TOP vs random).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters have schema descriptions (100% coverage). The description adds valuable context: default row count, max 100, and format for table names, complementing the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states retrieving sample rows from a table, specifying defaults and limits. It distinguishes from sibling tools like mssql_query (requires SQL) and mssql_get_schema (schema metadata).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions the tool as a safe, low-friction way to preview data without writing SQL. While it doesn't explicitly list alternatives, the context of sibling tools implies when not to use it (e.g., for complex queries).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mssql_top_queriesA

Read-only

Find the most expensive queries from the plan cache, ranked by a chosen metric: cpu, duration, reads (logical I/O), writes, memory (grant size), or executions. Returns per-query totals and averages with the SQL text — the starting point for performance tuning.

ParametersJSON Schema

Name	Required	Description	Default
`top`	No	Number of queries to return (default: 10, max: 50)
`metric`	No	Ranking metric (default: cpu)	cpu
`response_format`	No	Response format (default: markdown)	markdown

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description confirms read-only behavior (finding expensive queries) which aligns with annotations (readOnlyHint=true). No additional behavioral traits beyond annotations are disclosed, but no contradictions exist. The description adds minimal value beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, direct, and contains no redundant information. Every word serves a purpose, making it highly efficient for an AI agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has three well-described parameters, no output schema, and clear annotations, the description adequately explains purpose, metrics, and return content. It could provide more detail on output structure, but for a starting-point tool, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The description adds context by explaining the metrics (e.g., 'reads (logical I/O)') and that returns include per-query totals and averages, enhancing understanding beyond the raw schema. This justifies a score above the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds the most expensive queries from the plan cache, ranked by a chosen metric, and returns per-query totals and averages with SQL text. It distinguishes itself from siblings by focusing on plan cache and performance tuning, though it does not explicitly contrast with similar tools like mssql_performance_health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description describes the tool as 'the starting point for performance tuning', which implies when to use it. However, it lacks explicit guidance on when not to use it or clear differentiation from sibling tools. The context is implied but not directly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

Each tool targets a clearly distinct area: schema inspection, data preview, query execution, performance analysis, and monitoring. Even related tools like find_blocking, monitor_locks, and get_deadlocks have specific, non-overlapping purposes.

Naming Consistency3/5

Most tools follow a verb_noun pattern (get_, analyze_, monitor_, list_), but several deviate: mssql_index_fragmentation, mssql_top_queries, mssql_sample_data, mssql_query, and mssql_performance_health lack a clear verb prefix, breaking consistency.

Tool Count5/5

17 tools is well-scoped for a SQL Server database server covering schema, data, queries, performance, and monitoring. Each tool adds distinct value without being overwhelming.

Completeness4/5

The tool set covers schema browsing, data sampling, ad-hoc queries, performance tuning, and monitoring comprehensively. Minor gaps exist (e.g., missing query plan details, table statistics), but core workflows are well-supported.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

SRI — MCP Server Inspector A
biz.sri-test
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Developer Tools
21
The Quiet Protocol Growth Offense MCP A
com.thequietprotocol.www
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Databases Research & Data Finance
292
DB Query Guard MCP
com.clauxel.dbqueryguard
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
Databases Security
2
PGAuditor
com.mcpgatepro
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Databases Monitoring Observability
1

Related MCP Servers

mcp-sqlserver-readonly
Databases Developer Tools
gbfeliped
A
license
Not graded
quality
C
maintenance
Read-only SQL Server MCP server enabling safe database queries, table listing, and schema inspection with built-in security protections.
Updated 3 months ago (2026-06-18 13:49 UTC)
MIT
mssql-explorer-mcp
Databases Developer Tools
debabsah
A
license
Not graded
quality
C
maintenance
A read-only MCP server for exploring on-premises, multi-instance Microsoft SQL Server estates from AI clients, with read-only enforcement and Windows authentication support.
Updated 2 months ago (2026-06-24 02:22 UTC)
Apache 2.0
mssql-mcp
Databases Monitoring
blimyj
A
license
A
quality
C
maintenance
A read-only MCP server for Microsoft SQL Server that allows running SELECT queries and analyzing query performance with statistics.
Updated 2 months ago (2026-07-05 16:26 UTC)
4
907
MIT
sql-explorer-mcp
Databases Developer Tools
timsuv
F
license
A
quality
C
maintenance
A read-only MCP server for browsing and querying SQL Server databases, providing tools to list schemas, tables, describe columns, and execute safe SELECT queries with validated parameters.
Updated 2 months ago (2026-07-12 12:15 UTC)
15

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/PiyapatRag/mssql-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

MS SQL Server MCP Server

Requirements

Quick Start with npx

Installation

Option 1: Use with npx (Recommended for Testing)

Option 2: Global Installation

Option 3: Local Installation

Configuration

Step 1: Create a .env file (Recommended)

Step 2: Point Claude Desktop at the server

Environment Variables

Server Modes

Read-only mode (MSSQL_READ_ONLY=true, default)

Write mode (MSSQL_READ_ONLY=false)

Key Features

Security First

Performance Monitoring

Database Exploration

Available Tools (19)

Core

Schema exploration

Performance & storage

Locks, blocking & deadlocks

Security Setup

Create Read-Only SQL User (Recommended)

Development

Build

Watch Mode

Testing Locally

Troubleshooting

"command not found" Error with npx

Connection Errors

Permission Errors

Reporting a Vulnerability

Security Acknowledgements

Best Practices

Contributing

License

Built With

Support

Available Tools

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Step 1: Create a `.env` file (Recommended)

Read-only mode (`MSSQL_READ_ONLY=true`, default)

Write mode (`MSSQL_READ_ONLY=false`)