The custom tool object

Shape of a Custom Tool, a user-defined HTTP endpoint that agents can call as if it were a built-in tool.

A CustomTool is a user-defined HTTP endpoint exposed to agents as if it were a built-in tool. Define the method, URL, parameters, and auth once; assign to any agent.

Object shape

{
  "id": "tool_64f1c0ef2ec711ef6dc1dcf",
  "name": "custom_list_postmark_templates",
  "label": "List Postmark Templates",
  "description": "Returns the list of email templates from Postmark.",
  "type": "read",
  "method": "GET",
  "url": "https://api.postmarkapp.com/templates",
  "headers": { "Accept": "application/json" },
  "body_template": null,
  "parameters": [
    {
      "name": "count",
      "type": "integer",
      "description": "How many templates to return.",
      "required": false,
      "in": "query"
    }
  ],
  "auth": { "type": "api_key", "header_name": "X-Postmark-Server-Token" },
  "group": { "name": "Postmark", "icon": null, "color": null },
  "created_at": "2026-06-01T00:00:00.000Z",
  "updated_at": "2026-06-20T12:00:00.000Z"
}

Attributes

Field	Type	Notes
`id`	string	`tool_<24 hex>`.
`name`	string	Auto-generated slug from `label`, prefixed `custom_`. Immutable after creation. Used in `agent.tools[].name`.
`label`	string	Human-friendly display name. Include the connector + resource ("List Postmark Templates", not "List Templates").
`description`	string	LLM-facing description. Determines when the tool gets called.
`type`	enum	`"read"` or `"write"`. Write tools require approval in chat.
`method`	enum	`GET` \| `POST` \| `PUT` \| `PATCH` \| `DELETE`.
`url`	string	Endpoint URL. May contain `{{param}}` placeholders substituted at call time.
`headers`	object	Static headers map, e.g. `{ "Accept": "application/json" }`.
`body_template`	string \| null	JSON string template for POST/PUT/PATCH bodies. Supports `{{param}}`.
`parameters`	array	See below.
`auth`	object	Type + header_name only. Credentials NEVER returned.
`group`	object \| null	UI grouping. `{ name, icon, color }`.
`created_at`	ISO 8601	Always UTC.
`updated_at`	ISO 8601	Bumped on every PATCH.

Parameter shape

{
  "name": "ticket_id",
  "type": "string",
  "description": "Ticket ID to fetch.",
  "required": true,
  "in": "query" | "header" | "body",
  "headerName": "X-Ticket-Id"
}

Auth shape (read)

Reads return type + header_name only:

{ "type": "none" | "bearer" | "api_key" | "basic", "header_name": "X-API-Key" }

Auth shape (write input)

Writes accept credentials, encrypted at rest, never returned:

{
  "type": "api_key",
  "credentials": {
    "apiKey": "secret-here",
    "header_name": "X-API-Key"
  }
}

🔒

Credentials are write-only

Send auth.credentials on create/update. Read responses contain only the auth type and (for api_key) the header name. The secret itself is bcrypt-hashed and never returned.