OpenClaw Core Concepts #5: What Are Tools? Giving Your AI Agent Hands, Eyes, and a Voice - haiai.world

Without tools, your OpenClaw agent is just a very smart parrot. With them, it becomes an employee who can actually get things done.

If you have followed this series from the start, you have built up a solid mental model of OpenClaw’s four foundational systems. In Core Concepts #1: What Is the Gateway?, you learned that the Gateway is the always-on infrastructure layer that routes every message to the right destination. In Core Concepts #2: What Is the Agentic Loop?, you discovered the six-stage engine that turns a message into a completed task. In Core Concepts #3: How OpenClaw’s Memory System Works, you saw how your agent accumulates knowledge across sessions without ever forgetting you prefer TypeScript. And in Core Concepts #4: What Is an Agent?, you learned that an agent is, at its core, just a folder of plain text files.

But every single article in this series kept using a word we never fully defined: tools.

The Agentic Loop calls tools. The Agent runtime executes tools. The Gateway routes tool results back to the session. Tools are mentioned in TOOLS.md, restricted in openclaw.json, and abused by malicious skills from ClawHub. They are everywhere.

Today, we define them — completely, precisely, and in plain English.

The One-Sentence Definition

Here is the cleanest definition, straight from the official documentation:

A tool is a typed function the agent can invoke (e.g. exec, browser, web_search, message). OpenClaw ships a set of built-in tools and plugins can register additional ones. The agent sees tools as structured function definitions sent to the model API.

Three phrases in that sentence deserve your full attention:

“A typed function the agent can invoke” — tools are not passive features. They are callable actions. When the AI model decides it needs to do something—read a file, search the web, send a message—it calls a tool by name, like a programmer calling a function.

“The agent sees tools as structured function definitions” — this is what makes tool-calling reliable rather than chaotic. The model doesn’t improvise. It receives a precise schema telling it: “here is what this tool is called, here are the parameters it accepts, and here is what it returns.” It then calls the tool using that exact contract.

“Plugins can register additional ones” — the built-in tools are just the starting point. The entire Skills and MCP ecosystem exists to extend this set.

If that still feels abstract, here is the most concrete possible version: tools are how your agent gets hands. Without tools, the model can only generate text. With tools, it can read your email, write files to your hard drive, search the web, control your browser, and send messages on your behalf.

Tools vs. Skills: The Confusion Everyone Has on Day One

Before we go any further, we need to clear up the single most common point of confusion in the entire OpenClaw ecosystem. New users constantly mix these two things up.

The distinction is elegant once you see it:

Tools are organs — they determine whether OpenClaw can do something. Skills are textbooks — they teach OpenClaw how to combine tools to accomplish tasks.

Let’s make that concrete:

read and write are tools — they let the agent access files at a system level
exec is a tool — it lets the agent run terminal commands
web_search is a tool — it lets the agent query the web
browser is a tool — it lets the agent click, scroll, and fill forms

But knowing how to use Google Workspace for email management, or how to organize notes in Obsidian, or how to manage a GitHub repository — that knowledge comes from Skills (SKILL.md files injected into the system prompt).

The gog skill teaches the agent how to use Google Workspace for email and calendar; the obsidian skill teaches it how to organize notes; the github skill teaches it how to work with repos.

The most critical implication: installing a skill does not grant new permissions. You could install the Obsidian skill, and the agent would now know how to organize notes — but without the write tool explicitly enabled, it cannot write files at all. Tools are the gates. Skills are the maps.

Here is a table that makes this permanent in your memory:

	Tools	Skills
What it is	A typed, callable function	A Markdown instruction file (SKILL.md)
Lives in	OpenClaw core + plugins	Your workspace, shared folders, plugins
Controls	Whether the agent can do something	How the agent does something
Permission model	Governed by `tools.allow` / `tools.deny`	No permissions — purely instructional
Security risk	Direct (can execute commands)	Indirect (can instruct harmful tool use)
Example	`exec`, `browser`, `web_search`	`gog`, `obsidian`, `github`

The Six Built-In Tool Groups

OpenClaw organizes its 26 core built-in tools into logical groups. You will see these group names constantly in your openclaw.json configuration. Understanding the groups lets you write clean, readable permission policies rather than listing every individual tool by name.

Group 1: `group:runtime` — The Power Tools

Includes: exec, bash, process

This is the most powerful — and most dangerous — group. exec runs any shell command directly on your machine. bash is its legacy alias. process manages long-running background shell sessions. Together, they let your agent do anything a command-line user can do: install packages, move files, run scripts, restart services.

