Tools Reference

Tools are the building blocks that allow the Kuse Cowork agent to interact with your system and codebase.

Overview

The agent can use tools to:

• Read and modify files
• Execute shell commands
• Search and navigate codebases
• Run code in isolated containers

File Operations

read_file

Read the contents of a file.

Parameters:

Example:

{
  "name": "read_file",
  "input": {
    "path": "src/components/Button.tsx"
  }
}

‍

Features:

• Supports ~ expansion for home directory
• Handles large files with truncation
• Returns line numbers for easy reference

write_file

Create or overwrite a file.

‍

Example:

{
  "name": "write_file",
  "input": {
    "path": "src/utils/helpers.ts",
    "content": "export function helper() {\n  return true;\n}"
  }
}

Features:

• Creates parent directories if needed
• Overwrites existing files
• Supports any text content

edit_file

Make targeted edits to an existing file.

Parameters:

‍

Example:

{
  "name": "edit_file",
  "input": {
    "path": "src/config.ts",
    "old_content": "const DEBUG = false;",
    "new_content": "const DEBUG = true;"
  }
}

Features:

• Precise search-and-replace
• Preserves file formatting
• Supports multi-line edits
• Reports if match not found

list_dir

List contents of a directory.

Parameters:

‍

Example:

{
  "name": "list_dir",
  "input": {
    "path": "src/components"
  }
}

‍

Output:

Button.tsx
Card.tsx
Modal/
  index.tsx
  styles.css

Search Operations

glob

Find files matching a pattern.

Parameters:

‍

Example:

{
  "name": "glob",
  "input": {
    "pattern": "**/*.test.ts",
    "path": "src"
  }
}

‍

Pattern Examples:

grep

Search file contents.

Parameters:

‍

Example:

{
  "name": "grep",
  "input": {
    "pattern": "function handleSubmit",
    "path": "src",
    "include": "*.tsx"
  }
}

Output:

src/components/Form.tsx:45: function handleSubmit(event) {
src/components/Login.tsx:23: function handleSubmit() {

Command Execution

bash

Execute shell commands.

Parameters:

‍

Example:

{
  "name": "bash",
  "input": {
    "command": "npm test -- --coverage",
    "cwd": "/workspace"
  }
}

Features:

• Runs in project context
• Captures stdout and stderr
• Has timeout protection
• Returns exit code

‍

Security: Commands run on your local system. Be cautious with destructive commands.

‍

docker_run

Run commands in Docker containers.

Parameters:

‍

Example:

{
  "name": "docker_run",
  "input": {
    "command": "python script.py",
    "image": "python:3.11-alpine",
    "workdir": "/workspace"
  }
}

‍

Available Images:

‍

‍Mount Points:

‍

docker_list

List running Docker containers.

Parameters: None

Example:

{
  "name": "docker_list",
  "input": {}
}

docker_images

List available Docker images.

Parameters: None

Example:

{
  "name": "docker_images",
  "input": {}
}

‍

MCP Tools

When MCP servers are connected, additional tools become available dynamically:

{
  "name": "mcp_servername_toolname",
  "input": {
    "param1": "value1"
  }
}

‍

Tool Execution Flow

Error Handling

Common Errors

‍

Error Response Format

{
  "tool_use_id": "tool_123",
  "content": "Error: File not found: /path/to/file.txt",
  "is_error": true
}

‍

Best Practices

File Operations

Read Before Edit

Always read a file before editing to understand its current state.


Use Exact Matches

For `edit_file`, use the exact text including whitespace.


Prefer edit_file

Use `edit_file` for modifications, `write_file` only for new files.


Search Operations

Start Broad

Use `glob` to find files, then `grep` to search within them.


Use Specific Patterns

More specific patterns are faster and produce fewer results.


Command Execution

Prefer Docker

Use `docker_run` for risky or experimental commands.


Check Exit Codes

Tool results include exit codes for command success/failure.


Performance

Batch Operations

Combine related operations to reduce API calls.


Use Working Directory

Set `cwd` to avoid long absolute paths.


Tool Configuration

Allowed Tools

Tools can be restricted per task:

AgentConfig {
    allowed_tools: vec![
        "read_file".to_string(),
        "glob".to_string(),
        "grep".to_string(),
    ],
}

Docker Settings

Container resource limits:

• Memory: Default unlimited
• CPU: Default unlimited
• Timeout: 5 minutes per command
• Network: Host network by default

Next Steps

• Skills System - Extend tool capabilities
• Agent System - How tools are orchestrated
• MCP Protocol - Add external tools

‍