TOOLS.md — Tool Conventions

+15 Mana ✨
OpenClaw TOOLS.md Reference(DOCUMENTATION)OpenClaw Tool System Guide(DOCUMENTATION)

Introduction

TOOLS.md is a user-maintained bootstrap file where you document conventions, notes, and tips about the tools your agent has access to. Unlike AGENTS.md which covers operating instructions, TOOLS.md focuses specifically on how tools should be used within your workspace. It helps the agent use tools correctly when automatic documentation falls short or when your team has specific preferences about tool usage.

Key Concepts

  • Tool Documentation: User-written notes about how specific tools work and when to use them
  • Usage Conventions: Team-specific rules for tool usage, such as preferred flags, output formats, or safety constraints
  • Tool Chaining: Instructions for how tools should be combined in sequence for common workflows
  • Override Notes: Corrections or clarifications that override a tool's default behavior description
  • Per-Workspace Scope: Different workspaces can have different TOOLS.md files for different tool usage patterns

Real World Context

An agent has access to a deploy tool, a database-query tool, and a file-search tool. The deploy tool has a --dry-run flag that the team requires for all staging deployments. The database-query tool should never run DELETE statements without explicit confirmation. The file-search tool works best when given specific directory paths rather than searching the entire repository. All of these nuances live in TOOLS.md so the agent applies them automatically.

Deep Dive

TOOLS.md is optional but highly recommended when your agent uses tools with workspace-specific conventions. It lives alongside the other bootstrap files in your agent directory.

Here is an example TOOLS.md:

markdown
# Tool Conventions

## deploy
- Always use `--dry-run` first for staging environments
- Production deployments require the `--confirm` flag
- If deployment fails, check the health endpoint before retrying
- Never deploy during the maintenance window (Sundays 02:00-06:00 UTC)

## database-query
- READ queries are safe to execute without confirmation
- UPDATE and DELETE queries must be shown to the user first
- Always include a WHERE clause; never run unfiltered mutations
- Use `--format table` for queries returning fewer than 20 rows
- Use `--format csv` for larger result sets

## file-search
- Search specific directories when possible (e.g., `src/`, `internal/`)
- Avoid searching `node_modules/`, `vendor/`, or `.git/` directories
- Use glob patterns for file type filtering: `*.go`, `*.tsx`
- Combine with `grep` for content search within matched files

## code-executor
- Python code: use virtual environment at `.venv/`
- Go code: ensure `go.sum` is up to date before running
- Never execute code that modifies files outside the workspace
- Timeout: 30 seconds maximum for any execution

Each section documents a specific tool with conventions the agent should follow. The agent reads these instructions during bootstrap and applies them whenever it invokes the corresponding tool.

TOOLS.md differs from the tool's built-in description in an important way. The built-in description tells the agent what a tool does. TOOLS.md tells the agent how your team wants the tool to be used. These are complementary:

markdown
# Built-in tool description (automatic):
# "deploy: Deploys the application to the specified environment"

# TOOLS.md conventions (your additions):
## deploy
- Always use --dry-run first for staging
- Never deploy during maintenance windows
- Check health endpoint after deployment

The built-in description explains capability. Your TOOLS.md entries explain policy. Together they give the agent both the ability and the judgment to use tools correctly.

Common Pitfalls

  • Restating built-in tool descriptions: Do not duplicate what the tool already describes about itself. TOOLS.md should add conventions and constraints, not repeat basic functionality.
  • Writing tool conventions in AGENTS.md instead: Keep tool-specific guidance in TOOLS.md and general operating instructions in AGENTS.md. Mixing them makes both harder to maintain.
  • Not updating after tool changes: When a tool gets new flags or deprecated options, update TOOLS.md to reflect the current behavior.

Best Practices

  • One section per tool: Use the tool name as a Markdown header and list conventions as bullet points underneath.
  • Include safety constraints prominently: Rules about data mutation, production access, and destructive operations should be at the top of each tool's section.
  • Add examples for complex workflows: When tool chaining is common (e.g., search then deploy), document the sequence explicitly.

Summary

  • TOOLS.md documents user-maintained conventions and policies for tool usage within a workspace
  • It complements built-in tool descriptions by adding team-specific rules and constraints
  • Organize it with one section per tool, listing conventions as bullet points
  • Focus on safety constraints, usage patterns, and workflow sequences rather than restating basic tool functionality
  • Keep it updated as tools evolve and team conventions change
✓ Completed