tools.toml.example

# OpenCrabs Dynamic Tools
# Copy to ~/.opencrabs/tools.toml and customize.
#
# These are runtime-defined tools the agent can call autonomously.
# Unlike commands.toml (user-triggered slash commands), these appear
# in the LLM's tool list and the agent decides when to use them.
#
# Changes are hot-reloaded — no restart needed.
# The agent can also manage tools via the `tool_manage` meta-tool.

# --- HTTP Tools ---

[[tools]]
name = "health_check"
description = "Check if a service endpoint is healthy"
executor = "http"
method = "GET"
url = "https://{{host}}/health"
timeout_secs = 10
requires_approval = false
enabled = true

[[tools.params]]
name = "host"
type = "string"
description = "Hostname or IP to check (e.g. api.example.com)"
required = true

[[tools]]
name = "github_api"
description = "Query the GitHub REST API"
executor = "http"
method = "GET"
url = "https://api.github.com/{{endpoint}}"
headers = { "Authorization" = "Bearer {{token}}", "Accept" = "application/vnd.github+json" }
timeout_secs = 15
requires_approval = true
enabled = true

[[tools.params]]
name = "endpoint"
type = "string"
description = "API path (e.g. repos/owner/repo/issues)"
required = true

[[tools.params]]
name = "token"
type = "string"
description = "GitHub personal access token"
required = true

[[tools]]
name = "webhook_notify"
description = "Send a notification to a webhook URL"
executor = "http"
method = "POST"
url = "{{webhook_url}}"
headers = { "Content-Type" = "application/json" }
timeout_secs = 10
requires_approval = true
enabled = false

[[tools.params]]
name = "webhook_url"
type = "string"
description = "Full webhook URL"
required = true

# --- Shell Tools ---

[[tools]]
name = "disk_usage"
description = "Show disk usage for a directory"
executor = "shell"
command = "du -sh {{path}} 2>/dev/null || echo 'Path not found'"
timeout_secs = 10
requires_approval = false
enabled = true

[[tools.params]]
name = "path"
type = "string"
description = "Directory path to check"
required = true

[[tools]]
name = "docker_status"
description = "List running Docker containers"
executor = "shell"
command = "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
timeout_secs = 10
requires_approval = false
enabled = true

[[tools]]
name = "git_log_summary"
description = "Show recent git commits in a repository"
executor = "shell"
command = "cd {{repo_path}} && git log --oneline -{{count}}"
timeout_secs = 10
requires_approval = false
enabled = true

[[tools.params]]
name = "repo_path"
type = "string"
description = "Path to the git repository"
required = true

[[tools.params]]
name = "count"
type = "string"
description = "Number of commits to show"
required = false

[[tools]]
name = "deploy_staging"
description = "Deploy a branch to the staging environment"
executor = "shell"
command = "cd ~/project && ./deploy.sh {{branch}} staging"
timeout_secs = 120
requires_approval = true
enabled = false

[[tools.params]]
name = "branch"
type = "string"
description = "Git branch to deploy"
required = true

# --- Advanced: $OPENCRABS_PARAMS ---
#
# For tools with many parameters or values that may contain spaces,
# quotes, or special characters, use --params-file instead of inline
# {{param}} substitution. OpenCrabs writes all coerced parameters to
# a temp JSON file and sets $OPENCRABS_PARAMS to its path. Your CLI
# reads it via --params-file.

[[tools]]
name = "notify"
description = "Send a notification via an external service"
executor = "shell"
command = "/usr/local/bin/myapp-cli notify --params-file \"$OPENCRABS_PARAMS\""
timeout_secs = 30
requires_approval = true
enabled = false

[[tools.params]]
name = "channel"
type = "string"
description = "Notification channel: email, slack, push"
required = true

[[tools.params]]
name = "message"
type = "string"
description = "Message text"
required = true

[[tools.params]]
name = "priority"
type = "string"
description = "Priority level: low, normal, high"
required = false
default = "normal"

[[tools.params]]
name = "attachments"
type = "array"
description = "File paths or URLs to attach"
required = false
coerce_empty_to = "omit"

# --- Built-in tools (no config needed) ---
#
# OpenCrabs ships 40+ compiled-in tools that appear automatically in
# the LLM tool list — file/code (read_file, write_file, edit_file,
# bash, ls, glob, grep, ...), search (memory_search, session_search,
# web_search, exa_search, brave_search), channel I/O (telegram_send,
# discord_send, slack_send, trello_send, channel_search, a2a_send),
# agent/session (plan, task_manager, config_manager, cron_manage,
# rename_session, follow_up_question, slash_command, load_brain_file,
# write_opencrabs_file), and RSI (feedback_record, feedback_analyze,
# self_improve). See the "Tool System" section in README.md for the
# full catalog.
#
# Tool executions are auto-recorded to the feedback ledger — the agent
# also calls feedback_record / feedback_analyze manually when it
# notices patterns worth tracking.
#
# This file is only for DYNAMIC tools (HTTP and shell executors)
# defined at runtime per project. The agent can also create, list,
# enable/disable, and remove dynamic tools via the `tool_manage`
# meta-tool — changes hot-reload without a restart.

# --- Field Reference ---
#
# name             (required)  Tool name — used by the agent to call it
# description      (required)  What the tool does — shown to the LLM
# executor         (required)  "http" or "shell"
# enabled          (optional)  true/false, default: true
# requires_approval (optional) true/false, default: true
# timeout_secs     (optional)  Execution timeout, default: 30
# params           (optional)  Parameter definitions
#                              (name, type, description, required, default,
#                               coerce_empty_to, coerce_null_to)
#
# HTTP-specific:
#   method         "GET", "POST", "PUT", "DELETE", etc.
#   url            URL with {{param}} template variables
#   headers        Key-value map, supports {{param}} substitution
#
# Shell-specific:
#   command         Shell command — supports `{{param}}` for simple
#                   substitution AND `"$OPENCRABS_PARAMS"` (path to
#                   a temp JSON file with all coerced params) for
#                   tools with complex or many parameters.
#                   Supports `{{#name}}…{{/name}}` conditional blocks
#                   that render only when `name` is present in the
#                   coerced params — pair with `coerce_empty_to = "omit"`
#                   so a flag like `{{#ids}}--ids {{ids}}{{/ids}}` is
#                   dropped entirely when `ids` is an empty array.
#
# Per-parameter coercion (issue #95):
#   coerce_empty_to  (optional) What to do when the value is an empty
#                               array, empty object, or empty string.
#                               One of: "keep" (default), "omit",
#                               "null", "error".
#   coerce_null_to   (optional) What to do when the value is JSON
#                               `null`. Same enum as coerce_empty_to.
#
#   Example:
#
#     [[tools.params]]
#     name = "ids"
#     type = "array"
#     coerce_empty_to = "omit"  # [] drops the key from the payload
#     coerce_null_to  = "error" # null → tool returns an error
#
#   Existing tools without these fields keep the pre-coercion behavior.