tool-surface-disciplinelisted
Install: claude install-skill jgravelle/jcodemunch-mcp
# Tool-surface discipline
Authority: `docs/standard/STANDARD.md` criterion 4; CLAUDE.md
"Tool-description quality", "Codex tool-surface benchmark", "Tier-switch
pricing"; `tests/test_schema_budget.py`,
`tests/test_counter_surface_stability.py`, `tests/test_description_smells.py`;
`scripts/surface_diff.py`.
The principle in three sentences: the published `counter` surface is
byte-pinned and a reworded description is a full-rate cache write for every
user; `core_compact` has a hard token ceiling the tree sits within a few
tokens of; a new tool is paid for on every request by every user whether or
not they call it.
A surface change is ANY of: a tool added, removed or renamed; an argument
added, removed or retyped; a description reworded; a tier or profile
membership moved; a Counter front-door change; an always-visible control
added. `scripts/surface_diff.py` sees names only (`docs/workflows/FINDINGS.md`
W-1); descriptions are diffed from `_build_tools_list()` dumps.
Every surface change carries: README tool reference, CLAUDE.md Key Files
(invariant) or KEY-FILES.md (description), CHANGELOG naming the tool, and
`benchmarks/schema_baseline.json` regenerated with the token delta stated
(DoD 4). The `schema.core_compact_ceiling` verdict decides whether a
description may grow; the answer is usually to trim.