Execute a read-only SQL query and return rows as JSON.

Use this tool when the user wants to read data with SQL: filtering, joining, aggregating, or ad-hoc questions the schema tools cannot answer. Only SELECT / SHOW / DESCRIBE / EXPLAIN statements are accepted; INSERT/UPDATE/DELETE/DDL are refused — this server is strictly read-only. File-writing and lock functions (INTO OUTFILE, SLEEP, GET_LOCK, BENCHMARK, LOAD_FILE) are also refused.

Placeholders: use %s (PyMySQL style), not ?, and pass the values as a JSON array in params_json.

Returns JSON: {rows, rowCount, truncated, maxRows}. When truncated is true, the result was capped at maxRows rows.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the retrieved data.

Preferred rendering — card-based layout: when the client supports rich widgets or HTML artifacts, render a header card (query intent), a results table card, and a footer card with row count and a truncation notice if applicable.

Fallback — Markdown: one-line summary first, then a compact Markdown table of the rows.

Formatting rules (both modes): human-readable dates and numbers; never paste raw JSON unless explicitly asked; mention truncation when truncated is true; omit internal fields the user did not ask about.

Run EXPLAIN on a SELECT query and return the execution plan.

Use this tool when the user asks why a query is slow, whether an index is used, or how MySQL will execute a SELECT. Only SELECT statements are accepted (not SHOW/DESCRIBE/EXPLAIN).

Returns JSON: {format, originalSql, explainSql, rowCount, rows} where rows contain the plan.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the analysis.

Preferred rendering — card-based layout: when the client supports rich widgets or HTML artifacts, render a header card with the query, a plan table card (access type, key, rows examined), and a highlights card calling out full scans or missing indexes.

Fallback — Markdown: one-line verdict first (e.g. "uses index X"), then a compact Markdown table of the plan rows.

Formatting rules (both modes): explain the plan in plain language; never paste raw JSON unless explicitly asked.

List all databases visible to the configured MySQL account.

Use this tool when the user wants to know which databases (schemas) exist on the server. Returns JSON: {databases: [...]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: when the client supports rich widgets, render a single card with the database names as a clean list or chips.

Fallback — Markdown: one-line summary (count), then a bulleted list.

Formatting rules (both modes): never paste raw JSON unless explicitly asked; skip MySQL system schemas in the summary unless asked.

List tables in a database.

Use this tool when the user wants to see what tables exist. Returns JSON: {tables: [...], database}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card naming the database and a table-list card.

Fallback — Markdown: one-line summary (database + count), then a bulleted list of tables.

Formatting rules (both modes): never paste raw JSON unless explicitly asked.

Get the column structure of a table (DESCRIBE output).

Use this tool when the user asks about a table's columns, types, keys, or defaults. Returns JSON: {table, database, columns: [{Field, Type, Null, Key, Default, Extra}]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card with the table name and a columns table card (name, type, nullable, key, default).

Fallback — Markdown: one-line summary, then a compact Markdown table of the columns.

Formatting rules (both modes): never paste raw JSON unless explicitly asked; highlight primary keys in the summary.

Inspect all tables, columns, and indexes of a database at once.

Use this tool when the user wants an overview of a whole schema — e.g. to understand an unfamiliar database or plan queries. Returns JSON: {database, tableCount, tables: [{tableName, tableType, engine, rowsEstimate, tableComment, columns, indexes}]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card for the database (table count), then one card per table with its columns and indexes as compact tables.

Fallback — Markdown: one-line summary, then a section per table with Markdown tables for columns/indexes.

Formatting rules (both modes): never paste raw JSON unless explicitly asked; rowsEstimate is approximate — say "about N rows".

Find tables by matching table or column names.

Use this tool when the user knows roughly what they're looking for ("something with customer emails") but not the exact table. Returns JSON: {database, term, matchCount, matches: [{tableName, tableType, engine, matchedTableName, matchedColumns}]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card with the search term and one row per match showing why it matched (name vs columns).

Fallback — Markdown: one-line summary (match count), then a compact Markdown table of matches.

Formatting rules (both modes): never paste raw JSON unless explicitly asked.

Read a small sample of rows from a table (capped at 50).

Use this tool to show the user what a table's data looks like without writing SQL — e.g. right after describe_table. Returns JSON: {database, table, limit, rowCount, rows}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card naming the table and a results table card with the sampled rows.

Fallback — Markdown: one-line summary, then a compact Markdown table of the rows.

Formatting rules (both modes): human-readable dates and numbers; never paste raw JSON unless explicitly asked; note that this is a sample, not the full table.

Check MySQL connection health and basic server status.

Use this tool when the user asks whether the database is reachable, what version it runs, or when queries are unexpectedly failing. Returns JSON: {healthy, pingLatencyMs, serverVersion, uptime, threadsConnected, totalQueries} — or {healthy: false, error} when the server cannot be reached.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the status.

Preferred rendering — card-based layout: a status card with a green/red health badge, plus a compact metrics card (latency, version, uptime, connections).

Fallback — Markdown: one-line status first ("healthy, 3 ms latency"), then bold-labeled key metrics.

Formatting rules (both modes): render uptime in human units (days/ hours); never paste raw JSON unless explicitly asked.