Tools Overview

Codebolt Tools are custom utilities that extend the capabilities of AI agents by providing specialized functionality. Built on the Model Context Protocol (MCP) standard, these tools allow you to integrate external services, automate tasks, and create domain-specific capabilities that agents can use when solving problems.

MCP Compatibility

Codebolt Tools are built on the Model Context Protocol (MCP) standard, ensuring full backward compatibility. This means that any existing MCP implementation can be used as a Codebolt tool without modification. This compatibility allows developers to:

Use existing MCP tools directly in Codebolt
Share tools between different MCP-compatible platforms
Leverage the broader MCP ecosystem
Maintain consistency with MCP standards and best practices

What are Codebolt Tools?

Codebolt Tools are MCP-compatible utilities that:

Extend Agent Capabilities: Provide specialized functions that agents can call
Follow MCP Standard: Implement the Model Context Protocol for seamless integration
Are Reusable: Can be shared across multiple agents and projects
Support Configuration: Accept parameters for customization
Work Everywhere: Can be used in Codebolt Application or via CLI
Are Shareable: Can be published to and used from the tool registry

Why Use Tools?

Tools are essential for:

External Integrations: Connect to APIs, databases, and external services
File Operations: Read, write, and manipulate files safely
Data Processing: Transform and analyze data
Automation: Automate repetitive development tasks
Domain-Specific Logic: Implement business rules and specialized workflows

Tool Architecture

Core Components

Every Codebolt tool consists of:

Configuration File (codebolttool.yaml): Defines tool metadata and parameters
Implementation (index.js): Contains the tool's functionality
Documentation (README.md): Explains how to use the tool
Dependencies (package.json): Lists required Node.js packages

Tool Structure

my-tool/
├── codebolttool.yaml     # Tool configuration
├── package.json          # Node.js dependencies
├── index.js             # Main implementation
├── README.md            # Documentation
└── src/                 # Additional source files (optional)
    ├── handlers/        # Function handlers
    └── utils/           # Utility functions

How Tools Work

1. Tool Definition

Tools are defined in codebolttool.yaml. This allows for identification of tools in registry and codebolt application.

name: "File Manager"
description: "Safely manages file operations"
version: "1.0.0"
uniqueName: "file-manager-tool"

parameters:
  rootPath:
    type: "string"
    description: "Root directory for operations"
    default: "./"
  
  allowedExtensions:
    type: "array"
    description: "Allowed file extensions"
    default: [".js", ".ts", ".json", ".md"]

2. Tool Implementation

The tool implementation is a javascript class that extends the ToolBox class. The ToolBox class is a MCP-compatible class that provides the tool functionality. This is similar to FastMCP library, although you can use any MCP-compatible library.

// index.js
const { ToolBox } = require('@codebolt/toolbox');

class FileManagerTool {
  constructor(config) {
    this.config = config;
    this.toolbox = new ToolBox({
      name: 'File Manager',
      version: '1.0.0'
    });
    
    this.setupTools();
  }

  setupTools() {
    this.toolbox.addTool({
      name: 'list_files',
      description: 'List files in a directory',
      parameters: {
        path: { type: 'string', description: 'Directory path' }
      },
      execute: this.listFiles.bind(this)
    });
  }

  async listFiles(args, context) {
    const { path = './' } = args;
    // Implementation here
    return { files: [] };
  }

  async start() {
    await this.toolbox.start();
  }
}

module.exports = FileManagerTool;

3. Tool Usage

Agents can use tools to perform specific tasks:

// In an agent
const files = await this.tools.fileManager.listFiles({
  path: './src/components'
});

Creating Tools

You can create tools in two ways:

Option 1: Using Codebolt Application

Open Codebolt Application
Navigate to Tools section
Click "Create New Tool"
Fill in tool details and configuration
Implement tool functions in the editor
Test and save your tool

Option 2: Using CLI

# Create a new tool
codebolt-cli createtool

# Or create with options
codebolt-cli createtool \
  --name "My Tool" \
  --id "my-tool" \
  --description "Tool description"

