---
title: "Create agent custom tool"
method: POST
path: "/api/v0/agent/tools"
tags: ["Agent Tools"]
---

# Create agent custom tool

`POST /api/v0/agent/tools`

Create a new user-defined agent tool. Pass draft=true to generate a tool definition from a natural-language description without persisting it.

## Query parameters

- `draft` boolean — When true, generate a tool definition without saving.

## Request body

- AgentCustomToolCreateRequest — Request body for creating an agent custom tool. When draft=true, only the 'description' field is required. The LLM will generate the tool definition from the description. When draft=false (default), 'name' is required and the tool is persisted.
  - `tool_type` 'python' | 'prompt' | 'api' — Tool type: python, prompt, api.
  - `name` string, nullable — The tool name (snake_case). Required when draft=false.
  - `description` string — The tool description.
  - `parameters` object[], nullable — Parameter definitions [{name, type, description, required}].
  - `code` string — Code/prompt/config body.

## Response `200`

Successful Response

- union
  - AgentCustomToolPostResponse — Response for creating an agent custom tool.
    - `id` string, uuid, required — The ID of the created tool.
    - `tool_type` string, required — The tool type (python, prompt, api).
    - `name` string, required — The name of the tool.
    - `description` string, required — The description of the tool.
    - `parameters` object[], nullable — The parameter definitions.
    - `code` string, required — The code/prompt/config body.
    - `created_at` string, date-time, required — When the tool was created.
  - AgentCustomToolGenerateResponse — Response for LLM-generated tool definition.
    - `tool_type` string, required — The tool type (python, prompt, api).
    - `name` string, required — Generated tool name (snake_case).
    - `description` string, required — Generated tool description.
    - `parameters` object[], required — Generated parameter definitions.
    - `code` string, required — Generated code/prompt/config body.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/outerport/apis/outerport-api.md) · [All operations](https://skmtc.dev/outerport/apis/outerport-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/outerport/outerport-api/revisions/f565b46daaea/schema)