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.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Agent slug within the workspace.
Header Parameters
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.
1 <= length <= 255Request 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.