feat: add verbose mode to explain_query for scan-level metrics

[killme2008]

Problem

explain_query only ever issued EXPLAIN or EXPLAIN ANALYZE, never EXPLAIN ANALYZE VERBOSE. The index-pruning counters that matter for diagnosing query performance — rg_bloom_filtered, rg_inverted_filtered, rg_minmax_filtered, rows_bloom_filtered, rows_inverted_filtered — live in mito2's per-partition ScanMetricsSet and only render under VERBOSE (and only when > 0). Non-verbose output just shows the coarse partition_count (files / file_ranges), which says nothing about row-group-level pruning.

The query_performance_tuning prompt even acknowledged the gap: it told users to fall back to execute_sql with EXPLAIN ANALYZE VERBOSE <query> because the tool couldn't produce it.

Change

• Add a verbose: bool = False parameter to explain_query, orthogonal to analyze.
  • SQL path: EXPLAIN [ANALYZE] [VERBOSE] <query>
  • TQL path: TQL ANALYZE|EXPLAIN [VERBOSE] ... (TQL supports VERBOSE too, verified against a live instance)
• Update the query_performance_tuning prompt to use explain_query(analyze=true, verbose=true) instead of the execute_sql workaround.
• Sync tool descriptions in README, docs/llm-instructions.md, and the table_operation prompt.

Scan-level index-pruning counters require analyze=true, verbose=true (the counters are only produced during actual execution).

Tests

Added 3 tests that spy on the executed SQL and assert correct keyword assembly:

• EXPLAIN ANALYZE VERBOSE (analyze + verbose)
• EXPLAIN VERBOSE (verbose without analyze — confirms orthogonality)
• TQL ANALYZE VERBOSE (TQL path)

Full suite: 188 passed, flake8 clean, black clean.

[Copilot]

Pull request overview

Adds a verbose option to the explain_query MCP tool so users can request EXPLAIN ... VERBOSE (and EXPLAIN ANALYZE VERBOSE) output, enabling visibility into scan-level/per-partition metrics that aren’t shown in non-verbose explains. Updates prompt templates/docs to use the new capability and bumps the package/registry version.

Changes:

• Extend explain_query with verbose: bool = False and assemble EXPLAIN [ANALYZE] [VERBOSE] <query> (plus TQL ANALYZE|EXPLAIN [VERBOSE] ... rewriting).
• Add tests that spy on executed SQL to validate keyword assembly for SQL and TQL paths.
• Update prompts/docs/README references and bump version from 0.5.0 to 0.5.1.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/greptimedb_mcp_server/server.py	Adds verbose parameter and keyword composition for SQL/TQL explain execution.
tests/test_server.py	Adds 3 tests verifying correct EXPLAIN/TQL ... VERBOSE generation via a cursor spy.
src/greptimedb_mcp_server/templates/query_performance_tuning/template.md	Switches guidance from execute_sql workaround to explain_query(..., analyze=true, verbose=true).
src/greptimedb_mcp_server/templates/table_operation/template.md	Updates tool description to mention verbose mode.
README.md	Updates explain_query tool description to mention verbose=true.
docs/llm-instructions.md	Updates tool description to mention verbose=true.
pyproject.toml	Bumps project version to 0.5.1.
server.json	Bumps MCP registry metadata version to 0.5.1.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.