How to Document Your Local Tools in TOOLS.md

I often find myself repeating the same instructions to AI assistants about how I want my local scripts to run. It is a common frustration to have a perfect set of tools ready, but the assistant lacks the context to use them the way you prefer. You want the AI to follow your specific rules without you having to explain them in every single prompt.

In OpenClaw, you can handle this by using the TOOLS.md file. I recommend using this file to store your personal notes and conventions for external tools. It is important to remember that this file is for your notes only; it does not define the tools themselves, as OpenClaw provides those internally.

What You’ll Need

• An editable TOOLS.md file in your project.
• OpenClaw’s built-in tools.

Quick Start

To get started, open your TOOLS.md and add notes about how you want the assistant to behave. Here are two examples of how to format these notes based on the supported tools:

1. Set Rules for Messaging (imsg)

If you use the iMessage tool, you should define your safety and style preferences:

### imsg
- Send an iMessage/SMS: describe who/what, confirm before sending.
- Prefer short messages; avoid sending secrets.

2. Set Rules for Speech (sag)

For text-to-speech tools, specify the parameters the assistant needs to provide:

### sag
- Text-to-speech: specify voice, target speaker/room, and whether to stream.

Troubleshooting

If you run into issues, keep these points from the documentation in mind:

• Tool not found: Adding a note to TOOLS.md does not create a new tool. This file only provides context for tools that OpenClaw already provides internally.
• Assistant ignoring notes: Ensure your notes are clear and placed under the correct heading for the tool you are using.

I find that keeping these notes brief helps the assistant follow your local conventions more accurately. If you need more help setting up your environment, check out the AI Setup Assistant.

What’s Next

• Internal Tool Definitions
• Configuration Best Practices