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

> Discover how ClosedClaw's tiered tool functionalities Lite Medium and Full adapt to various LLM sizes. Optimize your agent configuration for peak performance and efficiency.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: deep-dive
- Published: 2026-02-25

---

**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`](https://github.com/asafelobotomy/closedclaw/blob/main/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)](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`](https://github.com/asafelobotomy/closedclaw/blob/main/src/agents/tool-tiers.ts#L98-L112) 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:

```typescript
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:**

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

```

The configuration system resolves this value through `resolveAgentConfig` in [`src/agents/agent-scope.ts`](https://github.com/asafelobotomy/closedclaw/blob/main/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)](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:

```typescript
// 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:

```typescript
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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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.