Tools

The tools command group lets you discover and execute the backend tools registered with Hutly’s tool registry. These are the same configurable tools that agents and workflows invoke at runtime: each tool has a config schema (how the tool factory is built) and produces one or more instances, each with its own arguments schema and output schema.

A typical flow is: tools list to find a tool code, tools describe to read its config schema and resolve instances, then tools execute to call a single instance.

All tools subcommands operate against the organization resolved from your configuration (HUTLY_ORG_ID / .hutlyrc.yaml) and authenticate with your HUTLY_API_KEY. Your key’s role within that organization governs which tools you can list and execute — tools gated to higher roles return an error from the registry.

Output is JSON by default. The --json flag is accepted everywhere as a no-op for compatibility, and --pretty pretty-prints the JSON.

tools list

Lists configurable tool codes alongside their config schemas. By default, workflow-only tools are excluded.

hutly tools list
hutly tools list --pretty
hutly tools list --include-workflow-tools

tools describe

Describes a single tool by its toolCode. Returns the tool’s config schema. When you also pass --config (a JSON object matching that config schema), the response additionally includes the resolved tool instances — each with its name, description, parameters (arguments) schema, and output schema. Use those instance names with tools execute.

# Config schema only
hutly tools describe knowledgebase-search --pretty

# Resolve instances by supplying a config
hutly tools describe knowledgebase-search \
  --config '{"knowledgebaseIds":["kb_123"]}' \
  --pretty

tools execute

Executes a single tool instance. The tool factory is built from --config, the named instance is picked, and its function is called with --args. Both --config and --args are required and must be valid JSON objects — discover their shapes with tools describe <toolCode> (and tools describe <toolCode> --config … for the instance arguments schema).

hutly tools execute knowledgebase-search search \
  --config '{"knowledgebaseIds":["kb_123"]}' \
  --args '{"query":"notice periods for fixed-term leases"}' \
  --pretty

If the instance name does not exist, or the arguments fail schema validation, the response reports the failure — including availableInstances and/or validationIssues to correct the call.

Some tools key their behaviour on a runtime context (chat-mode tools resolve a conversation; workflow-mode tools resolve a workflow execution). When run inside a Hutly sandbox, this context is read from the HUTLY_* environment variables automatically. The flags below override those values for a single call — useful when driving the CLI directly or from a workflow bash node.