Let’s not sugarcoat this. If exec is enabled, OpenClaw can run any shell command. That includes rm -rf ~. That includes installing packages. That includes reading any file you have access to. This is not a scare tactic — it is precisely why the permission system exists.

The practical implication: exec should be disabled for any agent that doesn’t absolutely need it. A morning briefing agent that reads your calendar does not need shell access. A coding agent that writes and tests code does.

Group 2: `group:fs` — The Filing Cabinet

Includes: read, write, edit, apply_patch

The group:fs tools give your agent access to the filesystem. read pulls file contents. write creates or overwrites files. edit makes targeted in-place modifications. apply_patch applies structured multi-file diffs — this is the tool Claude Code-style workflows use most.

By default, write and edit are scoped to the workspace directory. If you need your agent to write files across the entire filesystem (for example, managing server configs or editing nginx/systemd files), you have to explicitly enable broader access — which should be a deliberate, considered decision, not a default.

Group 3: `group:ui` — The Eyes and Hands

Includes: browser, canvas

browser is what makes OpenClaw feel genuinely futuristic. It controls a real Chromium browser instance — clicking buttons, filling out forms, taking screenshots, navigating pages, and scraping content that requires JavaScript to render. This is the tool behind stories of OpenClaw negotiating car prices by filling out dealer contact forms, or signing up for services autonomously.

canvas is a complementary tool for image rendering and visual output. Together, group:ui gives your agent the ability to see and interact with the visual web the way a human would.

Group 4: `group:messaging` — The Voice

Includes: message, sessions_list, sessions_send, sessions_spawn, session_status

These tools let your agent communicate — both with you and with other agents. message sends responses back through your configured channels (WhatsApp, Telegram, Discord, etc.). The sessions_* tools enable multi-agent coordination: listing running sessions, sending messages between agents, spawning new sub-agents, and checking session status.

This group is what makes the multi-agent architecture we described in Core Concepts #4 actually work. When a parent agent delegates a task to a sub-agent, it uses sessions_spawn. When it wants to know what the sub-agent found, it calls sessions_send.

Group 5: `group:memory` — The Long-Term Brain

Includes: memory_search, memory_get

These two tools are the execution layer of the memory system we covered in Core Concepts #3. memory_search performs hybrid semantic and keyword search across all your memory files — finding relevant context even when the wording doesn’t match exactly. memory_get reads a specific file or line range when you know exactly where the information lives.

Without these tools enabled, your agent cannot actively recall information from past sessions. It would have to rely entirely on whatever gets loaded into the boot context — a much blunter, more expensive approach.

Group 6: Web Tools — The Research Assistant

Includes: web_search, web_fetch

web_search queries the Brave Search API and returns results. It requires a Brave API key and caches results for 15 minutes by default. web_fetch retrieves the content of a specific URL. Together, these two tools let your agent research topics, read documentation, monitor websites for changes, and pull live data without needing the full browser tool overhead.

How the Agent “Sees” Tools: The Two-Layer Exposure

Here is something most documentation doesn’t explain clearly: the agent doesn’t just receive a list of tool names. It receives two parallel representations simultaneously.

The agent sees both “what tools exist” and “how to call them.” If a tool doesn’t appear in the system prompt or the schema, the model cannot call it.

Layer 1: The System Prompt Text — a human-readable description of available tools, injected into the context at session start. This is how the model understands what each tool does and when to use it.

Layer 2: The Tool Schema — structured JSON function definitions sent directly to the model API. This is the precise contract that tells the model the exact name, parameter types, and return format for each callable tool.

This two-layer approach means tool calling is precise and structured, not free-form. The model cannot invent tool names or guess at parameters. It either calls a real, schema-defined tool correctly — or it doesn’t call a tool at all.

Controlling Tool Access: The Permission System

This is where OpenClaw’s power and its danger become most apparent. By default, OpenClaw ships with a relatively open tool configuration — convenient for getting started, potentially catastrophic in production.

The permission system works through three mechanisms in your openclaw.json:

1. `tools.allow` and `tools.deny`

The fundamental rule: deny always wins over allow.

{
  "tools": {
    "allow": ["group:fs", "browser", "web_search"],
    "deny": ["exec"]
  }
}

This configuration enables all filesystem tools and the browser, but explicitly blocks shell execution — even if exec would otherwise be included by a profile. The deny list is a hard ceiling, not a suggestion.

2. `tools.profile` — Preset Allowlists

Rather than listing every tool individually, you can use built-in profiles as a starting point:

