Query Result Encoding: Why Markdown Tables WinΒΆ

Demonstrates why markdown tables are superior to JSON for encoding SQL query results in LLM contexts

When returning SQL query results to AI assistants, markdown tables significantly outperform JSON in both token efficiency and readability. Our analysis of 200 sample records shows markdown tables use 24% fewer tokens (9,621 vs 12,305) compared to NDJSON format.

Key Advantages of Markdown Tables:

  • Token Efficiency: 24% reduction in token usage compared to JSON

  • Visual Structure: Tabular format matches how humans naturally read data

  • LLM Comprehension: AI models excel at interpreting structured markdown tables

  • Immediate Readability: No parsing required - data is instantly comprehensible

Why JSON Falls Short:

  • Verbose Syntax: Repeated field names and JSON punctuation increase token count

  • Poor Readability: Requires mental parsing to understand data relationships

  • Limited Structure: No visual alignment or column-based comprehension

The query_result_encoding_example.py script demonstrates this comparison using 200 fake customer records, proving that markdown tables are the optimal format for SQL result encoding in MCP servers.

query_result_encoding_example.py
 1# -*- coding: utf-8 -*-
 2
 3import json
 4from pathlib import Path
 5
 6import tabulate
 7from faker import Faker
 8
 9dir_here = Path(__file__).absolute().parent
10
11fake = Faker()
12n_rows = 200
13
14rows = list()
15for i in range(1, 1+n_rows):
16    id = i
17    name = fake.name()
18    email = fake.email()
19    address = fake.address()
20    create_time = fake.date_time().strftime("%Y-%m-%d %H:%M:%S")
21    row = dict(
22        id=id,
23        name=name,
24        email=email,
25        address=address.replace("\n", ", "),
26        create_time=create_time,
27    )
28    rows.append(row)
29
30
31columns = ["id", "name", "email", "address", "create_time"]
32
33tb = tabulate.tabulate(
34    [tuple(row.values()) for row in rows],
35    headers=columns,
36    tablefmt="pipe",
37)
38path_markdown = dir_here / "01_markdown_table.md" # 9,621 tokens
39path_markdown.write_text(str(tb))
40
41lines = list()
42for row in rows:
43    line = json.dumps(row, ensure_ascii=False) # 12,305 tokens
44    lines.append(line)
45
46path_ndjson = dir_here / "02_ndjson_table.ndjson"
47path_ndjson.write_text("\n".join(lines))