perf(core): the built-in tool descriptions and schemas are the largest block of non-conversation context, and have no size tracking #12054

Part of #12028.

The gap

#12028 itemises non-conversation context for one session on a 1M-context model. Built-in tools are the largest category by a wide margin:

Every other category already has a tracking issue with a mechanism attached:

• system prompt → feat(core): assemble the tool-policy and example sections of the system prompt from the resident tool set #12032 (assemble the tool-policy and example sections from the resident tool set)
• context files → feat(extensions): an extension's context file is unconditionally resident, with no path gating, budget, or attribution #12030 (path gating, per-extension budget, attribution)
• deferral never engaging on large windows → Percentage-of-context-window budgets scale the wrong way: ToolSearch preload never engages, and the always-on context warning never fires, on large windows #12029
• a disabled tool's schema still being sent → tools.disabled removes zoom_image from the registry but its schema is still sent to the model #11814
• the /context ruler itself → fix(cli): /context category breakdown does not close (skills listing unattributed, messages derived from a cache subtraction, startup prelude uncounted) #12033

The size of the tool descriptions and schemas themselves has nothing. Not the deferral mechanism (#12029), not the leak (#11814) — what each tool costs when it is resident.

Six query angles across issues and PRs (tool schema tokens, shorten tool description, reduce tool schema tokens, slim built-in tools, tool description too long, and title-scoped variants) returned no matching item. That is absence of evidence rather than proof, but there is no tracking issue either way, which is the actionable part.

Where the mass is

From #12028's per-tool table, the top of the block:

workflow 3,829 · agent 3,613 · run_shell_command 1,495 · cron_create 1,103 · report_findings 1,016 · record_artifact 842 · update_goal 783 · ask_user_question 751 · web_fetch 693 · edit 612 · exit_plan_mode 592 · read_file 585 · web_search 499 · send_message 498

The two largest alone are 7,442 tokens — 34.7% of the block, 15.9% of all non-conversation context. Both are description-heavy rather than parameter-heavy: agent carries a subagent-type catalogue plus delegation policy, workflow a full authoring contract.

workflow is gated behind isWorkflowsEnabled(), which defaults to false on current main (packages/core/src/config/config.ts:9061: return this.workflowsEnabled ?? false). It appears in the sample because that session enabled it — so it is not dead weight on a default install. It is however the most expensive opt-in in the product: enabling one experimental feature costs more than run_shell_command, edit, read_file, write_file, grep_search and glob combined (4,080 for all six, per #12028).

What is actually askable

Not "make descriptions short". Three specific classes:

1. Restatement of what the schema already says. Prose repeating a parameter's name, type or enum back at the model. The schema is machine-read; the duplicate sentence costs tokens and adds nothing.
2. Worked examples embedded in descriptions. Several tools carry multi-example transcripts. feat(core): assemble the tool-policy and example sections of the system prompt from the resident tool set #12032 makes exactly this observation about # Examples in the system prompt (3,283 chars, entirely [tool_call: …]); the copies inside tool descriptions have the same shape and raise the same question — does the model need N examples or one?
3. Overlapping tools that could merge. tracking(core): non-conversation context token governance #12028 notes seven file tools total 4,080 tokens. Whether some of those are one tool with a mode parameter is a design question rather than a trimming one, and should be answered separately from (1) and (2).

What must not be trimmed

The discipline #12032 applies to prompts.ts applies here unchanged. Load-bearing text in tool descriptions includes:

• call boundaries and the dangerous-operation classes
• run_shell_command's shell-quoting rules and the "prefer dedicated tools over cat/grep/sed" policy
• the denied-tool-call rule — a denial must not be routed around via shell indirection, generated scripts, aliases, symlinks, config changes or hooks
• the "explain a mutating command before running it" requirement

These read as verbose but are behavioural constraints. Cutting them to hit a token target trades a measurable saving for an unmeasurable regression, and no test in CI would fail — the same failure mode #12032 identifies for a forked system prompt.

Why this is not a pure win

Trimming descriptions risks tool-selection recall. Any change needs a before/after on task success, not only on token count, which is why the acceptance list below carries a recall gate alongside the size gate.

Blocked on the ruler

There is currently no trustworthy instrument for the before/after. #12033 documents that /context's categories do not sum to its reported total, and that per-category estimates have never been compared against provider inputTokens. A "reduced by N tokens" claim sourced from /context today is not defensible. Either land #12033 first, or measure directly against provider usage in the PR.

Suggested acceptance

• a per-tool token table for a default install, measured against provider inputTokens rather than estimated
• a measurable reduction in the built-in tool block for a default configuration
• no regression in tool-selection recall or task success on a fixed task set
• the preserved safety / call-boundary text named explicitly in the PR, so a reviewer can check nothing behavioural was cut