Agent Tools System

Coda's Agent Tools System provides AI assistants with the ability to perform real-world tasks through a comprehensive set of built-in tools. This powerful feature enables Coda to read files, search the web, execute commands, and manage git repositories on your behalf.

Overview

The Agent Tools System is built on two key components:

Agent Framework: Based on the Oracle Cloud Infrastructure (OCI) Agent Developer Kit architecture
Tool System: Implements the Model Context Protocol (MCP) for secure, validated tool execution

Quick Start

Enabling Agent Mode

Agent mode allows the AI to automatically use tools to accomplish tasks:

# Enable agent mode
/agent on

# Check status
/agent status

# Disable agent mode
/agent off

Basic Tool Usage

When agent mode is enabled, simply ask Coda to perform tasks:

You: "What's in the current directory?"
Coda: I'll list the files in the current directory for you.
[Uses list_files tool]
Here are the files in the current directory...

You: "Read the README.md and summarize it"
Coda: I'll read the README.md file and provide a summary.
[Uses read_file tool]
Based on the README.md, here's a summary...

Available Tools

Coda includes 12 built-in tools organized into 4 categories:

📁 Filesystem Tools

read_file: Read contents of any file
write_file: Create or overwrite files
list_files: List directory contents
search_files: Search for files by name pattern
search_file_content: Search within file contents

🔧 System Tools

exec: Execute shell commands (with safety controls)
get_system_info: Get system information

🌐 Web Tools

web_search: Search the internet for information
fetch_url: Fetch and process web page content

📝 Git Tools

git_status: Check repository status
git_diff: View uncommitted changes
git_commit: Create commits (requires confirmation)

Managing Tools

View Available Tools

# Show tools overview
/tools

# List all tools
/tools list

# List tools by category
/tools list filesystem
/tools list git

# Get detailed information about a specific tool
/tools info read_file
/tools info web_search

Enable/Disable Tools

# Disable a specific tool
/tools disable exec

# Enable a tool
/tools enable exec

# Check status of all tools
/tools status

Tool Security & Permissions

Coda implements multiple security layers:

Tool Validation: All tool inputs are validated before execution
Permission System: Dangerous operations require explicit confirmation
Sandboxing: File operations are restricted to allowed directories
Audit Trail: All tool usage is logged for review

Configuration

Control tool behavior in ~/.config/coda/config.toml:

[tools]
enabled = true
filesystem_enabled = true
git_enabled = true
web_enabled = true
system_enabled = true
require_confirmation = false  # Set to true for extra safety

[agent]
enabled = true
max_iterations = 10  # Maximum tool calls per turn
show_tool_calls = true  # Display tool usage in conversation

Common Use Cases

File Analysis

You: "Analyze the Python files in src/ and tell me about the architecture"
Coda: I'll analyze the Python files in the src/ directory.
[Uses list_files and read_file tools]
Based on my analysis of the codebase...

Research Tasks

You: "Search for the latest Python 3.12 features and create a summary"
Coda: I'll search for information about Python 3.12 features.
[Uses web_search tool]
[Uses write_file to create summary.md]
I've created a summary of Python 3.12 features in summary.md...

Code Review

You: "Review the uncommitted changes and suggest improvements"
Coda: I'll check the git status and review the changes.
[Uses git_status and git_diff tools]
Here's my review of the uncommitted changes...

Project Setup

You: "Set up a new Python project with tests and CI"
Coda: I'll help you set up a new Python project structure.
[Uses multiple write_file calls to create project files]
[Uses exec to initialize git repository]
I've created a complete Python project structure...

Advanced Features

Tool Chaining

The agent can intelligently chain multiple tools together:

You: "Find all TODO comments in the codebase and create a task list"
Coda: [Uses search_file_content to find TODOs]
      [Uses write_file to create tasks.md]

Iterative Problem Solving

The agent can iterate to solve complex problems:

You: "Debug why the tests are failing"
Coda: [Uses exec to run tests]
      [Uses read_file to examine test files]
      [Uses search_file_content to find related code]
      [Provides analysis and suggestions]

Context-Aware Execution

Tools understand context from the conversation:

You: "I'm working on user_auth.py"
Coda: I understand you're working on user_auth.py
You: "Add input validation"
Coda: [Uses read_file on user_auth.py]
      [Uses write_file to add validation]

Provider Support

Tool support varies by provider:

Provider	Tool Support	Notes
OCI GenAI	✅ Full	Native function calling
OpenAI	✅ Full	Function calling API
Anthropic	✅ Full	Tool use API
Ollama	⚠️ Limited	Depends on model
LiteLLM	✅ Varies	Depends on backend

Best Practices

1. Be Specific

❌ "Fix the code"
✅ "Fix the TypeError in auth.py line 45"

2. Provide Context

❌ "Read the file"
✅ "Read config.json and explain the database settings"

3. Verify Results

You: "Create a backup of important files"
Coda: [Creates backups]
You: "List the backup directory to confirm"

4. Use Confirmation Mode

For sensitive operations, enable confirmation:

[tools]
require_confirmation = true

Troubleshooting

Tools Not Working

Check agent mode is enabled: /agent status
Verify provider supports tools: /tools status
Check specific tool is enabled: /tools info <tool_name>
Enable debug mode: /debug on

Permission Errors

# Check tool permissions
/tools status

# Review configuration
/config show

Performance Issues

Reduce max_iterations in config
Disable unused tool categories
Use specific tools rather than broad requests

Security Considerations

File System Access: Tools can read/write files in your current directory and subdirectories
Command Execution: The exec tool can run shell commands - use with caution
Web Access: Web tools can fetch content from any URL
Git Operations: Git tools can modify your repository

Always review tool actions, especially when:

Working in production environments
Handling sensitive data
Executing system commands
Making git commits

Examples

Complete Workflow Example

You: Enable agent mode and help me refactor user.py to use type hints
Coda: I'll enable agent mode and help you refactor user.py with type hints.

/agent on
Agent mode enabled.

Now I'll read user.py and add type hints.
[Uses read_file tool to read user.py]
[Analyzes code structure]
[Uses write_file tool to save refactored version]

I've successfully refactored user.py with comprehensive type hints. The changes include:
- Added type hints to all function parameters and return values
- Imported necessary types from typing module
- Used Union types where multiple types are accepted
- Added TypedDict for complex dictionary structures

Would you like me to show you the diff of the changes?

Research and Documentation

You: Research Python async best practices and create a guide
Coda: I'll research Python async best practices and create a comprehensive guide.

[Uses web_search tool to find current best practices]
[Reads multiple sources]
[Uses write_file to create async_guide.md]

I've created async_guide.md with a comprehensive guide covering:
- Async/await fundamentals
- Best practices for error handling
- Performance optimization tips
- Common pitfalls to avoid
- Real-world examples