Tools API

The Tools API provides information about the available tools that AI agents can use during task execution. These tools enable agents to interact with the file system, execute commands, manage Git repositories, and perform various development tasks.

Overview

Dispersl agents have access to a comprehensive set of tools that enable them to:

• File Operations: Read, write, and manipulate files and directories
• Command Execution: Run CLI commands and scripts
• Git Operations: Manage version control workflows
• Development Tasks: Perform code analysis, testing, and deployment
• Integration: Connect with external services and APIs

Available Tools by Agent

Code Agent Tools

The Code Agent has access to tools for code generation, file manipulation, and development tasks.

File System Tools

list_files

• Description: List files and directories in a specified path
• Parameters:
  • path (string): Directory path to list
  • recursive (boolean): Whether to list recursively
• Usage: Explore project structure and locate files

read_file

• Description: Read the contents of a file
• Parameters:
  • path (string): File path to read
  • encoding (string): File encoding (default: utf-8)
• Usage: Analyze existing code and configuration files

write_to_file

• Description: Create a new file with specified content
• Parameters:
  • path (string): File path to create
  • content (string): File content
  • mode (string): File permissions (default: 644)
• Usage: Generate new code files, configurations, and documentation

edit_file

• Description: Modify existing files with precise edits
• Parameters:
  • path (string): File path to edit
  • old_content (string): Content to replace
  • new_content (string): Replacement content
• Usage: Update existing code, fix bugs, and refactor

Command Execution Tools

execute_command

• Description: Execute shell commands and scripts
• Parameters:
  • command (string): Command to execute
  • working_directory (string): Directory to run command in
  • timeout (number): Command timeout in seconds
• Usage: Run build scripts, install dependencies, start services

Test Agent Tools

The Test Agent specializes in testing workflows with dedicated testing tools.

Test Framework Tools

detect_test_frameworks

• Description: Scan project for testing frameworks and configurations
• Parameters:
  • path (string): Project root path
• Usage: Identify existing test setup and conventions

write_test_file

• Description: Generate test files with appropriate structure
• Parameters:
  • path (string): Test file path
  • test_content (string): Test code content
  • framework (string): Testing framework (jest, mocha, pytest, etc.)
• Usage: Create unit tests, integration tests, and test suites

run_tests

• Description: Execute test suites and return results
• Parameters:
  • test_path (string): Path to tests or specific test file
  • framework (string): Testing framework to use
  • options (object): Additional test runner options
• Usage: Validate code functionality and generate test reports

Git Agent Tools

The Git Agent manages version control operations with specialized Git tools.

Repository Management

setup_branch_environment

• Description: Initialize and configure new Git branches
• Parameters:
  • branch_name (string): Name of the new branch
  • base_branch (string): Base branch to branch from
• Usage: Create feature branches and prepare development environment

execute_git_command

• Description: Execute Git commands with proper error handling
• Parameters:
  • command (string): Git command to execute
  • repository_path (string): Repository path
• Usage: Perform any Git operation with full command flexibility

git_status

• Description: Get current repository status and changes
• Parameters:
  • repository_path (string): Repository path
• Usage: Check working directory status and staged changes

git_diff

• Description: View differences between commits, branches, or working directory
• Parameters:
  • repository_path (string): Repository path
  • target (string): Comparison target (commit, branch, etc.)
• Usage: Review changes before committing or merging

git_add

• Description: Stage files for commit
• Parameters:
  • repository_path (string): Repository path
  • files (array): List of files to stage
• Usage: Prepare changes for commit

git_branch

• Description: Manage Git branches (create, delete, list)
• Parameters:
  • repository_path (string): Repository path
  • action (string): Branch action (create, delete, list)
  • branch_name (string): Branch name for create/delete actions
• Usage: Branch management and workflow organization

git_log

• Description: View commit history and logs
• Parameters:
  • repository_path (string): Repository path
  • options (object): Log formatting and filtering options
• Usage: Review project history and track changes

git_repo_info

• Description: Get repository metadata and configuration
• Parameters:
  • repository_path (string): Repository path
• Usage: Understand repository structure and settings

edit_git_infra_file

