Dynamic Tools

Dynamic Tools Reference

Runtime tool creation — define tools in ~/.opencrabs/tools.toml and they become callable immediately without restart or rebuild.

tool_manage Meta-Tool

Executor Types

Two executor types, set via the executor field:

Parameter Handling

Every tool parameter defined in [[tools.params]] becomes available in two ways:

1. $OPENCRABS_PARAMS — Environment variable pointing to a temporary JSON file containing all params with their current values. The file is created before the command runs and cleaned up after. Use with --params-file flags or read directly inside scripts:

   tomlCopy code
   command = "/usr/local/bin/mycli send --params-file \"$OPENCRABS_PARAMS\""
   

   Inside a shell script, read the file directly:

   shCopy code
   #!/bin/sh
   # $OPENCRABS_PARAMS points to a JSON file with all tool params
   action=$(jq -r '.action // "default"' "$OPENCRABS_PARAMS")
   payload=$(jq -r '.payload // empty' "$OPENCRABS_PARAMS")
   exec mycli "$action" --data "$payload"
   

2. {{param_name}} — Inline template substitution. Replaced with the string value of the parameter:

   tomlCopy code
   command = "curl -s -H \"Authorization: Bearer {{api_key}}\" {{endpoint}}"
   

Conditional Sections

Wrap template content with {{#param_name}}...{{/param_name}} to include only when the parameter is non-null and non-empty:

tomlCopy code
command = """curl -s {{#query}}-G --data-urlencode "q={{query}}"{{/query}} {{url}}"""

Coercion Rules

Each param can specify how null/empty values are handled before being written to $OPENCRABS_PARAMS:

Example:

tomlCopy code
[[tools.params]]
name = "query"
type = "string"
required = false
default = "null"
coerce_empty_to = "null"

tools.toml Format

Shell Executor

tomlCopy code
[[tools]]
name = "send_notification"
description = "Send a notification via the notification service"
executor = "shell"
enabled = true
requires_approval = true
timeout_secs = 30
command = "/usr/local/bin/notify-send --params-file \"$OPENCRABS_PARAMS\""

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

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

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

HTTP Executor

tomlCopy code
[[tools]]
name = "check_api_health"
description = "Check if the production API is responding"
executor = "http"
enabled = true
method = "GET"
url = "https://api.example.com/health"

[tools.headers]
Authorization = "Bearer {{api_key}}"

Rate Limiting

tomlCopy code
[tools.rate_limit]
requests = "10"
window = "1m"

Full Example — CLI tool with $OPENCRABS_PARAMS

tomlCopy code
[[tools]]
name = "search_index"
description = "Search indexed documents by query"
executor = "shell"
enabled = true
requires_approval = false
timeout_secs = 60
command = "/usr/local/bin/doc-search --params-file \"$OPENCRABS_PARAMS\" 2>&1"

[[tools.params]]
name = "query"
type = "string"
description = "Search text"
required = true

[[tools.params]]
name = "limit"
type = "integer"
description = "Max results to return"
required = false
default = "50"

[[tools.params]]
name = "source"
type = "string"
description = "Document source filter"
required = false
default = ""

How It Works

1. On startup, tools from tools.toml load into the ToolRegistry alongside compiled tools.
2. Dynamic tools appear in the LLM's tool list — the agent calls them autonomously.
3. Use tool_manage add to create new tools at runtime.
4. Use tool_manage reload to pick up manual edits to tools.toml.
5. Unlike commands.toml (user-triggered slash commands), these are agent-callable tools.
6. Shell commands run via sh -c — $OPENCRABS_PARAMS is set as an environment variable pointing to the real temp JSON file path. The file is cleaned up after command completion.