Local Tools

This is the lightweight cousin of Skills. Skills inject instructions; local tools expose executable actions. Use local tools when the project itself wants to bolt on an action ("publish to staging", "check this lint rule", "fetch our internal status board") without touching the role config or shipping a full MCP server.

Quickstart

mkdir -p .agents/tools
cat > .agents/tools/echo <<'EOF'
#!/usr/bin/env bash
# @description Echo a message back, optionally uppercased.
# @param *message string The text to echo
# @param uppercase boolean Uppercase the output

if [[ "${OCTOMIND_PARAM_UPPERCASE:-false}" == "true" ]]; then
  printf '%s\n' "$OCTOMIND_PARAM_MESSAGE" | tr '[:lower:]' '[:upper:]'
else
  printf '%s\n' "$OCTOMIND_PARAM_MESSAGE"
fi
EOF
chmod +x .agents/tools/echo

octomind run developer:general

In the session, the model now sees echo under server local.

File Contract

Any #-comment language works (bash, python, ruby, lua, perl, R, julia, awk, …). For // use Node/Deno (the interpreter strips the shebang itself); for -- use Lua/Haskell/SQL-shell wrappers.

Header Schema

#!/usr/bin/env bash
# @description Short summary the model sees in the tool list. Continuation
# lines without an @ tag append to the previous tag — keep multi-line
# descriptions readable.
# @param *target string Path to operate on
# @param force boolean Overwrite if the destination exists
# @param count integer Number of iterations

Tags

Unknown tags are ignored with a debug log so the format can grow without breaking existing tools.

Parameter syntax

@param [*]NAME TYPE DESCRIPTION...

• Required — prefix the name with * (e.g. *target). Mirrors how octomind renders required params in /tools output.
• Optional — no prefix. This is the default.
• TYPE — one of string, number, integer, boolean, array, object. Common aliases (str, int, bool, list, obj) are normalized. Unknown types fall back to string.
• DESCRIPTION — everything after the type, joined with single spaces. Shown in the tool's parameter docs.

Example with all flavors:

# @param *target string  Required path argument
# @param force boolean   Optional flag (no * prefix)
# @param count integer   Optional, default behavior left to the script
# @param tags array      Optional list, JSON-encoded on stdin

Schema generation

The header is converted to a standard JSON-Schema tool definition:

{
  "name": "echo",
  "description": "Echo a message back, optionally uppercased.",
  "parameters": {
    "type": "object",
    "properties": {
      "message":   {"type": "string",  "description": "The text to echo"},
      "uppercase": {"type": "boolean", "description": "Uppercase the output"}
    },
    "required": ["message"]
  }
}

The model's harness validates against this schema before the tool runs — required-param enforcement, type checking, and per-tool documentation come for free.

Calling Convention

When the model invokes the tool, octomind spawns the script with:

Pick whichever input style fits the language. Bash scripts usually read env vars; Python scripts often parse stdin JSON. Both arrive every call.

Bash example (env-driven)

#!/usr/bin/env bash
# @description Greet someone politely.
# @param *who string Person to greet
# @param shout boolean Yell the greeting
set -euo pipefail
greeting="Hello, ${OCTOMIND_PARAM_WHO}"
[[ "${OCTOMIND_PARAM_SHOUT:-false}" == "true" ]] && greeting="${greeting^^}!"
printf '%s\n' "$greeting"

Python example (stdin JSON)

#!/usr/bin/env python3
# @description Sum a list of integers.
# @param *values array JSON list of integers, e.g. [1,2,3]
import json, sys
params = json.load(sys.stdin)
print(sum(params["values"]))

Node example

#!/usr/bin/env node
// @description Capitalize a string.
// @param *text string Input text
let buf = '';
process.stdin.on('data', d => buf += d);
process.stdin.on('end', () => {
  const { text } = JSON.parse(buf || '{}');
  console.log(text.toUpperCase());
});

Discovery & Lifecycle

• When: every turn. Discovery is a read_dir of <workdir>/.agents/tools/ plus a header parse per file. Cheap, no caching needed.
• Where: the session's current working directory. If the workdir tool changes the directory mid-session, the next turn's tool list reflects the new location.
• Always-on: appended to every role's tool list automatically. There is no [mcp.servers] entry to add and no allowed_tools filter — local tools are role-agnostic by design (matches the OCTOMIND_SKILLS shape, but driven by file presence rather than env).
• Lowest priority on collision: if a local tool's name matches a config-defined or dynamic tool, the config/dynamic tool wins. You can't accidentally hijack shell by naming a script shell.
• Hot reload: edit a file and save — the next tool call sees the new schema/body. No session restart needed.

Errors and Edge Cases

Enable OCTOMIND_LOG=debug to see why specific files were skipped during discovery.

Security Notes

Local tools are arbitrary code on disk — by definition they run with the same privileges as octomind. The intent is "the project author wrote these scripts and committed them to the repo." Treat .agents/tools/ like package.json scripts: or a Makefile: trust the source.

If you check out a third-party project that ships local tools, audit them before running an octomind session there. The same auto-discovery that makes the feature pleasant also means malicious files run on first use.

Comparison

Local tools are deliberately the simplest layer — one file, one shebang, one header. Reach for the heavier mechanisms only when you outgrow them.