jdbc-mcp-server

Overview Schema Source Related Servers Discussions Admin

analyzePlan

analyzePlan

Read-onlyIdempotent

Diagnose query-plan performance issues with compact structured findings, identifying expensive nodes, full scans, estimation errors, risky nested loops, and disk spills.

Instructions

Diagnose query-plan performance with compact structured findings: expensive nodes, large-table full scans, estimation errors, risky nested loops and disk-sort spills. Use explainQuery when the full textual plan is required. Bind '?'->params, ':name'->namedParams; never mix. E.g. :status -> namedParams={status:'PAID'} — key is the bare name.

Input Schema

TableJSON Schema

Name	Required	Description
`sql`	Yes
`params`	No	Values for '?' placeholders, in order.
`analyze`	No	Execute the query to collect runtime stats where supported (default false).
`connection`	Yes	Database to run against. Call listConnections for valid names; do not guess.
`namedParams`	No	Values for ':name' placeholders, keyed by name.

Output Schema

TableJSON Schema

Name	Required	Description
`root`	No	Root node of the execution plan.
`engine`	No	Database engine that produced the result, such as PostgreSQL, Oracle, or SQL Server.
`analyzed`	Yes	True when the plan includes actual execution metrics, not only estimates.
`fullScans`	No	Plan nodes that perform full table or index scans and may deserve attention.
`nodeCount`	Yes	Number of table nodes in the schema graph.
`diskSpills`	No	Sort or hash nodes that appear to spill to disk.
`planningTimeMs`	No	Planner time reported by the database, in milliseconds when available.
`executionTimeMs`	No	Execution time reported by the database, in milliseconds when available.
`estimationErrors`	No	Plan nodes where actual rows differ materially from estimated rows.
`riskyNestedLoops`	No	Nested-loop nodes that may be expensive because the outer side is large.
`topExpensiveNodes`	No	Plan nodes ranked as most expensive by cost or actual time.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 15, 2026

TDQS

A4.8/5.0

Behavior4/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by disclosing that output is 'compact structured findings' rather than a full textual plan and enumerates the diagnostic categories. It does not contradict annotations, though it doesn't discuss the runtime-execution implications of the analyze parameter, which is covered in the schema.

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 compact and front-loaded: first the purpose, then the alternative tool, then the binding rule with a concrete example. Every sentence earns its place with no filler or 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?

With an output schema present, detailed return structure is unnecessary. The description covers the key routing decision, the parameter binding convention, and the diagnostic scope, while remaining fields like connection and analyze are already documented in the schema. This is complete for the tool's complexity.

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

Parameters5/5

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

Schema coverage is already high, but the description adds critical binding semantics beyond the schema: '?' maps to params, ':name' maps to namedParams, never mix, and the example clarifies that the object key should be the bare name without the colon. This directly helps an agent construct valid calls.

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 explicitly states the tool diagnoses query-plan performance and lists concrete findings it returns: expensive nodes, large-table full scans, estimation errors, risky nested loops, and disk-sort spills. It uses a specific verb ('Diagnose') with a clear resource ('query-plan performance') and differentiates itself from explainQuery in the next sentence.

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 gives explicit selection guidance: 'Use explainQuery when the full textual plan is required.' This directly tells the agent when not to use analyzePlan and which sibling tool is appropriate instead. It also includes binding instructions that guide correct invocation.

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