Tool System

TinyElf's tool system is managed by ToolRegistry for tool registration and execution, and TinyElfToolRegistryBuilder is responsible for building the complete tool set when a session starts. Each tool implements the ITool interface.

Tool Registration Flow

graph TB
    Builder["TinyElfToolRegistryBuilder<br/>buildToolRegistry()"] --> Reg["ToolRegistry"]

    Builder -->|"1. FileSystem"| FS["createFileSystemTools()<br/>Read, Write, Edit, ListDir, Glob, Grep"]
    Builder -->|"2. Shell"| Shell["ShellTool<br/>Bash"]
    Builder -->|"3. Web Search"| WS["setupWebSearch()<br/>WebSearch / NativeSearch"]
    Builder -->|"4. Web Fetch"| WF["createWebFetchTool()<br/>WebFetch + summarizer"]
    Builder -->|"5. Skills"| SK["SkillsTool + ReadSkillTool<br/>list_skills, read_skill"]
    Builder -->|"6. SkillHub"| SH["SkillHubSearchTool + InstallTool<br/>skillhub_search, skillhub_install"]
    Builder -->|"7. Sub-Agent"| SA["SpawnTool<br/>spawn_agent"]
    Builder -->|"8. Sub-Agent Query"| SAQ["SubagentListTool + StatusTool"]
    Builder -->|"9. Slash Command"| CMD["SlashCommandTool<br/>slash_command"]
    Builder -->|"10. MCP"| MCP["loadMcpTools() + loadDirectMcpTools()<br/>mcp__*"]
    Builder -->|"11. Session"| SS["SessionsSpawn/List/Send/History"]
    Builder -->|"12. Control"| Ctrl["NotifyTool + SessionsYieldTool"]

    FS --> Reg
    Shell --> Reg
    WS --> Reg
    WF --> Reg
    SK --> Reg
    SH --> Reg
    SA --> Reg
    SAQ --> Reg
    CMD --> Reg
    MCP --> Reg
    SS --> Reg
    Ctrl --> Reg

ITool Interface

interface ITool {
  readonly name: string;            // unique tool name (function_calling use)
  readonly description: string;     // LLM-readable description
  readonly parameters: JsonSchema;  // JSON Schema parameter definition
  execute(params: Record<string, unknown>): Promise<string>;
}

ToolRegistry

class ToolRegistry {
  register(tool: ITool): void;
  registerAll(tools: ITool[]): void;
  unregister(name: string): boolean;
  get(name: string): ITool | undefined;
  has(name: string): boolean;
  getAll(): ITool[];
  getNames(): string[];
  getDefinitions(): ToolDefinition[];    // OpenAI function_calling format
  createFiltered(allowedNames: string[]): ToolRegistry;
  execute(toolCallId, toolName, params): Promise<ToolCallResult>;
}

Execution Flow

1. Look up tool → return error if not found (list available tools)
2. Parameter type conversion → handle common LLM type errors (string → number etc.)
3. Required parameter validation → return error if missing
4. Call tool.execute(params)
5. Output truncation → truncate over maxChars (default 50KB) and add (truncated) mark
6. Error output append hint → [Analyze the error above and try a different approach.]

Tool Filtering

createFiltered() creates a new ToolRegistry instance containing only whitelisted tools. Used for:

• plan mode limited to read-only tools
• Agent config allowedTools field
• Slash command allowed-tools metadata

Complete Tool Table

FileSystem Tools

Tool	Class	Sensitivity	Parameters	Description
Read	ReadFileTool	Safe	path, offset?, limit?	Read file content, supports partial read
Write	WriteFileTool	Sensitive	path, content	Write file (create or overwrite)
Edit	EditFileTool	Sensitive	path, old_string, new_string, replace_all?	Precise string replacement
ListDir	ListDirTool	Safe	path	List directory contents
Glob	GlobTool	Safe	pattern, path?	File name pattern matching
Grep	GrepTool	Safe	pattern, path?, include?	File content search

FileSystem tool features:

• Path sandbox: all paths resolved relative to workspace root
• restrictToWorkspace config controls whether workspace-outside access allowed
• Read auto-truncates large files (>128KB), >10MB requires offset/limit

Shell Tool

Tool	Class	Sensitivity	Parameters	Description
Bash	ShellTool	Sensitive	command	Execute shell command

Shell tool security features:

• Command blacklist (critical deny patterns): rm -rf /, format, mkfs, diskpart etc.
• High-risk command warnings: sudo, curl | sh, permission changes
• Workspace-outside path detection
• Output limit: 100KB
• Timeout: default 2 minutes, configurable via execTimeout

Web Tools

Tool	Class	Sensitivity	Parameters	Description
WebSearch	WebSearchServiceTool	Safe	query, count?	Web search
WebFetch	WebFetchTool	Safe	url, prompt?, raw?	Fetch web content

WebFetch features:

• Use Readability to extract article body
• HTML → Markdown conversion (Turndown)
• Content over 4KB auto-summarized using background model
• 30-second timeout, max 5MB response

Web search three-tier fallback:

1. Native search (Anthropic/OpenAI/Gemini/xAI built-in)
2. WebSearchService (Tavily/Jina/Searxng)
3. Unavailable

Sub-Agent Tools

