execute_sql: markdown field is redundant payload — remove it or make it opt-in?

[sandeep-agami]

Type: payload reduction / enhancement. Contains an open design question for the owner — see below.

Summary

execute_sql returns a pre-rendered markdown table in addition to columns + rows + units. The markdown restates every value (with currency symbols + grouping), so it's a redundant copy of the tabular data — and in practice larger than rows itself. Since the MCP response is ingested by an LLM (tokens), it's payload cost on every call for data the client can already render from rows (exact strings) + units (format hints).

Measurements (102 live execute_sql calls)

• markdown total: 39,986 bytes — larger than rows (36,972 bytes); markdown ≥ rows on 97 / 102 queries.
• markdown is ~8% of the total response payload.
• For context, the receipt is 79% of the payload (see execute_sql trust receipt over-reports metrics: substring binding match on COUNT(*) yields false positives #144) — that's the bigger reduction; this is the smaller, cleaner one.

Why it's redundant

The exactness guarantee (the number a user verifies shouldn't drift through LLM reformatting) is already delivered by:

• rows — exact strings at full NUMERIC precision, and
• units — the per-column currency/unit, so the client formats correctly.

markdown is a third, pre-baked combination of those two. It saves the client a formatting step at the cost of duplicating (and slightly inflating) the whole table on every call.

Open question — owner decision (@ashwin-agami)

Two options; pick one:

1. Remove markdown entirely. Leanest. Clients render from rows + units. Loses the server-guaranteed exact display string.
2. Make markdown opt-in. e.g. an include_markdown argument (default off) or a response-fields selector, so a host that wants the pre-rendered exact table can request it while the default response stays lean.

The deciding check: does anything actually consume result.markdown today? (e.g. the agami-query skill / Claude Desktop trust panel rendering it verbatim). If yes → (2) preserves that consumer; if nothing depends on it → (1).

Where

packages/agami-core/src/tools.py::_finalize_execution builds markdown via units.format_table. Same seam already emits rows + units, so gating or dropping markdown is localized.