agents-store TOOLS.md Optimization Guide
TOOLS.md contains environment-specific notes about the tools available to the agent. It does NOT control tool access (that's in openclaw.json) — it provides guidance on HOW to use tools effectively in this specific environment.
Official Template
# TOOLS.md - Local Notes
Skills define HOW tools work. This file is for YOUR specifics.
The docs say: "Add whatever helps you do your job. This is your cheat sheet."
What Goes Here
| Category | Examples |
|---|---|
| Search tool priorities | "Use Firecrawl for Ukrainian sites, EXA for English queries" |
| Camera names/locations | "Front door camera: cam-01" |
| SSH hosts and aliases | "Production: ssh prod@10.0.1.5" |
| TTS preferences | "Use ElevenLabs voice 'Rachel' for notifications" |
| Speaker/room names | "Living room speaker: sonos-living" |
| Device nicknames | "Desk lamp = hue-light-3" |
| API endpoints | Custom internal API URLs |
| Database connections | Connection string references (not credentials!) |
Why Separate from Skills?
"Skills are shared. Your setup is yours." This separation enables:
- Updating skills without losing environment notes
- Sharing skills without exposing infrastructure
- Different agents using same skills with different tool configs
Search Tool Priority Template
Data-driven tool priority based on session analysis:
## Search Tools (priority order for [domain])
1. **Firecrawl** — best for [language/region] sites. [X]% success rate.
Use for: scraping full page content, crawling sites
Command: `firecrawl search "query" --scrape --limit 5`
2. **Perplexity** — good for overview + synthesis.
Use for: quick summaries, multi-source answers
3. **EXA** — best for English queries. NOTE: [X]% fail rate on [language] text.
Workaround: translate queries to English first
4. **Deep Research** — for comprehensive analysis (combines multiple providers).
Use for: research tasks requiring 3+ sources
Optimizing TOOLS.md from Session Data
Analyze session logs to determine optimal tool configuration:
- Most used tools — ensure they're documented with correct syntax
- Tools with high error rates — add workarounds and alternatives
- Tools never used — consider if they're needed, or if agent doesn't know about them
- Domain-specific tools — add usage notes for specialized tools
What Data Is Needed
| Input | Source | What It Determines |
|---|---|---|
| Installed skills | ls workspace/skills/ + extraDirs |
Available tools |
| Skill SKILL.md files | Read each SKILL.md | Commands and syntax |
| API endpoints | Client infrastructure | Custom URLs |
| Search priority | Domain needs | Which tool first |
| Tool performance | Session log analysis | Success/fail rates |
| Custom scripts | workspace/scripts/ | CLI utilities |
Signals from Sessions That Improve TOOLS.md
- Tool call fails repeatedly → add workaround note
- Agent uses suboptimal tool → add priority guidance
- New skill installed → add usage notes
- Agent doesn't know about a tool → document it
- Tool works differently than expected → add clarification
Best Practices
- Lead with the most-used tools
- Include success rates when available (from session analysis)
- Add workarounds for known issues
- Keep credentials out — reference env vars instead
- Update when skills or infrastructure change
- Group by function (search, media, communication, home automation)