"minimal"  → session_status only. For read-only or restricted agents.
"messaging" → message + sessions_*. For channel bots with no system access.
"coding"   → group:fs + group:runtime + group:sessions + group:memory + image. For dev agents.
"full"     → Everything. Use with extreme caution.

tools.profile sets the base before allow and deny are applied. This makes profile + targeted deny the cleanest pattern for most setups:

{
  "tools": {
    "profile": "coding",
    "deny": ["exec"]
  }
}

Starts with the coding profile, which includes filesystem and session tools, but explicitly removes shell execution.

3. Per-Agent Tool Overrides

In a multi-agent setup, different agents can have completely different tool profiles — a critical capability we touched on in Core Concepts #4. Here’s what that looks like in practice:

{
  "agents": {
    "list": [
      {
        "id": "coding",
        "tools": { "profile": "coding" }
      },
      {
        "id": "support-bot",
        "tools": {
          "profile": "messaging",
          "allow": ["web_search"]
        }
      },
      {
        "id": "family-bot",
        "tools": { "profile": "minimal" }
      }
    ]
  }
}

One Gateway. Three agents. Three completely different capability profiles. Your coding agent can run code. Your support bot can search the web. Your family bot can only report its own status. The permissions stay scoped to the minimum each agent actually needs — which is both a security best practice and a cost management strategy.

4. Loop Detection: The Circuit Breaker

One built-in safety mechanism worth knowing about is loop detection — a tool monitoring system that blocks or warns when it detects repetitive no-progress patterns. OpenClaw tracks recent tool-call history and blocks or warns when it detects patterns like genericRepeat (calling the same tool with the same params repeatedly), knownPollNoProgress (polling tools that return identical results), and pingPong (alternating A/B/A/B calls with no progress).

This prevents runaway agents from burning through your API budget in a stuck loop. Enable it with:

{
  "tools": {
    "loopDetection": {
      "enabled": true,
      "warningThreshold": 10,
      "criticalThreshold": 20,
      "globalCircuitBreakerThreshold": 30
    }
  }
}

Beyond Built-in Tools: Three Ways to Extend

Once you have mastered the 26 core tools, you have three paths for extending your agent’s capabilities further.

Path 1: Skills (SKILL.md Files from ClawHub)

Skills don’t add new tools to the system — they add instructions for using existing tools in specialized, domain-specific ways. ClawHub, the official skill marketplace, hosts over 13,700 community-built skills as of April 2026. These cover note-taking (Obsidian, Notion), email and calendar (Gog for Google Workspace), development (GitHub, Vercel), smart home (Home Assistant), voice calls (ElevenLabs), and much more.

The critical security reality: installing a skill from ClawHub grants it access to the same resources as OpenClaw itself. There is no sandbox isolation between skills by default. This is what made the ClawHavoc supply chain attack in early 2026 so damaging — attackers uploaded 1,184 malicious skills with professional documentation and convincing names before detection. Roughly 12% of the entire ClawHub registry was compromised before the attack was caught.

Since February 2026, ClawHub has integrated VirusTotal automatic scanning to block malicious skill downloads. But automated scanning catches known malware, not new attack patterns. Reviewing the source code of every skill you install is not optional — it is the only reliable defense.

Path 2: Plugins (npm Packages)

Plugins are a deeper extension mechanism than skills. A plugin is a package that can register any combination of new capabilities — channels, model providers, new tools, skills, speech, real-time transcription, real-time voice, media understanding, image generation, video generation, web fetch, web search, and more.

Some plugins are core (shipped with OpenClaw itself), while others are external (published on npm by the community). Plugin examples that ship additional tools include Lobster (a typed workflow runtime with resumable approvals), LLM Task (a JSON-only LLM step for structured output), and Music Generation (a shared music_generate tool backed by configurable providers).

The distinction between skills and plugins is architectural depth. A skill adds instructions. A plugin can add entirely new tools that didn’t exist in the core system.

Path 3: MCP (Model Context Protocol)

The largest and most powerful extension layer is the Model Context Protocol — an open standard created by Anthropic that provides a universal way for AI applications to connect with external tools and data sources. Think of MCP as USB-C for AI: one standard protocol that replaces dozens of custom integrations.

OpenClaw uses MCP to connect to 500+ tools — from Gmail and Slack to Salesforce and PostgreSQL — through a single, secure interface. OpenClaw acts as an MCP host: it initiates connections to MCP servers and sends requests on behalf of your automation workflows, managing multiple server connections simultaneously.

