How Tiered Tool Functionalities (Lite/Medium/Full) Adapt to Different LLM Sizes in ClosedClaw

ClosedClaw dynamically adjusts the available toolset based on LLM capabilities by filtering tools through configurable Lite, Medium, and Full tiers defined in the agent configuration.

The tiered tool functionality system in ClosedClaw solves a critical optimization problem: smaller language models struggle with large tool catalogs, while larger models can handle complex multi-step operations. By defining three distinct tiers in src/agents/tool-tiers.ts, the framework ensures that each model size receives an appropriately scoped toolbox that matches its reasoning capacity and context window limitations.

Architecture of the Tier System

The tier implementation spans configuration, runtime resolution, and filtering layers. At its core, the system treats tiers as additive allow-lists that restrict the full tool catalog before it reaches the LLM.

Tool Tier Definitions

The canonical tier definitions reside in [src/agents/tool-tiers.ts](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/tool-tiers.ts). This file exports two critical Set constants:

• LITE_TOOL_NAMES: Contains 16 essential tools including read, write, find, grep, ls, exec, web_search, and calculator
• MEDIUM_TOOL_NAMES: Expands the Lite set with coding and memory tools like edit, apply_patch, browser, memory_search, memory_store, and reflect_memory

The Full tier is represented by null in the TIER_SETS mapping, signaling the engine to skip filtering entirely and expose the complete tool catalog including custom plugins.

Runtime Filtering Logic

The filterToolsByTier function performs the actual restriction. It accepts an array of AnyAgentTool objects and a tier string, then returns only tools whose names exist in the corresponding allow-list:

export function filterToolsByTier(
  tools: AnyAgentTool[],
  tier: ToolTier
): AnyAgentTool[] {
  const allowSet = TIER_SETS[tier];
  if (!allowSet) return tools; // "full" tier returns unfiltered
  return tools.filter((t) => allowSet.has(t.name));
}

Configuring Tool Tiers for Different LLM Sizes

Users specify the desired tier in the agent configuration using the agents.list.<agent>.tools.tier key. The framework supports three values: "lite", "medium", or "full".

Configuration example:

agents:
  list:
    myAssistant:
      tools:
        tier: lite  # Options: lite, medium, full

The configuration system resolves this value through resolveAgentConfig in src/agents/agent-scope.ts, which looks up the agent definition and extracts the tier setting. If omitted, the system defaults to "full", granting access to all available tools.

Runtime Implementation in the Execution Pipeline

The filtering occurs during the embedded run flow within [src/agents/pi-embedded-runner/run/attempt.ts](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/pi-embedded-runner/run/attempt.ts#L82-L92). The runEmbeddedAttempt function extracts the agent ID from the session key, resolves the configuration, and conditionally applies tier filtering before constructing the system prompt:

// Resolve tier from session key pattern "session:<agentId>"
const agentIdForTier = params.sessionKey?.split(":")[1];
const tierConfig =
  agentIdForTier && params.config
    ? resolveAgentConfig(params.config, agentIdForTier)?.tools?.tier
    : undefined;

// Apply filtering if tier is specified and not "full"
if (tierConfig && tierConfig !== "full") {
  const beforeCount = tools.length;
  tools = filterToolsByTier(tools, tierConfig);
  log.debug(
    `tier: filtered tools from ${beforeCount} to ${tools.length} (tier=${tierConfig})`
  );
}

The filtered tool array then feeds into the system prompt builder, ensuring the LLM only sees tools appropriate for its tier.

Tool Capabilities by Tier

Each tier optimizes for specific model characteristics and use cases:

Lite Tier

• Target: Small models (e.g., Qwen3-8B) with limited context windows
• Toolset: 16 deterministic, low-latency tools focused on file operations, system commands, and basic web search
• Safety: Restricts complex operations that require extensive reasoning

Medium Tier

• Target: Mid-size models capable of coding assistance and state management
• Toolset: All Lite tools plus 16 additional tools including apply_patch, browser, memory_recall, canvas, and ocr_image
• Use case: Development workflows requiring memory persistence and browser automation

Full Tier

• Target: Large frontier models with extensive context windows
• Toolset: Complete catalog including all built-in tools, custom plugins, and experimental features
• Behavior: Bypasses filterToolsByTier entirely, passing the unmodified tool array

Practical Code Implementation

To manually apply tier filtering when building custom agent runners:

import { filterToolsByTier, ToolTier } from "./agents/tool-tiers.js";
import { createClosedClawCodingTools } from "./agents/pi-tools.js";

// Initialize the complete toolbox from the factory
let allTools = createClosedClawCodingTools({
  contextWindow: 4096,
  enablePlugins: true
});

// Restrict to Medium tier for a mid-size model
const tier: ToolTier = "medium";
const allowedTools = filterToolsByTier(allTools, tier);

console.log(
  `Filtered ${allTools.length} tools down to ${allowedTools.length} for tier: ${tier}`
);
// Output includes: read, write, edit, apply_patch, memory_search, etc.

GTK GUI Lite Mode Integration

The desktop UI in extensions/gtk-gui/src/monitor.ts implements a parallel Lite mode that operates independently of agent configuration. When shouldUseLiteMode returns true—typically due to resource constraints or user preference—the interface substitutes the standard tool pipeline with a lightweight "GTK lite-tools" variant.

Despite this UI-level override, the system still respects tier boundaries. The UI queries areLiteModeToolsEnabled and ensures that even in forced Lite mode, no tool outside the Lite tier allow-list becomes available to the underlying model.

Summary

• Configuration: Set agents.list.<agent>.tools.tier to "lite", "medium", or "full" in your YAML config
• Source of truth: Tier definitions live in src/agents/tool-tiers.ts as LITE_TOOL_NAMES and MEDIUM_TOOL_NAMES Sets
• Runtime filtering: filterToolsByTier executes in runEmbeddedAttempt before system prompt generation
• Additive design: Medium inherits Lite tools; Full disables filtering entirely
• UI integration: The GTK client can force Lite mode while maintaining tier safety guarantees

Frequently Asked Questions

How does ClosedClaw determine which tier to use for a specific agent?

The framework extracts the agent ID from the session key using the pattern session:<agentId>, then calls resolveAgentConfig to look up the agent definition in the global configuration. It retrieves the tools.tier value from that specific agent's configuration block. If no tier is specified, the system defaults to "full", providing unrestricted tool access.

Can I mix tools from different tiers or create custom tiers?

The current implementation supports only the three predefined tiers. However, since filterToolsByTier accepts any ToolTier key present in TIER_SETS, you could extend the tool-tiers.ts file to include additional custom sets following the same pattern as LITE_TOOL_NAMES and MEDIUM_TOOL_NAMES.

What happens if I configure the Lite tier but the model supports Full?

The tier configuration always takes precedence over automatic model detection. If you explicitly set tier: lite in the agent configuration, ClosedClaw will filter the toolset to only Lite-capable tools regardless of the underlying model's capabilities. To enable the full toolset, either remove the tier key or set it to "full".

Does the tier system affect custom plugins installed in ClosedClaw?

Yes. When using the Full tier, custom plugins included in the allTools array pass through unfiltered. However, if you configure Lite or Medium tiers, the filterToolsByTier function checks plugin tool names against the allow-lists. Custom tools with names not present in LITE_TOOL_NAMES or MEDIUM_TOOL_NAMES will be removed from the active toolset during runtime initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}