Tool	Class	Sensitivity	Parameters	Description
spawn_agent	SpawnTool	Sensitive	prompt, agent?, model?, background?, maxIterations?, permissionMode?, tools?	Launch sub-Agent
subagent_list	SubagentListTool	Safe	None	List active sub-Agents
subagent_status	SubagentStatusTool	Safe	runId	Query sub-Agent status

Session Tools

Tool	Class	Sensitivity	Parameters	Description
SessionsSpawn	SessionsSpawnTool	Sensitive	prompt, agentId?, title?	Create new session
SessionsList	SessionsListTool	Safe	limit?, offset?	List sessions
SessionsSend	SessionsSendTool	Sensitive	sessionId, message	Send message to session
SessionsHistory	SessionsHistoryTool	Safe	sessionId, limit?	View session history
SessionsYield	SessionsYieldTool	Safe	message	End Agent loop and return message

Skills Tools

Tool	Class	Sensitivity	Parameters	Description
list_skills	SkillsTool	Safe	None	List all available skills
read_skill	ReadSkillTool	Safe	name	Read skill content
skillhub_search	SkillHubSearchTool	Safe	query	Search community skills
skillhub_install	SkillHubInstallTool	Safe	skillId	Install community skill

MCP Tools

Tool	Class	Sensitivity	Parameters	Description
mcp__<server>__<tool>	Dynamically generated	Sensitive	Defined by MCP server	External MCP tools

MCP tools are loaded via three approaches:

1. User MCP (mcpServerIds) — connect user-configured stdio/http/sse servers in Settings → MCP via McpService
2. Built-in MCP (auto-assembled via McpProviderRegistry) — all built-in MCP handlers in-process, SDK wrapped via createSdkMcpServer, TinyElf registers as ITool, CLI accesses via central BuiltinMcpHttpServer HTTP bridge. Each agent's visible MCP determined by Provider's isEligible(ctx) (no longer walks builtinMcpServers field in Agent config — field deleted in cleanup-legacy-mcp (2026-05-19))
3. Direct MCP (directMcpServers) — pre-parsed stdio MCP declared in Agent config (user scenarios like calling local Python tools)

Control Tools

Tool	Class	Sensitivity	Parameters	Description
Notify	NotifyTool	Safe	title, body?	Send desktop notification
slash_command	SlashCommandTool	Safe	command, args?	Execute Slash command

Tool Sensitivity Classification

private static readonly SAFE_TOOLS = new Set([
  'Read', 'ListDir', 'Glob', 'Grep',
  'WebSearch', 'WebFetch',
  'list_skills', 'read_skill',
  'Notify', 'SessionsYield', 'SessionsHistory',
]);

Classification rules:

• In SAFE_TOOLS set → never requires confirmation
• In acceptEdits mode, Write and Edit also don't require confirmation
• All other tools (including MCP tools) → require confirmation

Tool Inheritance

Sub-Agents can inherit some tools from parent Agent:

const inheritableToolNames = new Set([
  'list_skills', 'read_skill', 'slash_command'
]);
// + all MCP tools starting with mcp__

Key Files

File	Path	Description
ITool interface	tinyelf/tools/ToolInterface.ts	Tool base interface
ToolRegistry	tinyelf/tools/ToolRegistry.ts	Tool registry
ToolRegistryBuilder	tinyelf/TinyElfToolRegistryBuilder.ts	Tool builder
FileSystemTools	tinyelf/tools/FileSystemTools.ts	FileSystem tools
ShellTool	tinyelf/tools/ShellTool.ts	Shell tool
WebTools	tinyelf/tools/WebTools.ts	WebFetch
WebSearchServiceTool	tinyelf/tools/WebSearchServiceTool.ts	WebSearch
SpawnTool	tinyelf/tools/SpawnTool.ts	Sub-Agent tool
SessionTools	tinyelf/tools/SessionTools.ts	Session management tools
SkillsTool	tinyelf/tools/SkillsTool.ts	Skills tool
SkillHubTools	tinyelf/tools/SkillHubTools.ts	SkillHub tools
McpToolAdapter	tinyelf/tools/McpToolAdapter.ts	MCP tool adaptation
NotifyTool	tinyelf/tools/NotifyTool.ts	Notify tool
YieldTool	tinyelf/tools/YieldTool.ts	Loop termination tool
SubagentTools	tinyelf/tools/SubagentTools.ts	Sub-Agent query tools
SlashCommandTool	tinyelf/tools/SlashCommandTool.ts	Slash command

All paths relative to packages/desktop/app/main/services/agent-core/engine/.

Extension Points

• New tool: implement ITool interface → register in TinyElfToolRegistryBuilder
• Modify sensitivity: add/remove in TinyElfAgentLoop.SAFE_TOOLS set
• Custom tool inheritance: modify inheritableToolNames set
• MCP tool loading: adapt new MCP transport via McpToolAdapter

Related Modules

Module	Path	Relationship
TinyElfAgentLoop	tinyelf/TinyElfAgentLoop.ts	Tool execution caller
ExecutionFirewall	platform/security/ExecutionFirewall.ts	FileSystem tool path check
McpService	capabilities/tools/mcp-users/McpService.ts	MCP tool source
SkillsLoader	tinyelf/skills/SkillsLoader.ts	Skills tool dependency
SubagentManager	tinyelf/tools/SpawnTool.ts	spawn_agent dependency