Herald — Notify • Route • Execute

Docs

Custom tools

Overview

Custom tools let you expose any HTTP API to AI agents. Unlike pre-built alert templates, you control the method, URL, body shape, headers, and parameters the agent can pass. Tools are stored per workspace and exposed via MCP when enabled.

Find the builder under Custom tools in the workspace sidebar.

Form sections

Basic info

Integration name — label in the dashboard
Tool name — MCP identifier (lowercase, underscores; immutable after creation)
Description — tells the agent when to use this tool (min 10 characters)

HTTP request

Method — GET, POST, PUT, PATCH, or DELETE
URL — target endpoint; supports {{secret_name}} placeholders
Body template — JSON with {{field}} placeholders matching your input schema

Input schema

Parameters the agent passes when calling the tool. Each field has a name, type (string, number, integer, boolean), description, and required flag.

Headers

Optional HTTP headers sent with every request (e.g. Content-Type: application/json).

Secrets

Encrypted key-value pairs referenced as {{secret_key}} in URL, headers, or body. Values are stored with AES-256-GCM and never shown again after save.

Template placeholders

When a tool runs, Herald replaces {{name}} tokens:

Placeholder	Source
`{{message}}`	Agent argument from input schema
`{{api_key}}`	Decrypted secret named `api_key`

Example body template:

{
  "message": "{{message}}",
  "source": "herald"
}

If the agent calls the tool with { "message": "Deploy failed" }, Herald sends that JSON to your URL.

Execution flow

Agent (Cursor) → MCP Gateway → load tool + secrets → HTTP request
                                                      ↓
                                            your URL
                                                      ↓
                                            audit log + usage counter

Two ways to invoke:

Dashboard test panel — run a tool with sample args from the custom tools page
MCP from IDE — agent calls the tool name via the gateway after Connect IDE setup

Editing & deleting

Edit from Custom tools in the workspace — only your HTTP (generic) tools
Tool name cannot change after creation
On edit, leave secret values blank to keep existing; omit a secret key to delete it
Disable tools from the Alerts page without deleting configuration

Example: POST to a Herald webhook

Chain a custom tool to an inbound Herald webhook:

Create a Herald webhook and copy its URL
Create a custom tool with method POST, that URL, and body {"event": "{{message}}"}
Agent invokes the tool → event lands in Inbox

OpenAPI import (Pro / Platform)

Bulk-create custom tools from an OpenAPI 3.x JSON spec in workspace Settings (max 25 operations). Each operation becomes a generic HTTP tool.