The most widely used MCP servers in the OpenClaw community include GitHub, Postgres, Filesystem, Slack, Google Drive, Notion, and Puppeteer for browser automation. Because MCP is an open standard, an MCP server built for one AI agent (like Claude Desktop or Cursor) works with all of them — including OpenClaw. OpenClaw adopted MCP specifically because the community had already built an enormous ecosystem around it. Rather than reinventing those integrations, OpenClaw simply speaks MCP and instantly inherits all of them.

One important distinction for security: MCP servers are portable (they work with Claude Desktop, Cursor, VS Code, and any MCP-compatible host), while skills are OpenClaw-specific. If you want the best of both worlds, build an MCP server for the tool capabilities and wrap it in a skill for the workflow logic.

The Security Reality: Tools Are a Double-Edged Sword

No honest article about OpenClaw tools can avoid confronting this directly.

The same capabilities that make tools powerful make them dangerous. Every tool that your agent can invoke is a tool that a compromised skill, a prompt injection attack, or a misconfigured permission can also invoke. The security surface of your agent grows with every tool you enable.

Here is a real attack pattern documented from the ClawHavoc campaign: a malicious skill uploaded to ClawHub, professionally documented and correctly categorized, would instruct the agent to run seemingly innocuous-looking commands using exec. Those commands would exfiltrate credentials and deploy a remote access trojan — all while the user saw normal-looking output in their chat.

The attacker didn’t need to exploit a zero-day vulnerability. They just needed a convincing SKILL.md, a user who trusted “top downloaded” as a proxy for safety, and an agent with exec enabled.

One of OpenClaw’s own maintainers said on Discord: “If you can’t understand how to run a command line, this is far too dangerous of a project for you to use safely.”

That is not a reason to avoid OpenClaw. It is a reason to configure it carefully.

The five non-negotiable rules for tool security:

Start with the minimum viable profile. Enable tools deliberately, not by default. Use messaging for bots, coding for dev agents, and minimal for anything that doesn’t need system access.
Explicitly deny exec unless you absolutely need it. Most automations don’t require full shell access. A daily briefing agent needs read-only access to email and calendars. It doesn’t need exec.
Review every third-party skill before installing. Read the SKILL.md. Read any bundled scripts. Check the GitHub source. Verify the VirusTotal scan. The ClawHavoc campaign proved that “top downloaded” is not a safety signal.
Use sandbox isolation for untrusted agents. OpenClaw supports Docker-based sandboxing that restricts what a sandboxed agent can reach. Enable it for any agent running third-party or community skills.
Enable loop detection in production. Runaway tool loops burn tokens, can cause unintended side effects, and are a known symptom of prompt injection. The circuit breaker configuration takes two minutes to add.

What a Real Tool Call Looks Like End-to-End

Let’s walk through the complete lifecycle of a single tool call, connecting everything you have learned across this entire series.

You send: “Search for the latest Claude Code updates from this week and save a summary to my notes folder.”

Stage 1 (Intake): The Gateway receives your message and routes it to your agent session.

Stage 2 (Context Assembly): The runtime loads your SOUL.md, AGENTS.md, MEMORY.md, and today’s daily log. It also assembles the tool schema — a JSON list of every enabled tool’s name, parameters, and description — and injects it into the model’s context.

Stage 3 (Model Inference): The model reads your request and the tool schema. It decides it needs to call web_search first.

Stage 4a (Tool Execution — Iteration 1): The runtime intercepts the web_search call, queries the Brave API for “Claude Code updates April 2026”, and returns the results to the model.

Stage 4b (Tool Execution — Iteration 2): The model reads the search results, decides it needs to fetch the full content of the most relevant article, and calls web_fetch with the URL.

Stage 4c (Tool Execution — Iteration 3): The model now has enough content to write a summary. It calls write with a target path of ~/notes/claude-code-updates-2026-04-09.md and the generated summary as content.

Stage 5 (Streaming): Throughout all of this, you see live updates in your chat: which tool is being called, what was found, what is being written.

Stage 6 (Persistence): The session logs what happened to today’s daily memory file. The agent now “remembers” that you have a notes folder at that path.

Three tools. Three loop iterations. One completed task. The AI did the research, the reading, and the writing. You sent one message.

The Three-Sentence Summary

If you take only three things away from this article, make it these:

A tool is a typed, callable function — the mechanism that turns AI text generation into real-world action. Without tools, your agent can only produce words. With tools, it can read files, run commands, search the web, control a browser, send messages, and orchestrate other agents.
Tools and skills are fundamentally different things. Tools are the gates that determine whether the agent can do something. Skills are the maps that teach the agent how to do something. Installing a skill never grants new permissions — only enabling the corresponding tool does that.
The permission system is not optional. Every tool you enable is an attack surface. Use the minimum viable profile for each agent, explicitly deny what you don’t need, review every third-party skill before installing it, and enable loop detection in production. The power of OpenClaw’s tool system and the danger of it are exactly the same thing.

