Tools
Tools

Add an HTTP tool

Create a new HTTP tool. This call sets the minimum (name, description, method, url; displayName optional, defaults to the name). Use `set_tool_headers` / `set_tool_params` / `set_tool_requires` afterwards to fill in the rest. URLs may include `{{variable_name}}` placeholders, declare those variables with `set_plain_variable`, or for a credential `request_secret_variable` in the app or `set_secret_variable` over the MCP.

POST
/workspaces/{workspace}/agents/{agent}/tools

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Path Parameters

workspace*string

Workspace slug (GET /me lists yours).

agent*string

Agent slug within the workspace.

Header Parameters

Idempotency-Key?string

A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/workspaces/string/agents/string/tools" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "description": "string",    "method": "GET",    "url": "string"  }'
{
  "toolId": "string",
  "property1": null,
  "property2": null
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}

Add a built-in tool POST

Add a built-in tool from the fixed template set. Built-in tools have their own runtime handler, so there is no URL, header, param or requires to set. Call list_builtin_tools first: it lists every template with what it does and the arguments the agent passes, and gives one template's full description. The everyday ones: `transfer_to_human` (escalates the call to a human), `call_and_connect` (rings a number the caller asks for and connects them; Australian mobiles, landlines and 13, 1300 and 1800 numbers only, never emergency, overseas or 19 numbers; with `stay_on_the_line: true` in its config the agent stays on the call with both people, otherwise it transfers and leaves; on an eval or a chat nobody is rung), `end_call` (politely hangs up), `take_a_message` (emails the caller's name, number and message to the routed inbox), `book_meeting` (a Cal.com booking), `search_knowledge_base` (grounds answers in the agent's knowledge base), `get_current_time` (a fresh clock reading partway through a call; every call already opens with the local date and time), `calculate` (works out a sum exactly, such as adding prices, a rate times hours or adding GST, and returns the answer in figures and in words; give it to any agent that quotes a total, because the model's own arithmetic slips), `escalate_emergency` (one fixed dial-triple-zero line, then a human, never triage), `send_text_message` (texts the caller a link they asked for), `request_details_form` + `check_captured_details` (texts a short form for written values such as an email), `send_order_verification_code` + `verify_order_code` (a 6-digit order OTP), `press_keys` (sends keypad tones, for a transfer prompt or an IVR menu), `capture_digits` (reads digits the caller keys in; needs `keypadInputEnabled` under call handling or it returns `dtmf_reception_disabled`), `add_to_do_not_call` (puts an inbound caller who opts out on the workspace do-not-call list; campaign calls and lead callbacks already have it) and `note_customer_answers` (asks the `questions` in its config in order before an offer). The rest drive demos and integrations, each listed by list_builtin_tools: the live second screen (`send_live_link` and the tools that push to its page), Square pricing and payment links, Cliniko intake and booking, the /build interview and website-guide tools, role-play, voice preview and caller playback. A template that reaches a third party takes its keys in config, always as a reference to a SECRET variable: set_builtin_config documents each template's config, and each Cliniko tool takes `api_key`, `shard` and `contact_email`. You can set `displayName` for the operator-facing label, and call `set_tool_description` afterwards for a more specific description. `name` defaults to the template name, which is right for the common case. An agent carries one tool per template: the validator blocks publish on a second, and this op refuses one rather than adding it.

Delete a tool DELETE

Delete a tool. Identify the tool by toolName (its snake_case name) or toolId. **Check if other tools' `requires` reference this tool's name first**, leaving dangling requires references will fail the publish validator.