Understanding Tools

Tools are actions agents can take to accomplish work. They're the bridge between AI's language capabilities and real-world tasks—reading files, calling APIs, running tests, managing git repositories, and more.

What Are Tools?

Tools provide agents with discrete, deterministic capabilities beyond language generation:

File Operations: Read, write, create, delete files in your projects
Code Operations: Analyze structure, generate code, run tests, format files
Communication: Send messages, request input, display progress
Memory & Context: Store and retrieve information across sessions
Version Control: Create commits, manage branches, review changes
API & Network: Call external APIs, fetch data securely
Execution: Run commands safely, execute code in sandboxes
Data Processing: Parse JSON, transform data, perform calculations

Without tools, AI can only generate text. With tools, agents transform plans into concrete actions.

How Agents Use Tools

When an agent needs to accomplish a task, it chooses appropriate tools based on what needs to be done, which actions are available, and the current workflow context.

Consider an agent tasked with "add a new feature to the authentication module":

Read existing code to understand current patterns
Search memory for team coding conventions
Generate new code following discovered patterns
Run tests to verify the implementation works
Format code to match style guidelines
Create a commit with an AI-generated message
Store context about the change for future reference

Each step uses a different tool. The agent reasons about the plan, then uses tools to execute it.

Tool Categories

Tools are organized by what they help agents accomplish:

Communication Tools

Agents use communication tools to interact with users and provide feedback:

Send messages to display information or results
Request structured input using forms or confirmations
Show progress for long-running operations
Display status during multi-step processes

Memory & Context Tools

Memory tools help agents maintain state and learn from experience:

Store information that persists across sessions
Search previous conversations and decisions
Recall project context and team conventions
Track changes to understand evolution over time

File & Code Operations

File tools enable agents to work with your codebase:

Read files to understand existing code
Write files to create new implementations
Analyze code structure to discover patterns
Generate code following conventions
Format code to match style guides
Validate syntax before committing

Version Control Tools

Git tools help agents manage code history:

Create commits with descriptive AI-generated messages
Manage branches for feature development
Review diffs to understand changes
Merge code following team workflows

Testing & Quality Tools

Testing tools ensure code quality:

Run test suites to verify behavior
Generate tests for new code
Analyze coverage to find gaps
Check quality metrics against standards

API & Network Tools

Network tools enable external integrations:

Call REST APIs securely with proper authentication
Fetch external data from services
Integrate with platforms like GitHub, Linear, Slack
Handle webhooks for real-time updates

Execution Tools

Execution tools run code and commands:

Execute commands safely in controlled environments
Run code in sandboxed containers
Monitor performance and resource usage
Capture output and error streams

Data Processing Tools

Data tools transform and analyze information:

Parse structured data (JSON, CSV, XML)
Transform data between formats
Aggregate results from multiple sources
Perform calculations and statistical analysis

Tool Availability and Safety

Not all tools are always available—this is intentional design for safety and reliability.

Workflow-Controlled Availability

Agents working through structured workflows (Pathways) only see tools appropriate for their current state. This prevents accidents and enforces safe practices.

Code Review Workflow Example:

Analysis State:
  Available: file:read, code:analyze, memory:search
  Not Available: file:write, git:commit, deploy:production

Review State:
  Available: comment:create, suggestion:generate
  Not Available: code:execute, file:delete, git:push

Never Available in this workflow:
  - Deployment tools
  - Destructive operations
  - Production access

Deployment Workflow Example:

Validation State:
  Available: test:run, lint:check, security:scan
  Not Available: deploy:staging, deploy:production

Staging State:
  Available: deploy:staging, config:load, monitoring:setup
  Not Available: deploy:production

Production State (with additional guards):
  Available: deploy:production, database:migrate, traffic:shift
  Also Available: rollback:initiate, monitoring:alert

This approach ensures agents can't accidentally use dangerous tools at inappropriate times, even if they wanted to.

Permission Boundaries

Tools respect workspace and agent permissions:

Workspace-Level Permissions: Production workspaces may have different tool access than development workspaces. Sensitive operations require explicit workspace-level approval.

Agent-Level Configuration: When creating agents, you specify which categories of tools they need. Agents only get access to tools necessary for their purpose.

Audit Trails: All tool usage is logged with complete context—which agent, which workspace, which tools, and why those tools were available. Comprehensive observability comes standard.

Using Tools in Practice

Example: Code Review Agent

A code review agent uses tools to provide intelligent feedback:

Read changed files to understand the proposed modifications
Analyze code for potential issues, style violations, or improvements
Search memory for team coding standards and past decisions
Check tests to verify coverage of changed code
Generate comments with specific suggestions
Request clarification if changes aren't clear

The agent coordinates multiple tools to provide comprehensive, context-aware reviews.

Example: Feature Development Agent

A feature development agent implements new functionality:

Read existing code to understand patterns and conventions
Search documentation for relevant API usage
Generate new code following discovered patterns
Run tests to verify the implementation works
Format code to match project style
Create commit with descriptive message
Store context about implementation choices

Each step builds on the previous, with tools providing the concrete actions needed.

Example: Bug Fix Agent

A bug-fixing agent diagnoses and resolves issues:

Read error logs to understand the failure
Analyze code to locate the problematic section
Search memory for similar bugs encountered before
Run tests to reproduce the issue
Modify code to fix the root cause
Run tests again to verify the fix works
Create commit explaining the fix and root cause

Tools enable systematic debugging rather than guesswork.

Tool Safety and Security

Tools operate within secure boundaries designed to prevent accidents and malicious use:

Execution Isolation: Tools run in controlled environments with resource limits and network restrictions.

Input Validation: All tool inputs are validated before execution, preventing injection attacks and ensuring type safety.

Audit Logging: Every tool use is logged with full context, creating comprehensive audit trails for compliance and debugging.

Permission Models: Tools require explicit permissions that can be granted per-agent or per-workspace, with all access patterns auditable.

Related Concepts

Workflows - How Pathways structure tool usage
Agents - How agents reason and take actions
Workspaces - Permission boundaries for tools

Lovelace Developer Portal