Tools

Tools are configured through the versioned tools field on POST /v1/agents and POST /v1/agents/{agentId}.

Tool config types

The tools array accepts three config types:

Type	Executes in	Purpose
`agent_toolset`	Managed agent environment	Enable and permission built-in toolsets.
`mcp_toolset`	Configured MCP server	Enable and permission tools from an MCP server.
`custom_tool`	Your application	Expose application-owned actions to the model through session events.

Built-in agent toolsets

Managed agents expose these built-in toolsets. Configure them by toolset name in configs; a toolset with enabled: false is invisible to the model.

Toolset	Tools	Description
`clarify`	`clarify`	Ask the user a question when the agent needs clarification or approval context.
`vision`	`vision_analyze`	Analyze an image from a URL, local path, or data URL.
`skills`	`skills_list`, `skill_view`, `skill_manage`	List, inspect, create, update, or delete agent skills.
`todo`	`todo`	Read or update the session task list.
`memory`	`memory`	Save, replace, or remove persistent memory and user-profile facts.
`session_search`	`session_search`	Search previous conversations for relevant context.
`code_execution`	`execute_code`	Run Python code that can call agent tools programmatically.
`web`	`web_search`, `web_extract`	Search the web and extract page contents.
`terminal`	`terminal`, `process`	Run shell commands and manage background processes in an isolated environment.
`file`	`read_file`, `write_file`, `patch`, `search_files`	Read, write, patch, and search files in the agent workspace.

Built-in toolset config

{
  "type": "agent_toolset",
  "defaultConfig": {
    "enabled": true,
    "permissionPolicy": { "type": "always_allow" }
  },
  "configs": [
    {
      "name": "terminal",
      "enabled": true,
      "permissionPolicy": { "type": "always_ask" }
    }
  ]
}

Field	Type	Required	Description
`type`	string	Yes	Must be `agent_toolset`.
`defaultConfig`	object	No	Default enablement and permission policy.
`configs`	object[]	No	Per-toolset overrides by built-in toolset name.

MCP toolset config

MCP tools are attached by pairing an mcpServers entry with an mcp_toolset entry in tools.

{
  "mcpServers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://mcp.example.com/github"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcpServerName": "github",
      "defaultConfig": {
        "permissionPolicy": { "type": "always_ask" }
      },
      "configs": [
        {
          "name": "create_issue",
          "permissionPolicy": { "type": "always_allow" }
        }
      ],
      "resources": false,
      "prompts": false
    }
  ]
}

Field	Type	Required	Description
`type`	string	Yes	Must be `mcp_toolset`.
`mcpServerName`	string	Yes	Name of an entry in `mcpServers`.
`defaultConfig`	object	No	Default enablement and permission policy for tools from this server.
`configs`	object[]	No	Per-tool overrides by MCP tool name.
`resources`	boolean	No	Whether MCP resources are enabled.
`prompts`	boolean	No	Whether MCP prompts are enabled.

Custom tool config

Custom tools are functions your application executes outside the managed agent environment. Declare them with type: "custom_tool", a model-facing name, a clear description, and an input_schema.

{
  "type": "custom_tool",
  "name": "check_order_status",
  "description": "Look up an order by ID.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Customer order ID"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  },
  "enabled": true,
  "permissionPolicy": { "type": "always_ask" }
}

Field	Type	Required	Description
`type`	string	Yes	Must be `custom_tool`.
`name`	string	Yes	Tool name exposed to the model.
`description`	string	Yes	Tool description exposed to the model.
`input_schema`	object	Yes	Object-shaped input schema.
`enabled`	boolean	No	Defaults to `true`.
`permissionPolicy`	object	No	Approval policy for this custom tool. Defaults to `always_ask` when omitted.

Custom tools use the permission policy above. With the default always_ask, the stream emits an approval request first. After approval, the stream emits agent.custom_tool_use and then session.status_idle with stop_reason.type: "requires_action". Execute the tool in your application and return user.custom_tool_result to POST /v1/sessions/{sessionId}/events. See the Events Reference for the full request/response flow. If the application-owned work cannot finish promptly, use the dedicated long-running custom tools flow. The initial response must reach the pending tool call within approximately five minutes.

Permission policies

Permission policies control whether built-in, MCP, and custom tools run automatically or wait for approval.

Policy	Behavior
`always_allow`	The tool executes automatically.
`always_ask`	The session pauses and waits for an approval response event.
`always_deny`	Herm denies the tool automatically before it executes.

When a tool with always_ask is invoked, the session emits agent.approval_request, then pauses with session.status_idle and stop_reason.type: "requires_action". Continue by sending user.approval_response to POST /v1/sessions/{sessionId}/events. For trusted autonomous sessions, set yoloMode: true on the session to automatically accept always_ask approval prompts. YOLO mode does not bypass always_deny or disabled tools. When a tool is disabled with enabled: false, Herm treats it as always_deny: the request is denied before execution and no approval request is emitted.

Role-specific tool policies

Agent versions can also define named roles. A role contains its own tools array using the same config shapes shown above. When a session is created with a role, that role’s tool policy is used for approval decisions instead of the agent version’s top-level tools.

{
  "name": "readonly",
  "tools": [
    {
      "type": "agent_toolset",
      "defaultConfig": { "enabled": false },
      "configs": [
        { "name": "terminal", "enabled": false },
        { "name": "file", "enabled": false },
        { "name": "clarify", "enabled": true }
      ]
    }
  ]
}

Create a session with that boundary by passing role to POST /v1/sessions.

Update semantics

Agent updates create a new immutable version. With PATCH /v1/agents/{agentId}, supplied tools are upserted by their stable key and omitted tools are preserved; an empty array removes nothing. Use the full-replacement POST /v1/agents/{agentId} to replace the complete tools array or clear it with tools: [].

Getting Started

Agents

Sessions and events

Capabilities

Credentials

Resources

Tool config types

Built-in agent toolsets

Built-in toolset config

MCP toolset config

Custom tool config

Permission policies

Role-specific tool policies

Update semantics

​Tool config types

​Built-in agent toolsets

​Built-in toolset config

​MCP toolset config

​Custom tool config

​Permission policies

​Role-specific tool policies

​Update semantics

Tool config types

Built-in agent toolsets

Built-in toolset config

MCP toolset config

Custom tool config

Permission policies

Role-specific tool policies

Update semantics