v0.7.0 — token-burn: Shrink MCP tool-schema surface via grouped/composite tools + lazy-loading

Problem

The trajectory-server registers 61 MCP tools (verified by grep -c "name: '[a-z_]+'," mcp/trajectory-server/src/tools/*.ts), spread across 19 tool files. Even with CC's deferred-tool mechanism (names listed, full JSONSchema fetched on demand via ToolSearch), 61 deferred-tool name+description entries enter every agent's tool index.

For agents whose tools: allowlist includes the namespace prefix mcp__plugin_tmb_trajectory-server (which is every TMB agent — bro/swe/pr-reviewer/architect/cto/ceo/pm), all 61 tool names + brief descriptions land in context per turn.

A typical bro planning turn calls 5–10 distinct tools (e.g. task_create_batch, audit_log, discussion_append, issue_create, branch_id_propose, validation_record via subagent, issue_get_with_discussions, task_first_actionable), forcing fetch of each schema on demand.

Evidence (verified)

  • Tool count per file:
    • agents.ts:2, audit.ts:2, branch_report_md.ts:1, commands.ts:2, composites.ts:3, config.ts:3, discussions.ts:3, file-registry.ts:5, issues.ts:8, onboard.ts:4, pr_comments.ts:2, reports.ts:2, roundtable.ts:5, rules.ts:4, scan.ts:3, skills.ts:5, stats.ts:1, tasks.ts:4, validation.ts:2 = 61 total
  • Composites already exist (mcp/trajectory-server/src/tools/composites.ts): branch_id_propose, task_retry_batch, bro_atomic_close. These collapse multi-call recipes into single transactions. Original description missed this.
  • Every agent's tools: field uses mcp__plugin_tmb_trajectory-server (namespace, not individual tools) — so each agent inherits all 61.

Plan

  1. Extend the composite pattern that composites.ts already established. Candidate targets, in order of multi-call leverage:
    • Roundtable lifecycle: roundtable_create + roundtable_vote * N + roundtable_close + roundtable_finalize_decisions + roundtable_summarize (5 tools) → one roundtable_op({op, ...}) composite or a 2-step roundtable_init + roundtable_close_with_decisions.
    • File-registry batch ops: file_registry_upsert, file_registry_bulk_upsert, file_registry_update_summaries, file_registry_delete, file_registry_verify (5 tools) → could collapse to file_registry_op for read/write parity.
    • Skill lifecycle: skill_register + skill_record_invocation + skill_record_outcome + skill_promote (4 tools) → skill_op composite.
  2. Per-agent tool allowlist — instead of every agent allowing the full namespace, generate per-agent allowlists that only include the tools that agent actually needs (bro needs ~25; consultants need ~10 read-only; SWE needs ~8; pr-reviewer needs ~5).
  3. Shrink individual schemas — audit verbose description: text on rarely-touched params (e.g. roundtable_finalize_decisions.disagreements_resolved_by_human_choice and similar long descriptions). Move long prose to docs/REFERENCE.md and keep schema descriptions terse.
  4. Document the deferred-tool index cost so contributors understand each new tool name+description costs every-turn tokens for every agent that allows the namespace.

Acceptance criteria

  • Tool count drops by at least 30% (61 → ≤42) via at least 2 new composites + retired single-purpose tools.
  • Per-agent allowlists shipped: bro, swe, pr-reviewer, consultants each enumerate the specific tools they need (not the namespace).
  • L2 tests cover each new composite — each op of the composite validated independently.
  • L4 dogfood confirms no functional regression.
  • New benchmark: tests/benchmarks/tool-schema-bytes.sh measures total schema bytes per agent class; baseline + post-fix recorded.

Out of scope

  • Removing JSONSchema requirement entirely (MCP protocol concern).
  • Per-call schema caching at the model layer.

Note on source

Previous description claimed composites didn't exist and proposed introducing them. composites.ts was already present with 3 composites — verified by reading the file. The plan is now framed as "extend the established pattern" not "introduce it." Tool count was verified empirically (61, not 60+ as estimated).

Edited by Zax Shen