4 min

Custom Tools

Extending What Your Agent Can Do

Tools Are the Hands of Your Agent

An agent without tools can only think and talk. Tools give it the ability to act — reading files, processing data, calling APIs, and writing output. The quality and safety of your tools determines the quality and safety of your agent.

Your project comes with three starter tools: a file organizer, a PDF summarizer, and an expense tracker. In this module, you'll understand how they work and build three more.

Anatomy of a Safe Tool

Every tool in OpenClaw follows a four-step pattern:

1. VALIDATE  →  Check inputs are well-formed and within expected ranges
2. PERMIT    →  Verify the action is allowed by safety rules
3. ACT       →  Execute the actual operation
4. LOG       →  Record what happened in the audit trail

This pattern ensures that no tool can bypass safety checks, and every action is accountable.

Input Validation

Input validation is your first defense against unexpected behavior:

Check	Why It Matters
Type checking	Prevent "undefined" from becoming a file path
Range validation	Prevent negative amounts, dates in the future, impossibly large files
Path sanitization	Prevent path traversal attacks (e.g., `../../etc/passwd`)
String length limits	Prevent memory issues from absurdly long inputs
Required fields	Catch missing data before it causes cryptic errors downstream

Never trust inputs from the LLM. The model might hallucinate file paths, invent dates, or pass malformed data. Validate everything.

Permission Checks

Before a tool acts, it must verify the action is allowed:

File operations — is the target path within allowed directories?

Network calls — is the target URL on the approved list?

Shell commands — is the command on the allow-list with valid arguments?

Cost impact — will this action exceed the remaining budget?

If any check fails, the tool should return a clear error message (not silently skip) and log the denial.

The Three Starter Tools

Your project includes three tools that demonstrate the pattern:

File Organizer (src/tools/file-organizer.ts)

Reads data/downloads.json for file entries

Categorizes files by type (documents, images, code, archives)

Creates organized directory structure

Logs every file move

PDF Summarizer (src/tools/pdf-summarizer.ts)

Reads data/documents.json for document metadata

Extracts key information from document previews

Generates structured summaries with title, key points, and action items

Logs every document processed

Expense Tracker (src/tools/expense-tracker.ts)

Reads data/expenses.json for receipt data

Categorizes expenses by type (travel, office, software, meals)

Flags unusual amounts or missing receipts

Logs every categorization decision

Building New Tools

When building a new tool, start with this checklist:

Define the interface — what inputs does it take? What does it return?

Write validation first — before any logic, validate all inputs

Add permission checks — does the safety config allow this action?

Implement the core logic — the actual work the tool does

Add audit logging — log the action, inputs (sanitized), and result

Write edge case tests — empty inputs, malformed data, permission denials

Edge Cases That Break Tools

The LLM will send your tools unexpected inputs. Plan for:

Empty arrays — "organize these files" when there are no files

Duplicate entries — the same file appearing twice in a batch

Missing fields — an expense receipt without an amount

Path conflicts — two files with the same target location

Encoding issues — filenames with special characters, unicode, or spaces

A well-designed tool handles all of these gracefully, with clear error messages and audit log entries.

Key Takeaways

Every tool follows validate → permit → act → log. No exceptions.

Never trust LLM inputs — validate types, ranges, paths, and required fields.

Permission checks must happen before action, with denials logged and reported.

Study the three starter tools to understand the pattern before building new ones.

Test edge cases: empty inputs, duplicates, missing fields, path conflicts.

This is chapter 4 of Open Source AI Agents (OpenClaw).

Get the full hands-on course — free during early access. Build the complete system. Your projects become your portfolio.

View course details

Ch. 3: Safety & Guardrails

Ch. 5: Workflows