Creating Custom Tools
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Custom tools in the plugsuits project are executable functions designed to extend the capabilities of the AI agent, allowing it to interact with the filesystem, execute shell commands, and manage task states. The system leverages the Vercel AI SDK tool utility to define structured interfaces that the agent can invoke during its reasoning loop. These tools are organized into specific subsystems such as execute, explore, modify, and planning to ensure a clean separation of concerns.
The architecture supports both internal tool definitions and external integration via the Model Context Protocol (MCP). By implementing custom tools, developers can provide the agent with specialized skills tailored to specific project requirements, such as custom build steps, specialized search logic, or proprietary API integrations.
Sources: packages/cea/src/tools/AGENTS.md, packages/harness/README.md:12-25
Tool Structure and Registration
Defining a Tool
Tools are defined using the tool function from the ai package. A tool definition consists of three primary components:
- Description: A string explaining what the tool does, often loaded from a companion
.txtfile. - Input Schema: A Zod schema that defines and validates the arguments the AI must provide.
- Execute Function: An asynchronous function that performs the actual logic and returns a string or object.
The flow shows how the AI interacts with a defined tool through a validation gate.
Sources: packages/cea/src/tools/planning/todo-write.ts:182-186, packages/harness/README.md:19-25
The Tool Registry
The project uses a centralized registry to manage tool keys. The file src/tools/index.ts serves as the single source of truth for exported tool names (e.g., shell_execute, read_file, edit_file). Maintaining stable keys in this registry is critical for ensuring that model tool contracts and tests remain consistent.
| Component | Responsibility |
|---|---|
src/tools/index.ts | Public tool registry keys and stable naming |
src/tools/explore/ | Read-only operations and search logic |
src/tools/modify/ | Deterministic file mutation (hashline-native) |
src/tools/execute/ | Process management and shell semantics |
Sources: packages/cea/src/tools/AGENTS.md:12-25
Implementation Patterns
Input Validation with Zod
Every custom tool must have a strictly typed inputSchema. This ensures the agent provides the correct data types and allows for descriptive field documentation, which helps the model understand how to use the tool.
Sources: packages/cea/src/tools/planning/todo-write.ts:28-41
Execution Logic and Session Management
Tools often require access to the current session state. The SessionManager from @ai-sdk-tool/harness is frequently used within the execute function to maintain session-specific data, such as temporary todo files or history.
This diagram illustrates the typical interaction between a tool execution and the session management system.
Sources: packages/cea/src/tools/planning/todo-write.ts:133-146, packages/harness/README.md:95-103
Handling Binary Dependencies
If a custom tool relies on external binaries (like ripgrep), the ToolsManager provides utilities to ensure these dependencies are present. It can check the system PATH or automatically download required binaries to a local directory (~/.cea/bin).
Sources: packages/cea/src/utils/tools-manager.ts:13-30, packages/cea/src/utils/tools-manager.ts:66-83
Advanced Tool Features
Custom Rendering
In interactive Terminal UI (TUI) mode, tool calls can be customized to display information more clearly than raw JSON. Developers can define custom renderers in a ToolRendererMap.
| Tool Name | Renderer Logic |
|---|---|
read_file | Previews file content with line numbers and handles truncation |
todo_write | Displays a summarized count of task statuses (Pending, Completed) |
shell_execute | Displays the command being run and its exit code |
Sources: packages/cea/src/interaction/tool-renderers.ts:474-515, packages/cea/src/interaction/tool-renderers.ts:634-645
MCP Tool Merging
The system supports merging local tools with those provided by Model Context Protocol (MCP) servers. During merging, naming conflicts are resolved by sanitizing server names and using them as prefixes for the tool names.
The diagram shows how conflicts are handled when a local tool and an MCP server provide tools with the same name.
Sources: packages/harness/src/mcp-tool-merger.test.ts:25-45, packages/harness/src/mcp-tool-merger.test.ts:114-125
Conclusion
Creating custom tools in plugsuits involves defining a clear Zod schema for inputs, implementing asynchronous execution logic that integrates with project-wide session management, and ensuring proper registration in the tool registry. By utilizing the built-in TUI renderers and binary management utilities, developers can build robust, user-friendly tools that expand the agent's capability to perform complex software engineering tasks autonomously.