• Description: Modify Git infrastructure files (CI/CD configs, hooks)
• Parameters:
  • file_path (string): Infrastructure file path
  • content (string): New file content
• Usage: Update CI/CD pipelines, Git hooks, and automation

Documentation Agent Tools

The Documentation Agent uses specialized tools for generating and managing documentation.

Documentation Generation

analyze_codebase

• Description: Analyze code structure and generate documentation insights
• Parameters:
  • repository_path (string): Repository path to analyze
  • include_patterns (array): File patterns to include
  • exclude_patterns (array): File patterns to exclude
• Usage: Understand codebase structure for documentation generation

generate_api_docs

• Description: Generate API documentation from code annotations
• Parameters:
  • source_path (string): Source code path
  • output_format (string): Documentation format (markdown, html, json)
• Usage: Create API reference documentation

create_readme

• Description: Generate comprehensive README files
• Parameters:
  • project_path (string): Project root path
  • template (string): README template to use
• Usage: Create project documentation and setup instructions

Tool Usage Examples

File Operations

{
  "tool": "write_to_file",
  "parameters": {
    "path": "/workspace/src/api/auth.js",
    "content": "const express = require('express');\nconst router = express.Router();\n\n// Authentication routes\nrouter.post('/login', (req, res) => {\n  // Login logic\n});\n\nmodule.exports = router;"
  }
}

Command Execution

{
  "tool": "execute_command",
  "parameters": {
    "command": "npm install express bcrypt jsonwebtoken",
    "working_directory": "/workspace",
    "timeout": 60
  }
}

Git Operations

{
  "tool": "git_add",
  "parameters": {
    "repository_path": "/workspace",
    "files": ["src/api/auth.js", "package.json"]
  }
}

Test Generation

{
  "tool": "write_test_file",
  "parameters": {
    "path": "/workspace/tests/auth.test.js",
    "test_content": "const request = require('supertest');\nconst app = require('../src/app');\n\ndescribe('Authentication', () => {\n  test('should login with valid credentials', async () => {\n    // Test implementation\n  });\n});",
    "framework": "jest"
  }
}

Tool Selection Strategy

Agents automatically select appropriate tools based on:

1. Task Requirements: Tools are chosen based on the specific task being performed
2. Context Awareness: Previous tool usage and current state influence selection
3. Efficiency: Agents prefer tools that accomplish tasks with fewer steps
4. Error Handling: Tools with better error recovery are preferred for critical operations

Custom Tools (Enterprise)

Enterprise customers can define custom tools for their specific workflows:

{
  "name": "deploy_to_staging",
  "description": "Deploy application to staging environment",
  "parameters": {
    "branch": {
      "type": "string",
      "description": "Git branch to deploy"
    },
    "environment": {
      "type": "string",
      "description": "Target environment",
      "enum": ["staging", "production"]
    }
  },
  "implementation": {
    "type": "webhook",
    "url": "https://your-api.com/deploy",
    "method": "POST"
  }
}

Tool Monitoring

Track tool usage and performance through the Analytics API:

curl -X GET "https://api.dispersl.com/v1/analytics/tools" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes:

• Most frequently used tools
• Tool success rates
• Average execution times
• Error patterns

Best Practices

Tool Usage Optimization

1. Combine operations: Use tools that can perform multiple operations efficiently
2. Error handling: Implement proper error handling for tool failures
3. Resource management: Monitor tool resource consumption
4. Security: Ensure tools follow security best practices

Custom Tool Development

1. Clear interfaces: Define clear input/output specifications
2. Error reporting: Provide detailed error messages and codes
3. Documentation: Include comprehensive tool documentation
4. Testing: Thoroughly test custom tools before deployment

Error Handling

Tools return standardized error responses:

{
  "error": {
    "code": "TOOL_EXECUTION_FAILED",
    "message": "Failed to execute command: npm install",
    "details": {
      "exit_code": 1,
      "stderr": "npm ERR! Cannot resolve dependency",
      "tool": "execute_command"
    }
  }
}

Security Considerations

• Sandboxing: Tools run in isolated environments
• Permission Control: Tools have limited file system and network access
• Audit Logging: All tool usage is logged for security monitoring
• Input Validation: Tool parameters are validated before execution