Agent Toolbelt & Local Tools

By default, every agent you create has no tools at all. Grant only what each agent actually needs.

There are two independent systems. Local tools control Huginn’s built-in capabilities — reading files, writing code, running shell commands. The toolbelt controls external connections — GitHub, Slack, AWS, Jira, and other integrations. Each is configured separately on the agent’s JSON definition.

Why this matters

Different agents do different jobs. A code reviewer only needs to read. A DevOps agent needs AWS. A documentation agent should never touch production.

If you give every agent access to everything, a single bad prompt — or a prompt injection attack — can cause real damage. An agent that can’t see your AWS connection can’t accidentally terminate an EC2 instance, no matter what instruction it receives.

Minimum access is not just a security practice. It also prevents agents from reaching for tools they don’t need, which keeps their responses more focused and their token usage lower.

Local Tools

Local tools are Huginn’s built-in primitives: file I/O, code search, git operations, shell execution.

Default behavior

A new agent has local_tools: [] — no built-in tools at all. It can reason and respond, but it cannot read a file, search code, or run a command.

Set local_tools to ["*"] to grant everything (useful for a general-purpose primary agent). Or list exactly what the agent needs.

Tool categories

Read tools — never require user approval

Write tools — require user approval unless auto-run is on

Execute tools — always require approval unless auto-run is on

Example: read-only reviewer

This agent can inspect code and git history but cannot write a single byte.

{
  "name": "Elena",
  "local_tools": [
    "read_file", "list_dir", "grep", "search_files",
    "git_status", "git_diff", "git_log", "git_blame",
    "find_definition", "list_symbols"
  ]
}

Example: full coding agent

This agent can read, write, commit, run shell commands, and run tests.

{
  "name": "Steve",
  "local_tools": [
    "read_file", "list_dir", "grep", "search_files",
    "write_file", "edit_file",
    "git_status", "git_diff", "git_commit",
    "bash", "run_tests"
  ]
}

Toolbelt

The toolbelt controls which external connections each agent can use. Connections are integrations you’ve set up in Huginn — GitHub, Slack, AWS, Jira, Google Workspace, and so on.

Default behavior

An agent with an empty toolbelt array has access to all configured connections on your machine. This is the default for backward compatibility.

Explicitly set the toolbelt to restrict access to only what the agent needs.

The approval gate

Each connection in the toolbelt has an optional approval_gate field.

• approval_gate: false — the agent uses this connection freely, including in headless and automated mode.
• approval_gate: true — reads are always allowed. Any write or action pauses and shows you a prompt, even in auto-run mode.

When the gate fires, you see something like this:

DevOps agent wants to: aws_ec2_terminate_instance
Instance: i-0abc123def456
[Allow once]  [Allow all for this session]  [Deny]

The approval gate cannot be bypassed by automation flags. Even --dangerously-skip-permissions does not override a connection’s approval_gate: true setting. The gate is a per-agent policy, not a per-run decision.

Example: DevOps agent

Full AWS access (gated) plus GitHub and Slack.

{
  "name": "DevOps",
  "toolbelt": [
    {
      "connection_id": "aws-prod",
      "provider": "aws",
      "approval_gate": true
    },
    {
      "connection_id": "github-myorg",
      "provider": "github",
      "approval_gate": false
    },
    {
      "connection_id": "slack-company",
      "provider": "slack",
      "approval_gate": false
    }
  ]
}

Example: security reviewer

Can read GitHub issues and pull requests. Cannot write to Slack or touch AWS.

{
  "name": "Elena",
  "toolbelt": [
    {
      "connection_id": "github-myorg",
      "provider": "github",
      "approval_gate": false
    }
  ]
}

Toolbelt field reference

Provider reference

Complete agent example

A security reviewer with both local_tools and toolbelt configured. It can read code and inspect GitHub, nothing else.

{
  "name": "Elena",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "api_key": "$ANTHROPIC_API_KEY",
  "system_prompt": "You are Elena, a security-focused code reviewer. You look for injection vulnerabilities, authentication flaws, insecure defaults, and data exposure risks. You do not write new code — only review and advise.",
  "local_tools": [
    "read_file", "list_dir", "grep", "search_files",
    "git_diff", "git_log", "git_blame",
    "gh_pr_view", "gh_pr_diff", "gh_issue_view"
  ],
  "toolbelt": [
    {
      "connection_id": "github-myorg",
      "provider": "github",
      "approval_gate": false
    }
  ],
  "description": "Security reviewer. Finds vulnerabilities and authentication flaws. Read-only — does not write files or execute commands."
}

Save this to ~/.huginn/agents/elena.json. The web UI picks it up immediately. The TUI reads it on next launch.

What happens when an agent tries a blocked tool

If an agent tries to call a tool that is not in its local_tools list, it receives a clean rejection message and reports back to you what happened.

The model never learns the blocked tool exists. At session start, Huginn sends only the schemas for tools the agent is allowed to use. A tool with no schema is invisible to the model — it cannot even try to call it.

For toolbelt connections, the same logic applies. An agent without aws-prod in its toolbelt has no AWS tool schemas. It cannot discover, attempt, or be tricked into using AWS.

If you want to verify your restrictions, ask the agent to do something it should not be able to do. It should tell you it does not have access to that tool or connection, then either ask you for an alternative approach or explain what it would need to complete the task.

How local tools and the toolbelt interact

These two controls are independent layers. You can mix and match them freely.

An agent could have full built-in tool access but a locked-down toolbelt — or vice versa. Configure each based on the agent’s actual job.

Best practices

Give each agent only what it actually needs. A documentation agent does not need GitHub write access. A data analyst does not need AWS.

Enable the approval gate on every production connection. Any agent that can reach a production AWS account, your primary GitHub org, or company Slack should have approval_gate: true. You only add a checkpoint for writes — reads stay free.

Use separate connection IDs for prod and non-prod. Set up aws-prod and aws-staging as distinct connections. Assign only aws-staging to agents that do not need production access.

Start with the minimum and add. It is easier to add a tool after noticing the agent needs it than to contain the damage after a write tool was granted unnecessarily.