[FEATURE] Tool definition opt-out or lazy loading

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I observed back to back context compact this morning. After some analysis observed that Artifact tool overhead - 88KB definition loaded every turn, never used in my project. Claude cli suggest that I can't control this from my side, but it's the biggest fixed cost and is platform level decision by Claude team. Here is research done using Claude-cli. Note app name and pr number is fake to ensure privacy.
Claude Analysis :
Root cause: compaction thrashing, not one bad tool

Not a single oversized output. It was a cascade:

┌───────────────────────────────────┬────────────────────────────────┬───────────────────────────────┐
│ Factor │ Size │ Impact │
├───────────────────────────────────┼────────────────────────────────┼───────────────────────────────┤
│ Tool definitions (fixed overhead) │ ~196KB/turn │ Artifact tool alone = 88KB │
├───────────────────────────────────┼────────────────────────────────┼───────────────────────────────┤
│ Continuation summary growth │ 5KB, 9KB, 13KB, 15KB, 17KB... │ Each compact leaves less room │
├───────────────────────────────────┼────────────────────────────────┼───────────────────────────────┤
│ Re-reads after compaction │ Same files read 3-4 times each │ Fills budget immediately │
└───────────────────────────────────┴────────────────────────────────┴───────────────────────────────┘

The cycle:

1. Compact fires, summary saved (~15KB)
2. Post-compact, assistant re-reads files to rebuild context
3. app1.py (3.4KB), app2.py (3.6KB), app3 (4.3KB) read again
4. Budget exhausted, compact fires again
5. Summary grows, budget shrinks

Biggest single reads were:

• Github Issue body: 39KB (line 43)
• app1.py: 24KB first read, then 3.4KB sections on re-reads
• Plan file: 19KB (line 569, post-compact #7, worst timing)

Aggravating factors:

• 3 Explore agents + 1 Plan agent spawned, Plan agent "lost to compaction" (line 435), needed re-reading
• 8 compactions in ~1 hour (15:32-16:31 UTC)
• Session self-diagnosed at line 573: "Autocompact is thrashing"

Fix options

1. Cap reads with limit/offset - read only needed sections, not full files
2. Graph tools first (per CLAUDE.md) - semantic_search_nodes / query_graph instead of reading entire files
3. Smaller plan files - the 19KB plan was death post-compact; keep plans under 5KB
4. No re-reading post-compact - trust the continuation summary, only read new sections needed
5. Artifact tool overhead - 88KB definition loaded every turn, never used in this project. Can't control this from user side, but it's the biggest fixed cost

Options 1-4 are actionable as feedback memories. Want me to save them?

✻ Crunched for 5m 30s · done 3:02 PM

❯ save 1 to 4 . what about 5th one ? why cant this be handled ?

Saving memories 1-4 now.

Listed 1 directory, wrote 4 memories

Now update the index.

Recalled 1 memory, wrote 1 memory

4 memories saved. Now about #5:

Why the Artifact tool can't be fixed from our side

The 88KB Artifact tool definition is injected by the Claude Code runtime into every turn's system prompt. It's not configurable:

• No setting to disable individual tool definitions
• No hook intercepts the system prompt assembly
• Even if you never use Artifacts, the definition still ships every turn
• It's ~45% of the total tool definition payload (88KB of ~196KB)

This is a platform-level decision by Claude Code. The tool definitions are baked into the client binary, not user-configurable YAML or JSON you could edit.

What would help but doesn't exist yet:

• A disabled_tools setting in .claude/settings.json that suppresses tool definitions (not just permissions)
• Lazy-loading tool schemas: send tool names only, fetch full schema when the model wants to call one
• Your feedback_no_artifacts_docs_md.md memory already tells me not to use Artifacts, but the 88KB definition still loads

What you could do:

• File a feature request at github.com/anthropics/claude-code/issues asking for tool definition opt-out or lazy loading
• The memory No Artifacts; docs are .md is already there, but it only prevents usage, not the 88KB payload

Bottom line: options 1-4 are mitigations we control. Option 5 needs a Claude Code product change. The 88KB tax is real but we can't remove it — we work around it by keeping everything else lean.

Proposed Solution

issue.rtf

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_