Tool Configuration

Basic Configuration

The codebolttool.yaml file defines your tool:

# Required fields
name: "Weather API Tool"
description: "Fetches weather information"
version: "1.0.0"
uniqueName: "weather-api-tool"

# Optional metadata
author: "Your Name"
category: "API"
tags: ["weather", "api", "data"]

# Tool parameters
parameters:
  apiKey:
    type: "string"
    description: "Weather API key"
    required: true
    sensitive: true
  
  units:
    type: "string"
    description: "Temperature units"
    default: "celsius"
    enum: ["celsius", "fahrenheit"]
  
  timeout:
    type: "number"
    description: "Request timeout in seconds"
    default: 30
    minimum: 1
    maximum: 300

Parameter Types

Supported parameter types:

string: Text values
number: Numeric values
boolean: True/false values
array: Lists of values
object: Complex data structures

Parameter Properties

type: Data type (required)
description: Human-readable description
required: Whether parameter is mandatory
default: Default value if not provided
sensitive: Hide value in logs (for API keys)
enum: List of allowed values
minimum/maximum: Range for numbers

Tool Implementation Patterns

Simple Function Tool

class CalculatorTool {
  setupTools() {
    this.toolbox.addTool({
      name: 'add',
      description: 'Add two numbers',
      parameters: {
        a: { type: 'number', required: true },
        b: { type: 'number', required: true }
      },
      execute: async (args) => {
        return { result: args.a + args.b };
      }
    });
  }
}

API Integration Tool

class WeatherTool {
  constructor(config) {
    this.apiKey = config.parameters?.apiKey;
    this.setupTools();
  }

  setupTools() {
    this.toolbox.addTool({
      name: 'get_weather',
      description: 'Get current weather',
      parameters: {
        city: { type: 'string', required: true }
      },
      execute: this.getWeather.bind(this)
    });
  }

  async getWeather(args, context) {
    try {
      const response = await fetch(
        `https://api.weather.com/v1/current?key=${this.apiKey}&q=${args.city}`
      );
      const data = await response.json();
      
      context.log.info(`Fetched weather for ${args.city}`);
      
      return {
        city: args.city,
        temperature: data.current.temp_c,
        condition: data.current.condition.text
      };
    } catch (error) {
      context.log.error('Weather API error', { error: error.message });
      throw new Error(`Failed to get weather: ${error.message}`);
    }
  }
}

File Processing Tool

class FileProcessorTool {
  setupTools() {
    this.toolbox.addTool({
      name: 'process_file',
      description: 'Process a file',
      parameters: {
        filePath: { type: 'string', required: true },
        operation: { 
          type: 'string', 
          enum: ['count_lines', 'extract_functions', 'format_code']
        }
      },
      execute: this.processFile.bind(this)
    });
  }

  async processFile(args, context) {
    const { filePath, operation } = args;
    
    // Security check
    if (!this.isPathSafe(filePath)) {
      throw new Error('Invalid file path');
    }

    const fs = require('fs').promises;
    const content = await fs.readFile(filePath, 'utf8');
    
    switch (operation) {
      case 'count_lines':
        return { lines: content.split('\n').length };
      
      case 'extract_functions':
        const functions = this.extractFunctions(content);
        return { functions };
      
      case 'format_code':
        const formatted = await this.formatCode(content);
        return { formatted };
      
      default:
        throw new Error(`Unknown operation: ${operation}`);
    }
  }
}

Testing Tools

Local Testing with CLI

# Test a specific function
codebolt-cli runtool get_weather ./weather-tool/index.js

# Debug with inspector
codebolt-cli inspecttool ./weather-tool/index.js

Unit Testing

// test/weather-tool.test.js
const WeatherTool = require('../index.js');

