Tool System

Tools give agents the ability to interact with the outside world -- searching the web, reading files, executing shell commands, and more. MateClaw includes 12 built-in tools and supports extension through MCP.

How Tools Work

When an agent decides it needs external information or wants to perform an action, it emits a tool call specifying the tool name and input parameters. The tool system:

1. Looks up the tool in the registry
2. Checks ToolGuard approval (if the tool is marked dangerous)
3. Executes the tool with the provided parameters
4. Returns the result to the agent as an "observation"

Tool Registration

Tools are registered using Spring AI's @Tool annotation on Spring beans:

@Component
public class DateTimeTool {

    @Tool(description = "Get the current date and time")
    public String getCurrentDateTime(
            @ToolParam(description = "Timezone, e.g. Asia/Shanghai") String timezone) {
        ZoneId zone = ZoneId.of(timezone);
        return LocalDateTime.now(zone).toString();
    }
}

Key points:

• The class must be a Spring @Component (or @Service, etc.)
• Each @Tool method becomes a callable tool
• Use @ToolParam to describe each parameter for the LLM
• The method's return value is sent back to the agent

Built-in Tools

MateClaw ships with 12 built-in tools:

Tool	Description	Dangerous
DateTimeTool	Get current date/time in any timezone	No
WebSearchTool	Search the web using Serper or Tavily API	No
ShellExecuteTool	Execute shell commands on the host	Yes
ReadFileTool	Read file contents from the filesystem	No
WriteFileTool	Write content to a file	Yes
EditFileTool	Edit specific parts of a file	Yes
SkillFileTool	Read and manage SKILL.md skill files	No
SkillScriptTool	Execute skill scripts	Yes
FileTypeDetectorTool	Detect file MIME type and encoding	No
DocumentExtractTool	Extract text from PDF, DOCX, and other documents	No
WorkspaceMemoryTool	Store and retrieve workspace-level memory entries	No
BrowserUseTool	Control a browser for web automation tasks	Yes
DelegateAgentTool	Delegate tasks to other Agents for collaboration	No
MateClawDocTool	Read built-in project documentation	No

DateTimeTool

Returns the current date and time for a given timezone.

Input:  {"timezone": "America/New_York"}
Output: "2025-03-15T14:30:22"

WebSearchTool

Performs a web search using Serper or Tavily. The search provider, API keys, and fallback behavior are configured in Settings > System Settings > Search Service -- no restart required.

Input:  {"query": "Spring AI Alibaba latest version"}
Output: "Spring AI Alibaba 1.0 was released on..."

Features:

• Switch between Serper and Tavily providers dynamically
• Optional fallback: if the primary provider fails, automatically try the other
• API keys are stored securely in the database (masked in the UI)

See Configuration > Search Service for details.

ShellExecuteTool

Executes a shell command on the host with cross-platform support: Linux/macOS uses /bin/sh -c, Windows uses cmd.exe /D /S /C. Every execution requires user approval through ToolGuard.

Safety design:

• Timeout control: 60-second default, 300-second hard limit -- the process is forcibly terminated when the timeout is reached
• Output limit: stdout and stderr are each capped at 10,000 bytes to prevent large output from exhausting memory
• Output is redirected to a temporary file (not piped), ensuring the timeout mechanism remains effective even with large output
• Returns a structured result (exitCode, stdout, stderr, timedOut)

Input:  {"command": "ls -la /tmp"}
Output: "total 48\ndrwxrwxrwt 12 root root..."

ReadFileTool

Reads the content of a file.

Input:  {"path": "/home/user/project/README.md"}
Output: "# My Project\n\nThis is a sample project..."

WriteFileTool / EditFileTool

Write to or edit files on the filesystem. Both are marked dangerous.

// WriteFileTool
Input:  {"path": "/tmp/hello.txt", "content": "Hello, World!"}
Output: "File written successfully: /tmp/hello.txt"

// EditFileTool
Input:  {"path": "/tmp/hello.txt", "oldContent": "World", "newContent": "MateClaw"}
Output: "File edited successfully"

DocumentExtractTool

Extracts text from documents (PDF, DOCX, XLSX, etc.).

Input:  {"path": "/home/user/report.pdf"}
Output: "Annual Report 2024\n\nRevenue: $1.2M..."

WorkspaceMemoryTool

Stores and retrieves key-value memory entries scoped to a workspace.

Input:  {"action": "store", "key": "project_name", "value": "MateClaw"}
Output: "Stored: project_name = MateClaw"

Input:  {"action": "retrieve", "key": "project_name"}
Output: "MateClaw"

BrowserUseTool

Controls a headless browser for web automation.

Input:  {"action": "navigate", "url": "https://example.com"}
Output: "Navigated to https://example.com. Page title: Example Domain"

ToolGuard

ToolGuard is a safety mechanism that requires user approval before executing dangerous tools. When enabled:

1. The agent requests a tool call
2. If the tool is in the dangerous list, execution pauses
3. The frontend shows an approval dialog to the user
4. The user approves or rejects
5. Execution resumes or the agent is notified of rejection

Configure ToolGuard in application.yml:

mateclaw:
  tool:
    guard:
      enabled: true
      dangerous-tools:
        - ShellExecuteTool
        - WriteFileTool
        - EditFileTool
        - SkillScriptTool
        - BrowserUseTool

Tool Management via API

List All Tools

curl http://localhost:18088/api/v1/tools \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Enable/Disable a Tool

curl -X PUT http://localhost:18088/api/v1/tools/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

MCP Tools

Tools can also be provided by external MCP (Model Context Protocol) servers. These tools are discovered automatically and appear alongside built-in tools. See MCP Protocol for details.

DelegateAgentTool

Delegate tasks to other Agents for multi-agent collaboration. Provides two methods:

• delegateToAgent(agentName, task) — Call target Agent by name, run in isolated session, return result as observation
• listAvailableAgents() — List all available Agents with name, type, and description

User: Search for Spring AI news and have the writer summarize it
Agent A: [calls WebSearchTool]
         [calls delegateToAgent(agentName="Writer", task="Summarize: ...")]
         [receives Writer's response]
         Combines and replies to user

Safety:

• Recursion guard — Max 3 delegation levels
• Isolated sessions — Delegated Agent uses separate conversation
• Result truncation — Limited to 4000 characters

Creating Custom Tools

To add a custom tool:

1. Create a Spring component with @Tool methods:

@Component
public class MyCustomTool {

    @Tool(description = "Calculate the factorial of a number")
    public String factorial(
            @ToolParam(description = "The number to compute factorial for") int n) {
        long result = 1;
        for (int i = 2; i <= n; i++) {
            result *= i;
        }
        return String.valueOf(result);
    }
}

2. The tool is automatically registered on startup and available to all agents.

3. If the tool performs potentially dangerous operations, add it to the ToolGuard dangerous list.

Next Steps

• Skill System -- Higher-level capabilities built on tools
• MCP Protocol -- External tool providers
• Security -- ToolGuard configuration details