Tools Overview

Toolpack SDK includes 77 built-in tools across 10 categories. When you enable tools, the AI can automatically use them to accomplish tasks.

Enabling Tools

const toolpack = await Toolpack.init({
    provider: 'openai',
    tools: true,  // Enable all built-in tools
});

Tool Categories

Category	Tools	Description
File System	18	Read, write, search, and manage files
Execution	6	Run commands and manage processes
System	5	System info, environment, disk usage
HTTP	5	HTTP requests (GET, POST, PUT, DELETE)
Web	9	Web search (Tavily/Brave/DuckDuckGo), scraping, metadata, feeds
Coding	12	AST-aware code analysis and refactoring
Git	9	Version control operations
Diff	3	Create and apply patches
Database	7	SQL queries and database operations
Cloud	3	Deploy to cloud platforms

How Tools Work

When the AI needs to perform an action, it automatically calls the appropriate tool:

const stream = toolpack.stream({
    messages: [{ role: 'user', content: 'List all .ts files in src/' }],
    model: 'gpt-4o',
});

// The AI will:
// 1. Recognize it needs to list files
// 2. Call fs.list_dir or fs.glob
// 3. Return the results in its response

The SDK handles tool execution automatically - you just see the final response.

Tool Events

Listen to tool execution events:

const client = toolpack.getClient();

client.on('tool:progress', (event) => {
    console.log(`Tool: ${event.toolName}`);
    console.log(`Status: ${event.status}`);  // 'started' | 'completed' | 'failed'
    if (event.result) {
        console.log(`Result: ${event.result}`);
    }
});

client.on('tool:log', (event) => {
    // Full tool execution log
    console.log(`${event.name}: ${event.duration}ms`);
});

Restricting Tools

Control which tools are available using modes:

// Only allow web tools
const webOnlyMode: ModeConfig = {
    name: 'web-only',
    displayName: 'Web Only',
    description: 'Only web access',
    systemPrompt: '...',
    allowedToolCategories: ['network'],
    blockedToolCategories: [],
    allowedTools: [],
    blockedTools: [],
    blockAllTools: false,
};

const toolpack = await Toolpack.init({
    provider: 'openai',
    tools: true,
    customModes: [webOnlyMode],
    defaultMode: 'web-only',
});

Or block specific tools:

const safeMode: ModeConfig = {
    name: 'safe',
    displayName: 'Safe',
    description: 'No dangerous operations',
    systemPrompt: '...',
    allowedToolCategories: [],
    blockedToolCategories: [],
    allowedTools: [],
    blockedTools: ['exec.run', 'exec.run_shell', 'fs.delete_file', 'fs.delete_dir'],
    blockAllTools: false,
};

Tool Configuration

Configure tool behavior in toolpack.config.json:

{
    "tools": {
        "enabled": true,
        "autoExecute": true,
        "maxToolRounds": 10
    }
}

See Configuration for all options.