describe('WeatherTool', () => {
  let tool;

  beforeEach(() => {
    tool = new WeatherTool({
      parameters: { apiKey: 'test-key' }
    });
  });

  test('should get weather for city', async () => {
    const result = await tool.getWeather(
      { city: 'London' },
      { log: { info: jest.fn(), error: jest.fn() } }
    );
    
    expect(result).toHaveProperty('temperature');
    expect(result.city).toBe('London');
  });
});

Publishing to Registry

# Publish your tool
codebolt-cli publishtool

# Or publish from specific directory
codebolt-cli publishtool ./my-tool

Using Tools from Registry

# List available tools
codebolt-cli listtools

# Pull tool updates
codebolt-cli pulltools

Tool Registry Features

Version Management: Track tool versions and updates
Discovery: Find tools by category and tags
Documentation: Access tool documentation and examples
Ratings: See community feedback and usage statistics

Best Practices

Security

Validate Inputs: Always validate and sanitize parameters
Limit Access: Restrict file system and network access
Handle Secrets: Use sensitive parameters for API keys
Error Handling: Don't expose sensitive information in errors

// Good: Input validation
async executeCommand(args, context) {
  if (!args.command || typeof args.command !== 'string') {
    throw new Error('Invalid command parameter');
  }
  
  // Sanitize command
  const safeCommand = args.command.replace(/[;&|`$]/g, '');
  // ... execute safely
}

Performance

Async Operations: Use async/await for I/O operations
Caching: Cache expensive operations
Timeouts: Set reasonable timeouts for external calls
Resource Cleanup: Clean up resources properly

// Good: Caching expensive operations
class DataTool {
  constructor() {
    this.cache = new Map();
  }

  async fetchData(key) {
    if (this.cache.has(key)) {
      return this.cache.get(key);
    }
    
    const data = await this.expensiveOperation(key);
    this.cache.set(key, data);
    return data;
  }
}

Documentation

Clear Descriptions: Write clear tool and parameter descriptions
Examples: Provide usage examples
Error Messages: Use helpful error messages
README: Include comprehensive README files

Common Use Cases

1. API Integration Tools

Connect to external services:

Weather APIs
Database queries
Cloud services
Third-party integrations

2. File Management Tools

Handle file operations:

Read/write files
Process documents
Generate reports
Manage directories

3. Development Tools

Automate development tasks:

Code formatting
Test execution
Build processes
Deployment scripts

4. Data Processing Tools

Transform and analyze data:

CSV processing
JSON manipulation
Data validation
Report generation

Troubleshooting

Common Issues

Tool Not Loading

Error: Tool configuration not found

Check codebolttool.yaml exists and is valid
Verify required fields are present

Parameter Validation Errors

Error: Parameter 'apiKey' is required

Check parameter definitions in configuration
Ensure required parameters are provided

MCP Protocol Errors

Error: Invalid MCP response

Ensure tool functions return proper response format
Check parameter types match definitions

Debug Mode

Enable detailed logging:

DEBUG=codebolt:tools codebolt-cli runtool function_name ./tool/index.js

Next Steps

Create Your First Tool - Step-by-step tool creation
Test Tools Locally - Testing and debugging
Publish Tools - Share your tools
CLI Tool Commands - CLI reference

What are Codebolt Tools?​

Why Use Tools?​

Tool Architecture​

Core Components​

Tool Structure​

How Tools Work​

1. Tool Definition​

2. Tool Implementation​

3. Tool Usage​

Creating Tools​

Option 1: Using Codebolt Application​

Option 2: Using CLI​

Tool Configuration​

Basic Configuration​

Parameter Types​

Parameter Properties​

Tool Implementation Patterns​

Simple Function Tool​

API Integration Tool​

File Processing Tool​

Testing Tools​

Local Testing with CLI​

Unit Testing​

Publishing and Sharing Tools​

Publishing to Registry​

Using Tools from Registry​

Tool Registry Features​

Best Practices​

Security​

Performance​

Documentation​

Common Use Cases​

1. API Integration Tools​

2. File Management Tools​

3. Development Tools​

4. Data Processing Tools​

Troubleshooting​

Common Issues​

Debug Mode​

Next Steps​