#615 model type describe --json: bloated output (40% duplicated specs, no compact mode) and lost method-to-output mapping drive agents to read extension source

Type

Improvement (agent/CLI UX)

Environment

• swamp 20260610.170238.0-sha.c5ede61b, macOS (darwin)
• Behavior confirmed unchanged as of 20260610.185312.0 availability check (diagnosis is behavioral, no source files compared)

Summary

swamp model type describe --json is the primary machine-readable discovery surface for agents, and field data shows it is a hot path: across my Claude Code transcripts (174 sessions, ~8,000 swamp invocations), the discovery-to-execution ratio is roughly 1:4.5 (425 discovery calls vs 1,899 method run calls) — schemas are re-discovered every session, not once. At that consumption frequency the current output has two problems.

1. The output answers "how to call" but not "what will happen" — so agents read extension source instead

A method entry carries only name, a one-line description, an argument JSON Schema (arguments plus an identical inputs copy), and dataOutputSpecs. Critically, every method carries an identical copy of the type-level output spec set, so the method-to-output mapping is unrecoverable from the CLI: for a 27-method type declaring 10 output specs, you cannot tell which output a given method actually writes, or under what data name. There are also no example invocations and no sample output.

Verified on three multi-method extension types (27, 12, and 5 methods respectively):

$ swamp model type describe <type> --json | \
    jq '[.methods[].dataOutputSpecs] as $a | [$a[] | . == $a[0]] | all'
true        # all methods carry the same full spec set — on every type tested

Measured consequence: my transcripts contain 97 Read calls on definition YAML plus a large share of 434 reads of extension TS source where the agent was answering questions discovery couldn't — "which output does this method produce, what does the result actually look like, what are the side effects".

2. The output is not sized for its consumption frequency

$ swamp model type describe <27-method type> --json | wc -c
391823      # ~100k tokens, for ONE type
$ swamp model type describe <12-method type> --json | wc -c
425955

Breakdown for the 391,823-byte example:

• 158,330 bytes (40%) = the identical dataOutputSpecs set duplicated into all 27 methods
• inputs is a byte-for-byte duplicate of arguments on every method (backward compat), doubling another ~4.7KB
• a minimal digest of the same type — jq '[.methods[] | {name, description}]' — is 2,153 bytes, a ~180x reduction

The human-readable swamp model get <name> already renders exactly the right digest (methods, one-line descriptions, inputs with types/required, outputs) — but there is no JSON equivalent, so agents must choose between a 400KB schema dump and parsing ANSI-colored text.

Steps to reproduce

swamp extension pull <any multi-method extension>   # e.g. @magistr/pihole
swamp model type describe <type> --json | wc -c
swamp model type describe <type> --json | \
  jq '[.methods[].dataOutputSpecs] as $a | [$a[] | . == $a[0]] | all'   # true
swamp model type describe <type> --json | \
  jq '.methods[0].inputs == .methods[0].arguments'                      # true

The duplication is runtime behavior (the type-level spec set is copied into every method during describe), not an extension-author choice — it reproduces with any multi-method extension that declares output specs.

Expected

• Discovery tells an agent which output spec(s) a given method writes (per-method association, not a type-level copy into every method).
• A compact machine-readable mode exists for the common "what methods are there and how do I call them" question.
• Output specs and argument schemas are emitted once, not duplicated.

Suggested fixes (independent, in impact order)

1. Emit dataOutputSpecs once at type level, with methods referencing the specs they actually write by name. Fixes both the 40% size bloat and the lost method-to-output semantics in one change.
2. Add a compact digest mode (e.g. model type describe --compact --json, or a JSON twin of the model get human rendering): method name, description, argument names/types/required, output spec names. Target <=5KB per type.
3. Drop the inputs/arguments duplication from JSON output (keep one; alias behind a flag if compat matters).
4. Optional per-method examples field in extension method metadata (example invocation + truncated sample output), surfaced by describe — directly removes the remaining reason agents open extension source.

Related

• #439 "Slim down extension search output now that extension info exists" (shipped) — same principle applied to extension search; this issue is the model type describe counterpart.