OpenParable
Skip to content
← Back to skills

Dynamic Tools

Development
dynamic-tools

Dynamic Tools is an Agent Skill for development published in the adolfousier/opencrabs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Runtime tool management with tool_manage and tools.toml format. Create, enable, disable, reload tools without restart. (/dynamic-tools, tool_manage, runtime tools)

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/adolfousier/opencrabs/blob/HEAD/src/docs/reference/templates/skills/dynamic-tools/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/dynamic-tools, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

ActionRequiredWhat
list—Show all dynamic tools with enabled/disabled status
addname, description, executor, method/commandCreate new tool (persists to tools.toml)
removenameDelete a tool
enable / disablenameToggle without removing
reload—Hot-reload from tools.toml

Executor Types

Two executor types, set via the executor field:

ExecutorField
executor = "shell"command — shell command string
executor = "http"method, url — HTTP method and endpoint

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:

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

    Inside a shell script, read the file directly:

    #!/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:

    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:

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:

coerce_empty_to / coerce_null_toEffect
"keep" (default)Pass null/empty as-is into the JSON
"omit"Drop the key entirely from $OPENCRABS_PARAMS JSON
"null"Convert to JSON null
"error"Reject the tool call with a validation error

Example:

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

tools.toml Format

Shell Executor

[[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

[[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

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

Full Example — CLI tool with $OPENCRABS_PARAMS

[[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.