Large cumulative agent descriptions impacting performance (~16.3k tokens)

Problem

The Task tool's agent descriptions are consuming ~16.3k tokens (exceeding the 15k recommended threshold), which impacts performance on every request.

Current State

• 50+ specialized agents defined in the Task tool description
• Each agent includes verbose descriptions + 2-4 full <example> blocks
• Many agents are domain-specific and rarely used (quantum-computing, blockchain-engineer, ar-vr-developer, game-developer, iot-specialist, etc.)

Example of Verbosity

Current format for each agent:

"elite-bug-terminator": Use this agent when you need to identify, diagnose, and fix ANY bugs, errors, issues, or unexpected behaviors in code. This includes debugging runtime errors, TypeErrors, logic flaws, performance problems, race conditions, integration issues, crashes, wrong outputs, or any code not working as expected. The agent should be AUTOMATICALLY invoked whenever error messages appear, tests fail, or users report problems.

<example>
Context: The user has an elite bug-hunting agent...
user: "My function is returning undefined instead of the expected value"
assistant: "I'll immediately use the elite-bug-terminator agent..."
<commentary>
Since the user is reporting unexpected behavior...
</commentary>
</example>

[3 more examples...]

Suggested Improvements

Option A: Trim Descriptions (Quick Win)

Reduce to single-line descriptions without examples:

"elite-bug-terminator": Debug and fix bugs, errors, crashes, and unexpected behavior
"blockchain-engineer": Smart contracts, DApps, Web3, DeFi development
"quantum-computing": Quantum algorithms and quantum computing applications

Option B: Lazy Loading (Better UX)

Only load full agent descriptions when the Task tool is actually invoked, not on every request.

Option C: Configurable Agents (Most Flexible)

Allow users to enable/disable specific agents in settings.json:

{
  "agents": {
    "enabled": ["general-purpose", "Explore", "bug-terminator", "test-commander"],
    "disabled": ["quantum-computing", "blockchain-engineer", "ar-vr-developer"]
  }
}

Impact

• Slower response times due to larger context
• Higher token usage/costs
• Reduced effective context window for actual work

Environment

• Claude Code version: 2.0.62
• Platform: macOS Darwin 24.5.0

Related

Users working on web projects don't need quantum-computing or IoT agents in every request. A leaner default with opt-in specialists would significantly improve performance.