ContenoxContenox

What are Tools?

Tools are the mechanism by which Contenox gives a model access to real-world actions. Instead of generating text, the model calls a tools to read files, run commands, query APIs, or fire HTTP requests — and gets the result back as context for its next reply.

How it works

Chain starts
  └─ FetchTools: each listed tools returns its tool schemas
       └─ Schemas are sent to the model alongside the prompt
            └─ Model returns a tool call
                 └─ execute_tool_calls runs the tools
                      └─ Result appended to history → model continues

In your chain JSON, specify which tools the task can use via the execute_config.tools allowlist:

"execute_config": {
  "model": "qwen2.5:7b",
  "provider": "ollama",
  "tools": ["local_fs", "nws", "local_shell"]
}

Pattern support:

ValueMeaning
field absentAll registered tools
[]No tools exposed to the model
["*"]All registered tool (explicit)
["a", "b"]Only the named tools
["*", "!local_shell"]All except local_shell

Unknown names in an exact list are silently ignored — if local_shell is disabled the chain still runs.

Use {{toolservice:list}} in your system_instruction to inject the live tool manifest. This macro respects the task's tools allowlist — the model only sees what the task permits:

"system_instruction": "You are a helpful assistant. Available tools: {{toolservice:list}}."

Template variables

System instructions and prompt_template fields support the following macros:

MacroReturns
{{var:<name>}}Value of the named template variable supplied by the caller
{{now}}Current time in RFC3339 format
{{now:<layout>}}Current time in Go time layout (e.g. {{now:2006-01-02}})
{{chain:id}}ID of the currently executing chain
{{toolservice:list}}JSON object mapping tools name → array of tool names (respects task tools allowlist)
{{toolservice:tools}}JSON array of tools names available to the task
{{toolservice:tools <name>}}JSON array of tool names for a specific tool

Tools types

Contenox ships with built-in local tools and supports unlimited remote tools:

Tools nameTypeAlways availableWhat it does
local_fsLocal✅Read, write, and search files within a configured directory (8 verb-specific tools, read-before-write contract for mutations)
webtoolsLocal✅Call HTTP endpoints — web_get, web_head, web_post, web_put, web_patch, web_delete. SSRF-guarded; mutating verbs HITL-approve by default.
local_shellLocalOpt-in (--shell)Run arbitrary shell commands
sshLocal✅Run a command on a remote host over SSH
printLocal✅Append a message to the chat history or return it as a string
echoLocal✅Echo the input back (useful for debugging chains)
your nameRemoteRegister with contenox tools addAny OpenAPI v3 service

Choosing the right tools

  • local_fs — best for code analysis, file editing, report generation. Prefer over local_shell for file ops; the read-before-write contract and sandbox guard against confabulated edits.
  • webtools — when the model needs to call HTTP. Use web_get / web_head for retrieval; mutating verbs trigger HITL approval by default.
  • local_shell — full power; use only in trusted, sandboxed environments. Reach for it for build / test / git, not for cat / grep / sed against project files.
  • ssh — run commands on remote machines from within a chain
  • print / echo — inject messages or inspect task output during development
  • Remote tools — turn any OpenAPI service into an agent tool; ideal for internal APIs, SaaS integrations, and team-shared tools

Further reading

Annotated ExamplesRemote Tools