Skip to main content
SOUL.mdIDENTITY.mdAGENTS.mdUSER.mdTOOLS.mdMEMORY.mdHEARTBEAT.mdBOOT.md
Back to Workspace
OpenClawFile 5 of 8 · 4 fields

TOOLS.md — How & when to use tools

Governs which external tools and APIs the agent can call, under what conditions, and with what constraints — preventing runaway API usage.

Last updated: April 2026

What This File Controls

TOOLS.md governs what your agent can technically do — which external tools and APIs it can call, under what conditions, and with what constraints. Without TOOLS.md, agents with tool access burn through API quotas with random invocations, access data they should not see, or attempt actions that could have real-world consequences without safeguards.

The runtime loads TOOLS.md after AGENTS.md and uses it to build the tool permission layer. Think of it as a security policy: AGENTS.md defines what the agent should do; TOOLS.md defines what it is allowed to do technically. The gap between these two files is your attack surface.

The security-first configuration principle is: start with zero access and add only what AGENTS.md requires. Every tool permission should be justified by a specific step in AGENTS.md. If a tool is not referenced in any AGENTS.md step, it should not appear in TOOLS.md. This zero-access baseline prevents capability creep as the agent’s scope expands over time.

Why it matters: Without TOOLS.md, agents burn through API quotas with random invocations.

Field-by-Field Breakdown

4 fields that shape your agent

toolRulesRequired

When and why each tool should be invoked.

toolRules: "e.g. Only call search API when user asks a factual question..."
envConfigOptional

Environment variables and configuration the tools depend on.

envConfig: "e.g. API_KEY stored in .env, rate limit: 100/hour..."
toolConstraintsRequired

Hard limits on tool usage to prevent misuse.

toolConstraints: "e.g. Max 3 API calls per turn, no writes to production DB..."
fileConventionsOptional

File naming and storage conventions tools must follow.

fileConventions: "e.g. Logs go to /tmp/agent-logs/, use ISO 8601 dates..."

Real-World Examples

FinleyManchester · 8 people · Accounting
## toolRules
- Use GOV.UK search only for HMRC guidance and legislation lookups
- Use the client database in read-only mode for matter references
- Use Slack API for posting research summaries to #tax-queries only
- Never call any tool without a clear connection to the current research query

## envConfig
- GOV_UK_API: configured via environment variable (never hardcode)
- CLIENT_DB: read-only connection string via .env
- SLACK_BOT_TOKEN: scoped to #tax-queries channel only

## toolConstraints
- Maximum 5 GOV.UK API calls per query to prevent rate limiting
- Client database: SELECT queries only, no INSERT/UPDATE/DELETE
- Never expose raw API responses to users — always summarise
- No access to client financial records (UTRs, bank details, NI numbers)

## fileConventions
- Research outputs saved to /research/[client-ref]/[date]-[topic].md
- Use ISO 8601 dates in all filenames
- Never include client PII in filenames

Common Mistakes

Using Full tool profile without a TOOLS.md

Agents with tool access but no TOOLS.md have unrestricted capabilities. They will call every available tool as they see fit, burning through quotas and potentially accessing sensitive data. Always define explicit tool rules.

Putting actual API keys in envConfig

envConfig should reference environment variable names, not actual secrets. Hardcoded keys in TOOLS.md end up in version control, logs, and potentially the agent’s conversation output.

toolConstraints conflicting with AGENTS.md job requirements

If AGENTS.md requires the agent to update customer records but TOOLS.md restricts the database to read-only, the agent fails silently or invents workarounds. Audit both files together.

Leaving fileConventions blank for agents that write files

Without conventions, the agent creates files with inconsistent names, in unpredictable locations, with no date-stamping. This makes output impossible to find and audit.

How SetupClaw Handles This

Security is the starting point. Our deployment specialist audits every tool capability against the AGENTS.md job scope, applying a least-privilege default. Only tools required by specific AGENTS.md steps are enabled, with constraints calibrated to your data sensitivity requirements.

£770

Security audit of TOOLS vs AGENTS scope + least-privilege configuration + 22-point security checklist

£1,100

All above + tool sandboxing for phased capability rollout + staging/production split

£2,200

All above + environment-specific configurations + automated security regression tests

  • All 4 fields configured with security-first defaults
  • 22-point security audit completed and documented
  • Tool permissions justified against AGENTS.md steps
  • Environment variables documented (no hardcoded secrets)
  • File conventions established for all agent outputs

Security audit and configuration completed day 1–2. Sandboxed rollout by day 5 (Standard+).

Advanced Topics

Tool sandboxing for phased capability rollout

