TOOLS.md is the 📝OpenClaw file that inventories the external capabilities — 📝APIs, functions, and utilities — an agent is authorized to call, along with the documentation and procedures required to use each one correctly.

In the OpenClaw architecture, TOOLS.md functions as the agent's "hands": the manifest of every external system the agent can reach, paired with inline usage instructions. When an agent needs to search a knowledge base, drive a browser, execute code, or hit a third-party service, it consults TOOLS.md to learn both what is available and how to call it. Tools in this model are protocols, not modules — contextual instructions loaded into the agent's working memory rather than executable abstractions the agent imports.

Key Facts

Category: OpenClaw agent configuration file
Role: Inventory of external capabilities and usage protocols
Format: Markdown with inline procedure blocks
Companion files: 📝SKILLS.md (know-how), SOUL.md (values), HEARTBEAT.md (operating cadence)
Location: Repository root of any OpenClaw workspace

How It Works

Inventory — each tool is listed with a name, purpose, authentication requirements, and a short rationale for when to use it
Inline procedures — instead of wrapping tools in code, TOOLS.md spells out the exact steps in natural language: "when you need X, run this command with these arguments"
Loaded into context — relevant sections are pulled into the agent's working memory at runtime, so the agent reasons over tool descriptions the same way it reasons over any other context
Authorization by inclusion — a tool that is not in TOOLS.md is not available to the agent. Editing the file is how an operator grants or revokes capability
Composable with skills — where SKILLS.md describes patterns of reasoning, TOOLS.md describes the outward-facing levers those skills pull

Why It Matters

Most agent frameworks treat tools as imported functions, which makes them invisible to the model once compiled. OpenClaw inverts this: tools are knowledge, not code. The agent reads its own TOOLS.md the way a new employee reads a runbook, and the file is editable by the operator in real time. This makes capability management legible, auditable, and negotiable — an agent that uses a tool incorrectly can be corrected by rewriting a paragraph rather than shipping a new release.

FAQ

What goes in TOOLS.md versus SKILLS.md?

TOOLS.md lists what the agent can reach (browsers, APIs, 📝Command Line Interface (CLI) binaries, knowledge bases). 📝SKILLS.md lists how the agent approaches problems (debugging patterns, writing heuristics, investigation protocols).

How does an operator add a new tool?

Edit TOOLS.md, add a section with the tool's name, purpose, and usage instructions, and refresh the agent's context. No code changes required.

Is TOOLS.md agent-specific or shared?

Both. Each OpenClaw workspace has its own TOOLS.md; specialized agents within a workspace can inherit from the root file and override with their own.

Why write tools as prose instead of function definitions?

Because the agent reads natural language far better than it reads schemas, and because tools that live in prose can be edited, debated, and refined by operators without a release cycle. The tradeoff is that the agent must understand and follow steps rather than calling a deterministic API.

📝OpenClaw — the agent runtime TOOLS.md configures
📝Markdown-File Agent Definition — the design pattern TOOLS.md belongs to
📝SKILLS.md — parallel file describing reasoning patterns and heuristics
📝TOOLS.md vs SKILLS.md vs MCP — clarifier disambiguating these three concepts
📝Model Context Protocol (MCP) — complementary standard for connecting agents to external tools programmatically