Token-efficient output format

[apgiorgi]

Part of the Agentic UX spec series. See sibling issues for related buckets.

Motivation

When the CLI is driven by an LLM agent (Claude Code, Cursor, Kiro, etc.), every byte of output is a token the agent pays for and a token that competes with the rest of its context window. Internal reports show engineer API spend jumping from ~$125/mo subscription to ~$1000/mo on raw API once agentic workflows take over (ai-token-economics channel, 2026-05-27). Our default JSON shapes were designed for humans + scripts, not for agents.

Spec

Make the default agent-facing output as compact as possible without losing fidelity.

Output format

• Support --output toon (TOON — Token-Oriented Object Notation) alongside today's json/yaml/table. TOON reports ~40% token savings vs JSON for list-shaped data.
• Keep table as the human default; promote a compact format (TOON or minified JSON) as the agent-mode default (see sibling Agent-mode detection and behavior split #10).

Schema

• Minimal default schemas: list operations return ≤4 fields per item (e.g. id, name, severity, updated). Full record only on get or with --full.
• Terse, stable field names: e.g. cost not totalAggregatedCostUsd. Stability is part of the contract — renames are breaking changes.
• Projection: --fields a,b,c to pick exact fields, and --exclude for the inverse.
• Content truncation with size hints: long text fields (descriptions, queries, error messages) truncate to N chars with a marker like {"value": "...", "_truncated": 4821}. Escape hatch: --full or --no-truncate.

Defaults

• Lower default --limit in agent mode (e.g. 25 vs the current default).
• Document each list endpoint's default + max.

References

• axi.md — "How to build agent-efficient tools", principles 1 (token-efficient output), 2 (minimal default schemas), 3 (content truncation): https://axi.md/
• Grafana gcx CLI announcement — --output json|yaml with stable field names: https://grafana.com/blog/get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool/
• "Be brief" benchmark (terse defaults rival explicit compression prompts): https://www.maxtaylor.me/articles/i-benchmarked-caveman-against-two-words
• squish-prompts — internal prompt compression: https://github.com/doitintl/squish-prompts
• LLMLingua paper (compression basis): https://arxiv.org/abs/2409.01227

Open questions

• Do we commit to TOON specifically, or keep json minified as the agent default?
• Are existing JSON field names already a contract (any external consumers parsing them)?
• Where do we draw the truncation length — global default vs per-field?

Acceptance criteria

• --output accepts a compact format and emits documented stable shapes
• List operations default to ≤4 fields; --full returns the wide record
• --fields and --exclude work on every list/get operation
• Long text fields truncate with a documented marker; --full disables truncation
• Each operation documents its default and max --limit
• Field-name contract documented in README/DISTRIBUTION.md

[apgiorgi]

Shipped the TOON output slice as PR #23 (--output toon). Notes on scope and the remaining criteria, since they drove the design:

What's done

• --output toon emits TOON via a restish content type (dciToonContentType) that mirrors the existing table type and degrades to indented JSON on encode error. table stays the default — selection is opt-in. Pure-Go dep (toon-format/toon-go), no cgo.

Deliberately deferred (still open here)

• --fields/--exclude projection, content truncation, lower default --limit — all clean, format-agnostic, and independent. The limit default depends on agent-mode (Agent-mode detection and behavior split #10).

Recommend reconsidering the field-name contract criterion (minimal ≤4-field schemas + terse stable renames like cost not totalAggregatedCostUsd):

dci is a passthrough wrapper — it forwards the API's response schemas, it doesn't own them. Implementing terse stable field names means the CLI maintains a per-endpoint rename + projection table and keeps it in sync as the API evolves. That's brittle, it fights the locked-down passthrough design, and "stable field names as a contract" is really an API-side responsibility. The issue's own open question ("are existing JSON field names already a contract?") points at the same tension.

Suggestion: split the field-rename/minimal-schema piece into its own issue and consider pushing it to the API, or scope it down to generic projection + truncation only (no per-endpoint rename maps), which the deferred items above already cover.