Skip to content
niminal

External tools

External tools are short-lived executables described by tool.json. niminal starts one only when the model calls it, sends the tool arguments as one JSON object on stdin, and expects one JSON value on stdout.

Manifest

Section titled “Manifest”

Put a tool in a directory with a tool.json beside the executable:

{
  "name": "word_count",
  "description": "Count words in text.",
  "command": ["./word-count"],
  "input_schema": {
    "type": "object",
    "properties": {"text": {"type": "string"}},
    "required": ["text"]
  },
  "timeout_seconds": 10,
  "capabilities": ["read"]
}

Required fields: name, description, command, and input_schema.

command must be a non-empty string array. The first item resolves relative to the manifest directory; later items are fixed arguments. The process runs in the workspace.

timeout_seconds defaults to 30. Output is capped at 100,000 bytes.

Capabilities

Section titled “Capabilities”

Supported values: read, write, shell, network, and user.

Tools that declare only read (and optionally user) are treated as read-only and auto-approved in the TUI like built-in read tools.

Discovery paths

Section titled “Discovery paths”

Global tools (always loaded; later paths win on name conflicts):

~/.niminal/tools/NAME/tool.json
~/.agents/tools/NAME/tool.json

Project tools (trusted workspace only):

<workspace>/.agent/tools/NAME/tool.json
<workspace>/.agents/tools/NAME/tool.json
<workspace>/.niminal/tools/NAME/tool.json

Names that collide with built-in tools are skipped with a warning. Use /reload after changing a manifest.

Next steps

Section titled “Next steps”