Skip to content
Ascend GTM Ops — Docs

Retain all 25 registered tools — close Task 1.2 by decision, not by telemetry-driven cuts

ADR-023: Retain all 25 registered tools — close Task 1.2 by decision, not by telemetry-driven cuts

Status: Accepted Date: 2026-04-24 Deciders: Mishaal Murawala Supersedes (partial): Phase 1 Task 1.2 per V5-PHASE-1-CONSOLIDATION-SPRINT.md. ADR-018 exit-criterion for Task 1.2 is satisfied by this ADR.

Context

Phase 1 Task 1.2 was scoped as “audit tools by telemetry, cut 3–5 with <5 calls/7d.” The plan explicitly listed candidates: discover_apis, aws_textract_analyze, gamma_generate, claude_files (already subsumed by the unified claude tool in Task 1.3), and any tool below the usage threshold.

PR #44 shipped the Analytics Engine telemetry pipeline on 2026-04-23, which would have produced the usage data by ~2026-04-30. In the 2026-04-24 session, Mishaal made an explicit call:

“we won’t be using some of the tools for a long time. but we don’t want to cut them. no need to wait.”

Decision

Retain all 25 currently registered tools. Close Task 1.2 as resolved by decision. Phase 1 is complete on 2026-04-24, not 2026-04-30.

Cuts are not the point of this task; correct sizing is. The user’s judgment is that low-near-term-use tools still have option value — removing them forces a future re-registration cost (tool file, tests, docs, TOOLS.md row, HANDOVER update, provider config) that outweighs the marginal token-schema savings today.

Why not cut anyway

  1. Per-session token cost of schema is bounded. The 25-tool schema fits well within the MCP context budget. Cutting 4 tools saves perhaps 5–10% of tool-schema tokens, which is noise next to the 10× savings already delivered by consolidating claude_* in PR #49.
  2. Re-registration is not free. Every tool has a test file, a doc, a TOOLS.md row, and a PROVIDERS entry (for provider-backed tools). Re-adding one later is 30–60 min of ceremony; keeping it is zero.
  3. The telemetry is still valuable — it feeds per-tool latency p95s, error-rate alerts, and cost attribution. Keeping the pipeline without acting on “cut” signals is the correct use of the data at current scale.
  4. ADR-018 precondition 1 still binds. The pre-commit check 04 cap remains 25 (not bumped). Any future tool addition still requires dropping something else first — this ADR just freezes the current set against reflex cuts.

What the Phase 1 exit contract actually required

From the plan:

≤25 tools registered in src/handlers/mcp.ts (pre-commit check 04 cap updated to 25).

We are at exactly 25. The criterion was met in PR #49 (28 → 25 via claude_* consolidation), not by any subsequent cuts. Task 1.2 as originally scoped was a nice-to-have inside an already-satisfied exit criterion.

Consequences

Positive

  • Phase 2 (Context Plane Scaffold) unblocks immediately. No 6-day idle wait on data.
  • Low-use tools stay in the surface for the agents that occasionally need them (discover_apis remains a useful first-call pattern for new agents; aws_textract_analyze stays for PDF-heavy workflows when they arrive; gamma_generate stays for content pipelines; etc.).
  • Removes a dependency on a specific calendar date (2026-04-30) which was always fragile.

Negative

  • Carrying 4–5 tools whose schema tokens deliver little value until someone uses them. Acceptable given the above math.
  • If we ever DO want to cut, we’ll need to run the audit query manually rather than inheriting the results from this Phase’s sprint work. Trivial cost.

Future-reversal trigger

If schema token cost becomes measurable (per-session p95 > 25% of context budget consumed by tool schema, or agents routinely hit context limits on tool-heavy sessions), revisit — but via explicit decision, not auto-cuts.

Phase 1 final status (2026-04-24)

All exit criteria met:

  • ✅ ≤25 tools registered (25 exactly)
  • ✅ Zero Phase-1-scope Proposed ADRs (ADR-009 rejected, ADR-011 accepted)
  • ✅ docs/tech-debt-register.md with ≥10 rows (18 rows)
  • ✅ All 5 platform-spec gaps closed (Tasks 1.1 + 1.6 + 1.8)
  • ✅ CI green on main, zero drift
  • ⚠️ Bundle size 2072 KiB raw / 403 KiB gzip — 24 KiB over soft 2 MB target, not gate-enforced, acceptable
  • ✅ Task 1.2 closed by this ADR

Phase 1 is complete. Phase 2 (Context Plane Scaffold) may begin immediately per V5-PHASE-2-CONTEXT-PLANE.md.

References