Workflow (and other heavy tools) should be lazy-loaded — inline docs burn ~14.5k tokens every session

Summary

The Workflow tool description embeds extensive inline documentation — scripting API reference, multiple code examples, pattern guides, and engineering constraints. This loads into the context window of every session, even sessions that never touch Workflow.

Observed behavior

Running /context shows:

System tools: 14.5k tokens (7.3%)

A significant portion of this comes from tool descriptions that double as documentation (especially Workflow, but also Agent, Bash, etc.).

Expected behavior

Claude Code already has a deferred/lazy-load mechanism for tools like TaskCreate, CronCreate, WebFetch, etc. — they appear as names only until ToolSearch fetches their full schema. The same approach should apply to Workflow and other doc-heavy tools.

For a typical coding session, Workflow is never invoked. Its full description (examples, phase patterns, budget API, resume semantics, quality patterns, …) should only be loaded when the model actually needs it.

Suggestion

• Move Workflow (and possibly Agent) to the deferred pool, loaded on demand via ToolSearch
• Or strip the inline examples/patterns from the always-loaded description and move them to a separate fetchable reference

Impact

Every session pays a fixed ~14.5k token tax regardless of what features are used. For users on limited-context plans or long conversations, this compounds quickly. The deferred mechanism proves the infra is already there — this is a policy/configuration gap, not an architectural limitation.