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

# Create Tool

`POST /ai/tools`

Create a new custom AI tool that can be attached to AI assistants.

## Headers

- `Idempotency-Key` string

## Request body

- CreateSharedToolRequest — Request model for creating a shared (org-level) tool.
  - `type` string, required
  - `display_name` string, required
  - `function` object
  - `retrieval` object
  - `handoff` object
  - `invite` object
  - `webhook` object
  - `pay` PayToolParams
    - `connector_name` string, required — The name of the pay connector configured in the Telnyx API. Must reference an existing pay connector for this organization.
    - `currency` string — Default currency for payments processed by this tool.
    - `payment_method` string — Default payment method for payments processed by this tool.
    - `description` string, nullable — Optional description of the pay tool that will be passed to the assistant.
  - `client_side_tool` object
  - `update_dynamic_variables` UpdateDynamicVariablesToolParams — Configuration for an update_dynamic_variables tool.
    - `name` string, required — The function name surfaced to the LLM. Must match the OpenAI function-name pattern `^[a-zA-Z0-9_-]+$` and be unique across the assistant's function, webhook, and client_side tools.
    - `description` string, required — Description of the tool passed to the assistant, guiding when to call it and which variables to update.
    - `updatable_variables` object[], required — The dynamic variables the assistant is allowed to write. At least one is required.
      - `name` string, required — The dynamic-variable key to update. Must match `^[a-zA-Z0-9._-]+$` and may not start with the reserved `telnyx_` prefix (reserved for system variables). The `pattern` encodes both rules via a negative lookahead.
      - `type` string — Optional hint for the variable's value type (e.g. `string`).
      - `description` string — Optional description of the variable, guiding the assistant on what value to capture.
  - `timeout_ms` integer

## Response `200`

Successful Response

- SharedToolResponse
  - `id` string, required
  - `type` string, required
  - `display_name` string
  - `tool_definition` object, required
  - `timeout_ms` integer
  - `created_at` string

## Other responses

- `400` — Bad Request / Validation Failed (10015). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
- `409` — A request with the same Idempotency-Key is still being processed (10036). Retry later with the same key and request.
- `413` — Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
- `422` — Validation Error. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
- `503` — Service unavailable (10016), including unavailable Edge idempotency protection for a keyed request.

## Changes

> 99 revisions in range; 1 not diffed.

- **2026-09-22** `9621f6123ebc` — 2 warning
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `409`
  - added the new `domain_graduation_limit_exceeded` enum value to the `errors/items/code` response property for the response status `409`
- **2026-09-16** `a6a61a29ecdd` — 1 breaking, 1 warning, 6 info
  - the response's body type changed from `object` to no type for status `422`
  - removed the optional property `detail` from the response with the `422` status
  - added the new optional `header` request parameter `Idempotency-Key`
  - added `#/components/schemas/HTTPValidationError, #/components/schemas/inference-embedding_ErrorResponse` to the response body `anyOf` list for the response status `422`
  - …4 more
- **2026-08-04** `ca70e22d0d63` — 1 info
  - added the new optional request property `update_dynamic_variables`
- **2026-07-16** `020dcdb3d9da` — 1 info
  - added the new optional request property `pay`
- **2026-07-07** `2c2d1971907f` — 1 info
  - added the new optional request property `client_side_tool`

[Full history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/tools/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/227c33b1ac9c?raw)