---
title: "Create"
method: POST
path: "/tools"
tags: ["tools"]
---

# Create

`POST /tools`

Creates a new tool in a project.

## Query parameters

- `project` string

## Headers

- `Authorization` string, required

## Request body

- CreateToolRequest
  - `name` string, required — The name of the tool. Must be snake_case and unique within the organization.
  - `description` string, required — A description of what the tool does.
  - `type` 'custom_context' | 'custom_webhook' | 'custom_websocket' | 'built_in_transfer_to_phone_number' | 'built_in_transfer_to_agent' | 'built_in_natural_conversation_ending' | 'built_in_keypad_input' | 'built_in_choose_not_to_respond', required — The type of tool.
  - `execution_mode` 'sync' | 'async', required — Mode of operation.
  - `parameters` union — The tool's parameters, either as a flat array of parameter definitions or as a raw JSON Schema object (use the object form for nested parameters). When sending an array: - For `custom_webhook` tools with POST method, each parameter must include a `location` field. - For `custom_webhook` tools with GET method, `location` defaults to `"query_string"` if not specified. - For `custom_websocket`, `built_in_transfer_to_phone_number`, and `built_in_transfer_to_agent` tools, `location` must not be specified. - `parameter_locations` must not be sent, since placement is carried inline on each parameter. When sending a JSON Schema object, `custom_webhook` tools supply parameter placement in `parameter_locations` instead. Tools that cannot have parameters (`custom_context` and the `built_in_*` types) must send an empty array or omit the field.
    - ToolParameter[]
      - `type` 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'enum', required — The parameter type.
      - `item_type` 'string' | 'integer' | 'number' | 'boolean' — Required only when type is "array". The type of items in the array.
      - `enum_values` string[] — Required only when type is "enum". The fixed set of allowed string values for the parameter. Values must be unique and non-empty.
      - `name` string, required — The parameter name.
      - `description` string, required — Description of the parameter.
      - `is_required` boolean, required — Whether the parameter is required.
      - `location` 'request_body' | 'query_string' — Only applicable for `custom_webhook` tools. Specifies where the parameter should be sent in the webhook request. - For GET webhooks: defaults to `"query_string"` and `"request_body"` is not allowed. - For POST webhooks: required, can be either `"request_body"` or `"query_string"`. - Not allowed for `custom_websocket`, `built_in_transfer_to_phone_number`, or `built_in_transfer_to_agent` tools. When switching a webhook tool's `endpoint_method` from POST to GET, its request body parameters must be re-sent with `"query_string"` locations.
    - ToolParametersJsonSchema — A tool's parameters expressed as a raw JSON Schema object, for parameters that the flat `ToolParameter` list cannot express: nested objects, arrays of objects, `anyOf` variants, `null`, and non-string enums. Each entry in `properties` is a JSON Schema value supporting `type` (`"string"`, `"integer"`, `"number"`, `"boolean"`, `"null"`, `"array"`, `"object"`), `description`, `enum` (string parameters only), `items` (for arrays), `properties`/`required`/`additionalProperties` (for objects) and `anyOf`. Values may be nested up to 5 levels deep. Parameter names cannot be any of the reserved names that Phonic injects into every tool call: `call_info`, `conversation_id`, `from_phone_number`, `to_phone_number`, `twilio_call_sid`. For `custom_webhook` tools, parameter placement is supplied separately in `parameter_locations` rather than inline on the schema.
      - `type` 'object', required
      - `properties` object, required — The tool's top-level parameters, as a map from parameter name to its JSON Schema.
      - `required` string[] — The names of the required top-level parameters. Every name must be defined in `properties`.
      - `additionalProperties` false — Must be `false`. Tool parameter schemas do not allow properties beyond the ones declared.
  - `parameter_locations` object — Where each top-level parameter is sent in the webhook request, as a map from parameter name to location. Only for `custom_webhook` tools whose `parameters` are a raw JSON Schema object. Every key must name a top-level parameter. For POST webhooks, every parameter needs an entry. For GET webhooks, entries default to `"query_string"` and `"request_body"` is not allowed.
  - `endpoint_method` 'GET' | 'POST' — Required for webhook tools. HTTP method for the webhook endpoint.
  - `endpoint_url` string, uri — Required for webhook tools. Must be a publicly routable HTTPS URL without embedded credentials.
  - `endpoint_headers` object — Optional headers for webhook tools.
  - `endpoint_timeout_ms` integer — Timeout for webhook tools.
  - `tool_call_output_timeout_ms` integer — Timeout for WebSocket tool responses.
  - `phone_number` string, nullable — The E.164 formatted phone number to transfer calls to. Set to null if the agent should determine the phone number.
  - `dtmf` string, nullable — DTMF digits to send after the transfer connects (e.g., "1234"). Defaults to null. Ignored when dynamic_dtmf is true.
  - `dynamic_dtmf` boolean — When true, the agent determines the DTMF digits at call time (and may choose to send none); the static dtmf is ignored. Only sent when use_agent_phone_number is true (not on a SIP REFER transfer).
  - `use_agent_phone_number` boolean — When true, Phonic will transfer the call using the agent's phone number. When false, Phonic will transfer the call using the phone number of the party to whom the agent is connected. This is only available for built_in_transfer_to_phone_number tools.
  - `detect_voicemail` boolean — When true, Phonic will listen in and tell the user if the transfer hits voicemail. This is only available for built_in_transfer_to_phone_number tools when use_agent_phone_number is true.
  - `agents_to_transfer_to` string[] — Array of agent names that the LLM can choose from when transferring. Required for built_in_transfer_to_agent tools. All agents must exist in the same project as the tool.
  - `require_speech_before_tool_call` boolean — When true, forces the agent to speak before executing the tool.
  - `speech_before_tool_call` 'required' | 'optional' | 'suppressed' — For built_in_natural_conversation_ending and built_in_keypad_input tools. Whether the agent must speak before calling the tool ("required"), the model decides ("optional"), or the agent must stay silent ("suppressed"). Not used by other tool types.
  - `respond_after_sec` number, double, nullable — For built_in_choose_not_to_respond tools. Number of seconds to wait after the tool fires before the agent speaks a follow-up if the user stays silent. When null, the agent stays silent (default). Not used by other tool types.
  - `wait_for_speech_before_tool_call` boolean — If true, the agent will wait to finish speaking before executing the tool. This is only available for custom_webhook and custom_websocket tools.
  - `forbid_speech_after_tool_call` boolean — When true, forbids the agent from speaking after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools.
  - `forbid_tool_call_after_speech` boolean — When true, forbids the agent from calling the tool right after it has spoken. Available for custom_webhook and custom_websocket tools.
  - `allow_tool_chaining` boolean — When true, allows the agent to chain and execute other tools after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools.
  - `wait_for_response` boolean — The agent doesn't typically wait for the response of async custom_websocket tools. When true, makes the agent wait for a response, not call other tools and inform the user of the result. Only available for async custom_websocket tools.
  - `context` string — The static context returned to the agent. Required for custom_context tools.

## Response `201`

Success response

- ToolsCreateResponse201
  - `id` string, required — The ID of the created tool.
  - `name` string, required — The name of the created tool.

## Other responses

- `400` — Invalid parameters
- `403` — Agent authentication cannot create tools
- `409` — Tool name already exists

---

[API](https://skmtc.net/phonic/apis/api-reference.md) · [All operations](https://skmtc.net/phonic/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/phonic/api-reference/revisions/7f8c81a5a990/schema)