Add markdown output format for execute_sql to reduce token usage by ~50%

[ericseastrand-ln]

Summary

• Adds output_format parameter to execute_sql and execute_sql_multi MCP tools
• Default is "markdown" — returns a markdown table string instead of JSON array-of-objects
• output_format="json" preserves existing behavior for backwards compatibility
• Includes 7 unit tests for the markdown formatter

Closes #296

Problem

execute_sql returns results as a JSON array of objects, repeating every column name on every row:

[
  {"event_id": "EVT-10001", "event_name": "Concert A", "venue": "Arena 1", "city": "NYC"},
  {"event_id": "EVT-10002", "event_name": "Concert B", "venue": "Arena 2", "city": "Chicago"}
]

Since MCP tools are consumed by LLMs, this is extremely wasteful — ~42% of the payload is redundant column names. In a real session with 107 SQL queries, this caused 4 context compaction events and burned ~64M tokens.

Solution

Return a markdown table by default:

| event_id | event_name | venue | city |
| --- | --- | --- | --- |
| EVT-10001 | Concert A | Arena 1 | NYC |
| EVT-10002 | Concert B | Arena 2 | Chicago |

(2 rows)

For a 100-row × 10-column result set:

Format	Size	Savings
JSON (current)	27,380 chars	—
Markdown (new default)	13,860 chars	50%

Changes

• databricks-mcp-server/databricks_mcp_server/tools/sql.py — adds _format_results_markdown() helper and output_format parameter to both execute_sql and execute_sql_multi
• databricks-mcp-server/tests/test_sql_output_format.py — 7 unit tests covering empty results, single/multiple rows, None handling, pipe escaping, column-name-once guarantee, and size comparison

No changes to databricks-tools-core — formatting is applied at the MCP server layer only.

Test plan

• All 7 new tests pass (pytest tests/test_sql_output_format.py)
• Existing passing tests unaffected
• Manual test: run execute_sql with default format and verify markdown output
• Manual test: run execute_sql with output_format="json" and verify JSON output

[calreynolds]

Thank you! Great PR 👍