Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
MCP Tools
explain_sql
Show the execution plan for a SQL statement without running it.
Only a single statement is accepted (no
See Tool Configuration for how
Features
- Never executes: Only ever compiles/plans the statement — safe to enable regardless of the source’s
readonlysetting - Per-dialect output: Uses
EXPLAINon PostgreSQL, MySQL, MariaDB, and SQL Server, andEXPLAIN QUERY PLANon SQLite (bareEXPLAINon SQLite returns low-level bytecode, not a readable plan) - Opt-in only: Not part of the default tool pair — must be explicitly enabled per source
explain_sql is opt-in. Unlike execute_sql and search_objects, it is not enabled automatically when a source has no [[tools]] entries — add it explicitly (see Enabling explain_sql below).Usage
Pass a single SQL statement to explain. The tool adds theEXPLAIN prefix itself — do not include it in the input.
SELECT * FROM users WHERE status = 'active'
EXPLAIN SELECT * FROM users WHERE status = 'active'
;-separated batches), and the input must not itself begin with EXPLAIN or ANALYZE — both are rejected so the tool’s own EXPLAIN prefix can never combine with a smuggled ANALYZE to actually execute the statement.
Because plain
EXPLAIN never executes the target statement, explain_sql is safe to run against write statements too. explain_sql on DELETE FROM users WHERE id = 1 returns the plan without deleting anything.Enabling explain_sql
Add a[[tools]] entry with name = "explain_sql". It takes no other options — no readonly or max_rows — since it’s always read-only:
[[sources]]
id = "production"
dsn = "postgres://user:pass@localhost:5432/mydb"
[[tools]]
name = "execute_sql"
source = "production"
readonly = true
[[tools]]
name = "search_objects"
source = "production"
[[tools]]
name = "explain_sql"
source = "production"
[[tools]] entries work across multiple sources.