---
name: jgravelle-tool-surface-discipline
description: "The small-front-door principle and what counts as a tool-surface change. Load in /feature step 3, in review, and before editing any tool name, argument, description or tier."
license: "NOASSERTION"
metadata:
  decimalai-skill-id: "14d88176-dec1-4d42-b16a-cfc78bbe651a"
  decimalai-version-id: "dad72ab6-b5bd-421a-a961-1f763d793c7b"
  decimalai-version: "1"
  decimalai-body-sha256: "dc76ee3500fea21cfc53e803d3bcd67217566cbdaff7652328b8b8aad3948c53"
  decimalai-name: "jgravelle/tool-surface-discipline"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "agent-tooling"
  decimalai-source: "https://app.decimal.ai/s/jgravelle-tool-surface-discipline@1/SKILL.md"
---
# 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.