Provides offline diagnostics for PostgreSQL: analyzes SQL queries for anti-patterns, checks migration DDL for destructive or locking risks, suggests conservative index candidates, and reviews supplied EXPLAIN JSON plans without database credentials or executing statements.
Catch dangerous PostgreSQL migrations and slow queries before your AI agent ships them — offline, no DB credentials.
Offline PostgreSQL migration linting and query analysis for AI coding agents. Detects table-locking DDL, dangerous type changes, slow query patterns, and execution plan issues before they reach production. Nothing leaves your machine, no database connection required.
Click the button above to install in one step, or use this link:cursor://anysphere.cursor-deeplink/mcp/install?name=database-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kYXRhYmFzZS1kb2N0b3IiXX0=
Or add manually to ~/.cursor/mcp.json:
{
"mcpServers": {
"database-doctor": {
"command": "npx",
"args": ["-y", "mcp-database-doctor"]
}
}
}claude mcp add database-doctor -- npx -y mcp-database-doctorOr, if available in the Cursor plugin marketplace:
/plugin marketplace add petrovicistefan/mcp-marketplaceAdd to claude_desktop_config.json:
{
"mcpServers": {
"database-doctor": {
"command": "npx",
"args": ["-y", "mcp-database-doctor"]
}
}
}Or add to .vscode/mcp.json:
{
"mcpServers": {
"database-doctor": {
"command": "npx",
"args": ["-y", "mcp-database-doctor"]
}
}
}npx -y mcp-database-doctor⭐ Star this repository to support the project and stay updated! → Give a star
Related MCP server: nock-mcp
The hook: Your AI agent generates migrations that look harmless: CREATE INDEX, ALTER COLUMN ... TYPE, ADD COLUMN NOT NULL. But each one can lock your production table for minutes or hours, block every write, and take down your app.
Database Doctor catches these before they ship:
No database required: Static analysis only, works with uncommitted code
No credentials: Nothing connects to your database or executes SQL
No network: Everything runs locally on your machine
AI-native: Designed for AI coding agents (Claude Code, Cursor, GitHub Copilot)
✅ Before shipping migrations — Catch CREATE INDEX without CONCURRENTLY, dangerous type changes, volatile defaults
✅ Reviewing slow queries — Detect SELECT *, deep OFFSET, unbounded writes, unindexed predicates
✅ Analyzing EXPLAIN plans — Spot large sequential scans, row estimate errors, sort spills, high loop counts
✅ Suggesting indexes — Get conservative DDL candidates for WHERE clause columns
Your agent writes the migration. Database Doctor reviews it before committing.
User: "Add an email column to the users table"
Agent writes:
ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL;
Database Doctor flags:
⚠️ NOT_NULL_CHANGE (medium severity)
Adding NOT NULL requires a full table scan and may hold locks.
Recommendation: Backfill data first, then add NOT NULL separately.
Agent rewrites:
ALTER TABLE users ADD COLUMN email VARCHAR(255);
-- Backfill in application code or batched UPDATE
ALTER TABLE users ALTER COLUMN email SET NOT NULL;Catch dangerous migrations before they reach CI.
Ask your AI: "Check all migrations in db/migrations/ for safety"
Database Doctor reviews each file and reports:
Destructive DDL (DROP, TRUNCATE)
Blocking index creation
Table-rewriting column changes
Constraint validation without NOT VALID
Transactions that can't hold CONCURRENTLY operations
Find performance issues before they hit production.
Your agent generates:
SELECT * FROM orders
WHERE LOWER(email) = 'user@example.com'
OFFSET 10000
LIMIT 20;Database Doctor flags:
SELECT_STAR: Wildcard projection couples schema to caller
FUNCTION_PREDICATE: LOWER() may not use an index on email
DEEP_OFFSET: Offset 10000 discards many rows, use keyset pagination
Submit a slow query's execution plan for analysis.
# On your test database
EXPLAIN (FORMAT JSON) SELECT ... > plan.json
# In your AI client
"Review this execution plan from plan.json"Database Doctor detects:
Sequential scans on large tables
Row estimate errors (10x+ off)
Sort operations spilling to disk
High loop counts in nested joins
check_migration)Check | Severity | What It Catches |
| High | DROP TABLE/SCHEMA/DATABASE, TRUNCATE |
| High | ALTER COLUMN ... TYPE (table rewrite + strong locks) |
| Medium | CREATE INDEX without CONCURRENTLY (blocks writes) |
| High | CONCURRENTLY inside BEGIN/COMMIT (invalid) |
| Medium | UNIQUE index requires compatible existing data |
| Medium | SET NOT NULL or ADD COLUMN NOT NULL (table scan) |
| Medium | ADD FOREIGN KEY / CHECK without NOT VALID |
| High | DEFAULT with random(), clock_timestamp(), nextval() |
| High | CASCADE can affect dependent objects |
analyze_query)Check | Severity | What It Catches |
| Low | Wildcard projection increases coupling |
| High | UPDATE/DELETE without WHERE |
| Medium | Large OFFSET discards rows, use keyset pagination |
| Medium | Function in WHERE may not use index |
| Low | LIMIT without ORDER BY gives unstable results |
| Medium | Explicit CROSS JOIN multiplies row counts |
| Medium | NOT IN subquery with NULLs can produce unexpected results |
| Medium | ORDER BY random() can require sorting all rows |
explain_plan)Check | Severity | What It Catches |
| Medium | Sequential scan with 10,000+ estimated rows |
| Medium | Estimated vs actual rows differ by 10x+ |
| Medium | Sort spilled to disk (increase work_mem) |
| Medium | Plan node executes 1000+ loops |
As of October 2026. All comparisons stated cautiously based on public documentation.
Feature | Database Doctor | MigrationPilot | Locksmith | Ballast | DBHub |
Offline analysis | ✅ No DB connection | ✅ Optional | ✅ No DB connection | ❌ Requires DB | ❌ Connects to DB |
Migration linting | ✅ 9 migration rules | ✅ 112 rules | ✅ 9 rules + rewrites | ✅ Superset of Squawk | ❌ Not a linter |
Query analysis | ✅ 8 query patterns | ❌ Migration-only | ❌ Migration-only | ❌ Migration-only | ✅ Via execution |
EXPLAIN plan analysis | ✅ 4 plan checks | ❌ | ❌ | ❌ | ✅ Via EXPLAIN |
Index suggestions | ✅ Conservative candidates | ❌ | ❌ | ❌ | ❌ |
MCP server | ✅ 5 tools | ✅ 4 tools | ✅ 3 tools | ⚠️ Unclear | ✅ Multi-DB gateway |
No credentials needed | ✅ Never connects | ⚠️ Optional | ✅ Never connects | ❌ Requires DSN | ❌ Requires connection |
AI agent integration | ✅ MCP-native | ✅ MCP + CLI | ✅ MCP-native | ⚠️ MCP unclear | ✅ Multi-DB MCP |
Auto-fix | ❌ Recommendations only | ✅ 20 auto-fixes | ✅ Paste-ready rewrites | ⚠️ Unclear | ❌ |
PostgreSQL-specific | ✅ PostgreSQL-first | ✅ PostgreSQL-only | ✅ PostgreSQL-only | ✅ PostgreSQL-only | ❌ Multi-DB |
License | MIT | MIT | MIT | MIT | MIT |
Our differentiators:
Broadest scope: migrations + queries + EXPLAIN plans + index suggestions (4 capabilities in one tool)
Zero setup: No database, no credentials, no config — works on uncommitted code
Privacy-first: Completely offline, nothing sent anywhere
PostgreSQL-native: Not regex-based, handles comments, strings, dollar quotes, nested blocks
Lightweight: Zero dependencies beyond MCP SDK and Zod
When to use alternatives:
MigrationPilot: Need 112 rules, auto-fix, VS Code extension, GitHub Action with SARIF
Locksmith: Need paste-ready safe rewrites and lock matrix documentation
Ballast: Need load-aware analysis weighted by real table size (requires DB connection)
DBHub: Need to connect to live databases for exploration and guarded SQL execution
Database Doctor exposes 5 MCP tools for AI agents:
Tool | Input | Output |
|
| SQL anti-patterns with severity, message, recommendation, statement number |
|
| Destructive DDL, locking risks, transaction conflicts, constraint validation issues |
|
| Conservative index DDL candidates (never applied, requires EXPLAIN validation) |
|
| Large scans, row estimate errors, sort spills, high loops |
|
| Aggregate review of supplied artifacts (not live database health) |
All tools are read-only, idempotent, and require no authentication.
Reports include:
code: Stable identifier for the finding type
severity: high, medium, or low
message: What the issue is
recommendation: How to fix it
statement: Which statement in multi-statement SQL (1-indexed)
For migrations:
"Check this migration for locking issues"
"Review db/migrations/003_add_email_index.sql before I commit"
"Is this ALTER TABLE safe for a production table with 10M rows?"For queries:
"Analyze this query for performance issues"
"Why is this SELECT slow?"
"Review the queries in src/repositories/user.ts"For EXPLAIN plans:
"Review this EXPLAIN plan from plan.json"
"What's wrong with this execution plan?"For index suggestions:
"What indexes would help this query?"
"Suggest indexes for this WHERE clause"For aggregate review:
"Review all migrations in db/migrations/ for safety"
"Check queries.sql and migrations.sql for issues"Integration with development workflow:
"Before I commit, check the migration I just generated"
"Add this to pre-commit: check all .sql files for dangerous patterns"Database Doctor uses heuristic static analysis, not a full PostgreSQL parser or proof of safety.
✅ Comments (single-line -- and nested block /* */)
✅ String literals (including escaped E'...')
✅ Dollar-quoted strings ($$, $tag$)
✅ Quoted identifiers ("column_name")
✅ Common DDL and DML patterns
⚠️ Not a full SQL parser: Complex CTEs, nested scopes, unusual DDL may produce false positives or missed findings
⚠️ No schema metadata: Can't verify if a column exists, what type it is, or what indexes are present
⚠️ Index inference is conservative: Supports one unquoted table, no joins/subqueries, no composite index optimization
⚠️ Stored procedure bodies not analyzed: SQL inside functions, DO blocks, dynamic strings is not inspected
⚠️ No execution: Can't measure actual query time, lock duration, or real plan costs
⚠️ PostgreSQL-first: Not tested on MySQL, SQL Server, Oracle, or other dialects
✅ Finding detected: Review the specific pattern before applying
⚠️ No findings: Does NOT mean the SQL is safe, performant, or valid PostgreSQL
⚠️ Absence of a finding is not authorization to run a migration in production
Always test migrations on a safe environment before production.
Requirements: Node.js >=22.18 (Node 24 recommended)
# Install dependencies
npm install
# Type check
npm run check
# Run tests (core logic, no network)
npm test
# Build
npm run build
# Integration tests (MCP stdio after build)
npm run test:integration
# Verify package contents
npm pack --dry-runTest coverage: 53 core tests covering:
SQL masking (comments, strings, dollar quotes, quoted identifiers)
Query analysis (all 8 rules)
Migration checks (all 9 rules)
EXPLAIN plan parsing and analysis
Index suggestion logic
Health report aggregation
CI: GitHub Actions runs type check, tests, build, integration tests, and package verification on every push and PR.
Part of the petrovicistefan MCP suite — local-first guardrails for AI coding agents.
All tools in this family are:
✅ Local-first: Everything runs on your machine
✅ Read-only: No destructive operations (except explicit opt-in)
✅ No API keys: No accounts, no telemetry, no network calls (unless opted in)
✅ AI-native: Built specifically for AI coding agents
Server | Purpose |
Audit MCP servers for tool poisoning, rug pulls, and leaked secrets (OWASP MCP Top 10) | |
Detect expensive cloud patterns before they hit production | |
mcp-database-doctor | Catch dangerous PostgreSQL migrations and slow queries (you are here) |
Find outdated dependencies, CVEs, and license issues | |
Audit web pages for SEO and accessibility issues | |
Validate REST API designs against best practices | |
Browse and discover all MCP servers in the family |
Free forever:
Local query, migration, and EXPLAIN plan analysis
All 5 MCP tools
No usage limits
No telemetry
Pro tier (planned, opt-in):
History tracking (before/after comparisons)
CI policies and advanced recommendations
Hosted HTTP API (for non-MCP integrations)
Quotas via control-plane for hosted path only
Team tier (planned, opt-in):
Shared migration policies
Centralized reports
Fleet-wide query analysis
Local tools stay free and offline forever. Paid features are additive and require explicit opt-in.
Contributions are welcome! Please read CONTRIBUTING.md first.
Good first contributions:
Add test cases for false positives or missed findings
Improve documentation and examples
Add support for more PostgreSQL versions
Extend query or migration rules
Not currently accepting:
Support for other databases (MySQL, SQL Server, etc.) without a clear use case
Network-based features (stay local-first)
Contribution guide · Open issues · Report a false positive
MIT © Stefan Petrovici
See LICENSE for details.
I'm Stefan Petrovici: passionate about IT, a husband and a father. I built Database Doctor and the entire MCP suite on my own. I'm looking for a job.
I build web applications end to end—frontend, backend, APIs and deployment—and I'm happy to work on anything else that needs building. This repository shows how I work: tests, CI, careful documentation and attention to detail.
I also build WordPress and WooCommerce plugins, available at pluginsforstores.com.
If your team is hiring, write to me at hello@petrovicistefan.ro.
Found this useful? Star this repository!
A GitHub star helps other developers discover the project and lets you save it for later. Thanks for supporting open source!
Database Doctor is not affiliated with PostgreSQL, Anthropic, or any other vendor mentioned in this document.
Offline PostgreSQL SQL heuristics. No execution; no finding is not proof of safety.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: this is offline static analysis requiring no DB execution, and it explicitly warns about false negatives ('no finding is not proof of safety'). It does not disclose the specific checks performed or the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse sentences, front-loaded with the core capability and immediately followed by the most important caveat. Zero filler, though the extreme brevity edges toward under-specification rather than ideal concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter analyzer with annotations carrying the safety profile and no output schema, the description conveys the key operational fact (offline, no execution) and a critical caveat. It remains incomplete on what heuristics are run and what the result contains, which an agent would want before invoking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description says nothing about the single required 'sql' parameter (format, size limits, dialect expectations). With a low-coverage schema the description is expected to compensate and it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (PostgreSQL SQL) and the general action (heuristic analysis), and 'offline ... no execution' begins to separate it from an execution-based sibling like explain_plan. However, 'heuristics' is vague about what is actually being checked (performance, safety, style), so the agent cannot fully tell what this tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance and no sibling is named. 'No execution' implicitly contrasts with explain_plan and the caveat 'no finding is not proof of safety' is a limitation note, not routing guidance, so the agent must infer when to pick this over suggest_indexes or explain_plan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review PostgreSQL migration SQL for destructive operations, lock/rewrite risks and transaction conflicts. Does not execute.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Does not execute' largely restates the structured safety profile. The added value is naming the categories of issues it detects, which is more purpose than behavior; nothing is said about output format or size limits for the 100k-char input.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the scope and risk categories front-loaded and the critical non-execution caveat trailing immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-parameter analysis tool with annotations covering the safety profile and no output schema, the definition is largely sufficient. Naming the returned findings or the input length constraint would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One parameter at 0% schema description coverage. The description implies the parameter is migration SQL text, but adds no format, dialect-version, or batching guidance beyond that implication, so it only marginally compensates for the empty schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Review) plus resource (PostgreSQL migration SQL) and enumerates the exact risk classes examined: destructive operations, lock/rewrite risks, transaction conflicts. Combined with 'Does not execute', an agent can distinguish this static review tool from siblings like analyze_query or explain_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (migration SQL under review) and clarifies it is non-executing, but it never states when to prefer this over analyze_query or explain_plan, nor any preconditions. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Interpret a supplied PostgreSQL EXPLAIN FORMAT JSON plan. Does not run EXPLAIN ANALYZE.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the tool does not execute or benchmark the query, so the agent learns no runtime statistics are produced and the plan must be supplied pre-formed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the core action is front-loaded and the scope exclusion follows immediately. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description never indicates what the interpretation returns (e.g., structured findings vs. prose) or how large/complex plans are handled. For a single-parameter read-only tool this is adequate but leaves a real gap around the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema only reveals that 'plan' is a non-empty string up to 1MB. The description compensates by specifying the expected payload is a PostgreSQL EXPLAIN FORMAT JSON plan, which is essential to invoking it correctly, though the 1MB size ceiling and JSON-parse-failure behavior remain undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Interpret') and a specific resource ('PostgreSQL EXPLAIN FORMAT JSON plan'), which is far more precise than a generic 'explain query' phrasing. The closing sentence clarifies scope by ruling out EXPLAIN ANALYZE, though it does not explicitly name which sibling (e.g., analyze_query) handles the alternative case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'Does not run EXPLAIN ANALYZE' supplies one clear when-not condition, implying the plan must already have been captured. However, there is no positive guidance on when to reach for this tool versus analyze_query or suggest_indexes, so usage is only partially implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate diagnostics over supplied artifacts, not live database health.
| Name | Required | Description | Default |
|---|---|---|---|
| plans | No | ||
| queries | No | ||
| migrations | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the diagnostics run against caller-supplied artifacts rather than a live connection, which changes how the agent should think about the call. It stops short of describing batching limits or what happens with empty input.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core action and appends the one discriminator that matters. Every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations are rich and the schema is simple, so the safety and shape story is mostly told. But with no output schema, the description never indicates what the aggregated report contains or how multiple artifact types are combined, and it leaves the optional/required nature of the three arrays unaddressed. Adequate, not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema supplies only property names and array-of-string types. The phrase "supplied artifacts" hints that the inputs are inline content rather than IDs or file paths, but it never maps to plans/queries/migrations individually, states the expected format (SQL text? serialized plans?), or notes that all three are optional. Compensation for the coverage gap is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Aggregate diagnostics over supplied artifacts" names a specific verb (aggregate) and resource (diagnostics), and the trailing clause carves out a distinct scope from live-DB tools. It implies, but does not name, the sibling relationship to analyze_query/check_migration/explain_plan, so sibling differentiation is indirect rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"not live database health" is an effective when-not constraint that rules out the wrong mental model, which is more than most descriptions offer. However, it never says when to prefer this tool over analyze_query or check_migration, nor that the tool is appropriate for batch/offline review, so the positive routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Conservative index candidates for single unquoted table queries. Requires EXPLAIN validation; never applies DDL.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| existingIndexes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so safety is covered. The description still adds real value by stating it 'never applies DDL' (reinforcing advisory-only behavior) and that output 'Requires EXPLAIN validation', which is procedural context the annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the scope constraint and the advisory nature front-loaded. No filler; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotation coverage of parameters, the definition should explain the sql input and existingIndexes role, and ideally the shape of returned candidates. It conveys the safety posture well but leaves the calling contract under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions the two parameters. The sql input format and the purpose of existingIndexes (why pass known indexes) are left entirely unexplained; the vague 'single unquoted table queries' phrase hints at a sql constraint but does not define it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action and resource ('index candidates') plus an explicit scope restriction ('single unquoted table queries') and a quality stance ('conservative'). This is far more than a restatement of the name, but it distinguishes itself from no sibling tool (analyze_query, explain_plan) by name or role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Requires EXPLAIN validation' gives downstream workflow context and 'never applies DDL' bounds the action, but there is no explicit when-to-use guidance relative to analyze_query or explain_plan. An agent must infer that this is advisory-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1analyze_querycheck_migrationexplain_planhealth_reportsuggest_indexesScored across 5 tools
Each tool targets a distinct artifact: raw SQL (analyze_query), migration SQL (check_migration), index candidates (suggest_indexes), EXPLAIN JSON plans (explain_plan), and aggregated artifacts (health_report). analyze_query and suggest_indexes both operate on queries, so there is mild overlap, but their differing outputs keep them separable.
Four of five names follow a clean verb_noun pattern (analyze_query, check_migration, suggest_indexes, explain_plan). health_report breaks the pattern as a noun_noun label, a minor deviation that is still readable.
Five tools is well-scoped for an offline PostgreSQL diagnostic suite, with each tool covering a distinct analysis dimension and no redundant entries.
The surface covers the core diagnostic dimensions for a read-only, offline advisory role: query heuristics, migration risk, index advice, plan interpretation, and health aggregation. No write/live-DB operations are expected given its stated non-executing purpose, though a dedicated schema/config check is absent.
DBRE-grade SQL analysis inside any MCP client. No connection. No install. Paste a query.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
SQL validation, formatting, parsing, metadata extraction, linting, and security analysis.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