Rather than enabling all tools at once, use a phased rollout pattern. Start with read-only access, monitor for a week, then progressively enable write capabilities. TOOLS.md supports a sandboxed field that restricts tool access to a staging environment until explicitly promoted to production.

## toolConstraints
- PHASE 1 (week 1-2): Read-only access to Shopify, Slack monitoring only
- PHASE 2 (week 3-4): Add Slack posting to #customer-support
- PHASE 3 (month 2+): Add carrier tracking API access
- ROLLBACK: If error rate exceeds 5%, revert to previous phase

Example Configurations

Persona A — MeridianChief of Staff

# TOOLS.md -- Tool Rules

## toolRules
- Confirm attendees before scheduling any calendar event
- Use approved templates for all external communications
- Notion: read and update project boards; never delete pages
- Gmail: draft emails for review; never send without confirmation

## envConfig
- Notion API, Slack API, Gmail API, Google Calendar API
- All keys configured via environment variables

## toolConstraints
- No external emails without draft review by the principal
- No public document creation without explicit approval
- Calendar: read all; create/modify only for the principal’s calendar

## fileConventions
- Meeting notes: /meetings/[date]-[topic].md
- Action plans: /actions/[date]-[initiative].md
- Status reports: /reports/[week]-status.md
Persona B — Axiom (Veteran Growth Hacker)
# TOOLS.md -- Tool Rules

## toolRules
- Date-range bounds on all analytics queries (max 90 days)
- Use Python for statistical analysis and significance testing
- Mixpanel for funnel analysis; PostgreSQL for cohort queries
- Google/Meta Ads: read-only access for campaign performance data

## envConfig
- Mixpanel API, PostgreSQL (read-only), Google Ads API, Meta Ads API
- All keys configured via environment variables

## toolConstraints
- No modifying live experiments or ad campaigns
- No production PII access — use anonymised datasets only
- Maximum 20 analytics queries per session
- No budget allocation changes without escalation

## fileConventions
- Experiment briefs: /experiments/[date]-[hypothesis].md
- Post-mortems: /experiments/[date]-[hypothesis]-results.md
- Growth playbook updates: /playbook/[topic].md
Persona C — Lumen (Scientific Researcher)
# TOOLS.md -- Tool Rules

## toolRules
- Publication date filters on all database searches (default: last 5 years)
- Cross-reference at least 2 sources before including in synthesis
- PubMed for biomedical literature; Google Scholar for broader search
- Zotero for citation management and bibliography generation

## envConfig
- PubMed API, Google Scholar API, Zotero API
- All keys configured via environment variables

## toolConstraints
- No summarising abstracts as if they were full papers
- Flag all preprints and non-peer-reviewed sources explicitly
- Maximum 25 search queries per research session
- Never cache full-text articles locally

## fileConventions
- Literature reviews: /research/[topic]/[date]-review.md
- Evidence tables: /research/[topic]/[date]-evidence.md
- Bibliographies: /research/[topic]/bibliography.bib
Persona D — Narrative (Senior Content Creator)
# TOOLS.md -- Tool Rules

## toolRules
- SEO tools (Ahrefs) for keyword research and intent analysis only
- Match posting times to platform-specific engagement windows
- WordPress for content management; Buffer for social scheduling
- ConvertKit for email list management; GA4 for performance tracking

## envConfig
- WordPress API, Ahrefs API, Buffer API, ConvertKit API, GA4 API
- All keys configured via environment variables

## toolConstraints
- No direct publishing to any platform — always draft and queue
- No auto-send emails without human review
- No competitor names in content without legal review
- Maximum 10 SEO tool queries per content piece

## fileConventions
- Content briefs: /content/briefs/[date]-[slug].md
- Drafts: /content/drafts/[date]-[slug].md
- Performance reports: /content/reports/[month]-performance.md
Persona E — Architect (Chief Engineer)
# TOOLS.md -- Tool Rules

## toolRules
- Run linter before executing any code changes
- Test on staging environment before any migration
- GitHub for code review and PR management
- Datadog for monitoring and alerting; AWS EKS for deployment status

## envConfig
- GitHub API, GitHub Actions, ArgoCD, AWS EKS, Datadog API
- All keys configured via environment variables

## toolConstraints
- No direct push to main branch — all changes via pull request
- No database migrations without a documented rollback plan
- No access to production secrets or credentials
- Maximum 5 deployment actions per session

## fileConventions
- ADRs: /docs/adr/[number]-[title].md
- Incident reports: /incidents/[date]-[severity]-[title].md
- Design docs: /docs/design/[date]-[feature].md

Skip the complexity — let us configure your workspace

We handle all 8 files, including TOOLS.md.

Book a Setup Call