📬 Subscribe to the haiai.world newsletter for weekly AI tool breakdowns. No fluff, just clarity.

Up next: OpenClaw Core Concepts #6 — Skills in Depth: How SKILL.md files work, how to read them safely, and how to build your own from scratch.

More in This Series:

References

OpenClaw Official Docs — Tools and Plugins https://docs.openclaw.ai/tools
openclaw.cc — Tools | OpenClaw Docs https://openclaw.cc/en/tools/
openclaw.com.au — OpenClaw Tools — Native Agent Capabilities https://openclaw.com.au/tools
openclaw-ai.com — Tools | OpenClaw Docs https://openclaw-ai.com/en/docs/tools/index
WenHao Yu — OpenClaw Setup Guide: 26 Tools + 53 Skills Explained (February 5, 2026) https://yu-wenhao.com/en/blog/openclaw-tools-skills-tutorial/
MoltFounders — OpenClaw Configuration Guide 2026 — Complete openclaw.json Reference https://moltfounders.com/openclaw-configuration
DigitalOcean — What Are OpenClaw Skills? A 2026 Developer’s Guide (February 25, 2026) https://www.digitalocean.com/resources/articles/what-are-openclaw-skills
OpenClaw News — The OpenClaw Ecosystem in 2026: A Complete Map of Tools, Skills, and Integrations (March 7, 2026) https://openclawnews.online/article/openclaw-ecosystem-2026
ManageMyClaw — OpenClaw Ecosystem Map 2026: All Tools https://managemyclaw.com/blog/openclaw-ecosystem-tools-map-2026/
Composio — Top 10 OpenClaw Skills to Take Your Productivity Up a Notch (March 4, 2026) https://composio.dev/content/top-openclaw-skills
Theguidex — 20 Best OpenClaw Skills in 2026 — Tested & Ranked by Category https://theguidex.com/best-openclaw-skills/
GitHub (VoltAgent) — awesome-openclaw-skills: 5,400+ skills filtered and categorized from the official OpenClaw Skills Registry https://github.com/VoltAgent/awesome-openclaw-skills
open-claw.social — Open Claw Ecosystem | 700+ Skills, ClawHub, Plugins & Extensions https://open-claw.social/open-claw-ecosystem.html
LaunchMyOpenClaw — Model Context Protocol (MCP) + OpenClaw: Connect Any Tool (2026) https://launchmyopenclaw.com/openclaw-mcp-guide/
Blink Blog — OpenClaw MCP Guide: Connect Any Tool with Model Context Protocol (April 5, 2026) https://blink.new/blog/openclaw-mcp-model-context-protocol-guide-2026
Skywork AI — The Ultimate Guide to OpenClaw and Model Context Protocol (MCP) in 2026 https://skywork.ai/skypage/en/ultimate-guide-openclaw-mcp/2037093913304317952
OpenClawMCP Blog — OpenClaw Skills: How to Find, Install, and Build Custom Skills https://openclawmcp.com/blog/openclaw-skills-guide
1Password Blog — From Magic to Malware: How OpenClaw’s Agent Skills Become an Attack Surface (February 2, 2026) https://1password.com/blog/from-magic-to-malware-how-openclaws-agent-skills-become-an-attack-surface
DEV Community (waxell) — The OpenClaw Security Crisis: 135,000 Exposed AI Agents and the Runtime Governance Gap https://dev.to/waxell/the-openclaw-security-crisis-135000-exposed-ai-agents-and-the-runtime-governance-gap-e26
Contabo Blog — OpenClaw Security Guide 2026 (February 26, 2026) https://contabo.com/blog/openclaw-security-guide-2026/
Towards AI — OpenClaw Complete Tutorial 2026: Setup, Skills, Memory, and Architecture Explained (March 7, 2026) https://pub.towardsai.net/openclaw-complete-guide-setup-tutorial-2026-14dd1ae6d1c2
GitHub (openclaw/openclaw) — Issue #31224: Allow write/edit tools to access files outside workspace directory https://github.com/openclaw/openclaw/issues/31224
Releasebot — OpenClaw Release Notes — April 2026 Latest Updates https://releasebot.io/updates/openclaw
GitHub (freema/openclaw-mcp) — MCP server for OpenClaw — secure bridge between Claude.ai and your self-hosted OpenClaw assistant https://github.com/freema/openclaw-mcp