---
title: "Create Tool"
method: POST
path: "/api/v1/tools/"
tags: ["main"]
---

# Create Tool

`POST /api/v1/tools/`

## Request

- Base URL: `https://app.dograh.com`
- URL: `https://app.dograh.com/api/v1/tools/`
- Auth: none declared

Create a new tool.

Args:
    request: The tool creation request

Returns:
    The created tool

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable

## Request body

- CreateToolRequest: Request schema for creating a reusable tool.
  - `name` string, required: Display name for the tool.
  - `description` string, nullable: Description shown to the agent when deciding whether to call it.
  - `category` 'http_api' | 'end_call' | 'transfer_call' | 'transfer_agent' | 'calculator' | 'native' | 'integration' | 'mcp': Tool category. Must match definition.type.
  - `icon` string, nullable: Lucide icon identifier.
  - `icon_color` string, nullable: Hex color for the tool icon.
  - `definition` union, required: Typed tool definition.
    - HttpApiToolDefinition: Tool definition for HTTP API tools.
      - `schema_version` integer: Schema version.
      - `messages` union[]: Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only.
        - union
          - ToolStartTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'start', required
          - ToolStartAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'start', required
          - ToolDelayedTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'delayed', required
            - `after_ms` integer, required
          - ToolDelayedAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'delayed', required
            - `after_ms` integer, required
      - `type` 'http_api', required: Tool type.
      - `config` HttpApiConfig, required: Configuration for HTTP API tools.
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required: HTTP method to use for the request.
        - `url` string, required: Target HTTP or HTTPS URL.
        - `headers` object, nullable: Static headers to include with every request.
        - `credential_uuid` string, nullable: Reference to an external credential for request authentication.
        - `parameters` ToolParameter[], nullable: Parameters the model must provide when calling this tool.
          - `name` string, required: Parameter name used as a key in the tool request body.
          - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required: JSON type for the parameter value.
          - `description` string, required: Description shown to the model for this parameter.
          - `required` boolean: Whether this parameter is required when the tool is called.
        - `preset_parameters` PresetToolParameter[], nullable: Parameters injected by Dograh from fixed values or workflow context templates.
          - `name` string, required: Parameter name used as a key in the request body.
          - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required: JSON type for the resolved value.
          - `value_template` string, required: Fixed value or template, e.g. {{initial_context.phone_number}}.
          - `required` boolean: Whether the parameter must resolve to a non-empty value.
        - `timeout_ms` integer, nullable: Request timeout in milliseconds.
        - `body_template` object, nullable: Optional JSON body template for POST, PUT, and PATCH requests.
        - `body_format` 'json' | 'form': Encoding of the POST, PUT, and PATCH request body: 'json' sends application/json, 'form' sends application/x-www-form-urlencoded.
    - EndCallToolDefinition: Tool definition for End Call tools.
      - `schema_version` integer: Schema version.
      - `messages` union[]: Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only.
        - union
          - ToolStartTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'start', required
          - ToolStartAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'start', required
          - ToolDelayedTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'delayed', required
            - `after_ms` integer, required
          - ToolDelayedAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'delayed', required
            - `after_ms` integer, required
      - `type` 'end_call', required: Tool type.
      - `config` EndCallConfig, required: Configuration for End Call tools.
        - `endCallReason` boolean: When enabled, the model must provide a reason for ending the call. The reason is set as call disposition and added to call tags.
        - `endCallReasonDescription` string, nullable: Description shown to the model for the reason parameter. Used only when endCallReason is enabled.
    - TransferCallToolDefinition: Tool definition for Transfer Call tools.
      - `schema_version` integer: Schema version.
      - `messages` union[]: Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only.
        - union
          - ToolStartTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'start', required
          - ToolStartAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'start', required
          - ToolDelayedTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'delayed', required
            - `after_ms` integer, required
          - ToolDelayedAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'delayed', required
            - `after_ms` integer, required
      - `type` 'transfer_call', required: Tool type.
      - `config` TransferCallConfig, required: Configuration for Transfer Call tools.
        - `introduction_enabled` boolean: Play a generated introduction in the agent's voice to both parties before connecting them. Supported for Twilio calls with a TTS provider. Realtime speech-to-speech agents and synthesis failures skip the introduction.
        - `introduction_prompt` string: Instructions for the transfer introduction, including language.
        - `destination_source` 'static' | 'dynamic' | 'context_mapping': Whether the destination is static/template, resolved by HTTP, or selected by ordered gathered/initial-context mapping rules.
        - `destination` string: Phone number, SIP endpoint, or template to transfer the call to, e.g. +1234567890, PJSIP/1234, or {{initial_context.transfer_destination}}.
        - `timeout` integer: Maximum seconds to wait for the destination to answer.
        - `call_disposition` string, nullable: Optional disposition to record after a successful transfer. When omitted, Dograh records its provider-specific transfer default.
        - `parameters` ToolParameter[], nullable: Parameters the model may provide when calling this transfer tool, for example state, department, or transfer reason.
          - `name` string, required: Parameter name used as a key in the tool request body.
          - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required: JSON type for the parameter value.
          - `description` string, required: Description shown to the model for this parameter.
          - `required` boolean: Whether this parameter is required when the tool is called.
        - `resolver` HttpTransferResolverConfig: HTTP endpoint used to resolve transfer destination at call time.
          - `type` 'http': Resolver type.
          - `url` string, required: HTTP or HTTPS endpoint for transfer resolution.
          - `headers` object, nullable: Static headers to include with every resolver request.
          - `credential_uuid` string, nullable: Reference to an external credential for resolver authentication.
          - `timeout_ms` integer: Resolver request timeout in milliseconds.
          - `wait_message` string, nullable: Optional short message played while Dograh resolves routing.
          - `parameters` ToolParameter[], nullable: Parameters the model may provide when calling this transfer tool.
            - `name` string, required: Parameter name used as a key in the tool request body.
            - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required: JSON type for the parameter value.
            - `description` string, required: Description shown to the model for this parameter.
            - `required` boolean: Whether this parameter is required when the tool is called.
          - `preset_parameters` PresetToolParameter[], nullable: Parameters injected by Dograh from fixed values or workflow context templates.
            - `name` string, required: Parameter name used as a key in the request body.
            - `type` 'string' | 'number' | 'boolean' | 'object' | 'array', required: JSON type for the resolved value.
            - `value_template` string, required: Fixed value or template, e.g. {{initial_context.phone_number}}.
            - `required` boolean: Whether the parameter must resolve to a non-empty value.
        - `context_mapping` ContextDestinationMappingConfig: Resolve a transfer destination from gathered or initial context. Rules are evaluated in order. The first rule whose context value matches one of its routes wins; ``fallback_destination`` applies only when no rule matched. Destinations may be provider-native values or context templates.
          - `rules` ContextDestinationRule[], nullable: Ordered routing rules evaluated top to bottom; first match wins.
            - `context_path` string, required: Context path used for routing. An unprefixed path checks gathered context first, then initial context; use initial_context.* or gathered_context.* to select one explicitly.
            - `routes` ContextDestinationRoute[], required
              - …
          - `context_path` string, nullable: Deprecated single-rule context path. Use rules instead; accepted for backward compatibility.
          - `routes` ContextDestinationRoute[], nullable: Deprecated single-rule routes. Use rules instead; accepted for backward compatibility.
            - `context_value` string, required: Context value that selects this destination.
            - `destination` string, required: VICIdial in-group, SIP endpoint, E.164 phone number, or context template used when this route matches.
          - `fallback_destination` string, nullable: Optional provider-native destination or context template used when no rule matched.
    - TransferAgentToolDefinition: Tool definition for Transfer Agent tools.
      - `schema_version` integer: Schema version.
      - `messages` union[]: One start text message, with template variables supported. Omit to use the default handover line, or send an empty list for a silent handoff.
        - union
          - ToolStartTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'start', required
          - ToolStartAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'start', required
          - ToolDelayedTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'delayed', required
            - `after_ms` integer, required
          - ToolDelayedAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'delayed', required
            - `after_ms` integer, required
      - `type` 'transfer_agent', required: Tool type.
      - `config` TransferAgentConfig, required: Configuration for Transfer Agent tools. One tool, one destination. An agent that can hand the caller to several places gets several of these tools, and the model chooses between them the way it chooses between any other tools -- by their names and descriptions. That keeps the routing decision in the one place the model already reasons about, and leaves nothing to configure here but where the call goes. Most of how a handoff sounds is fixed: the caller hears a ringer while the next agent is prepared. The handover line is configurable because it is caller-facing and Dograh runs in more than one language, and so is how the next agent opens: an agent that greets callers on its own number should not re-introduce itself mid-conversation, and one that only ever answers handoffs needs a line of its own before it picks the conversation up.
        - `workflow_id` integer, required: Id of the Dograh agent to transfer to. Must be in the same organization, and must not be a speech-to-speech agent.
        - `greeting_mode` 'start_greeting' | 'continue' | 'introduce_and_continue': How the destination agent opens. 'start_greeting' plays its Start Call greeting and waits for the caller. 'continue' skips the greeting and opens with a reply generated from the handover note. 'introduce_and_continue' speaks the introduction in the destination's own voice and then opens with a generated reply, so the caller hears who picked up without having to repeat themselves.
        - `introduction` string, nullable: What the destination agent says as it takes over, in its own voice, before its first generated reply. Required with greeting_mode 'introduce_and_continue' and not accepted otherwise. Supports template variables.
    - CalculatorToolDefinition: Tool definition for Calculator tools.
      - `schema_version` integer: Schema version.
      - `messages` union[]: Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only.
        - union
          - ToolStartTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'start', required
          - ToolStartAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'start', required
          - ToolDelayedTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'delayed', required
            - `after_ms` integer, required
          - ToolDelayedAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'delayed', required
            - `after_ms` integer, required
      - `type` 'calculator', required: Tool type.
    - McpToolDefinition: Persisted MCP tool definition.
      - `schema_version` integer: Schema version.
      - `messages` union[]: Configured speech. An empty list disables announcements. HTTP/MCP choose one start entry and one entry per delayed timing at random. End-call and transfer tools support one start entry only.
        - union
          - ToolStartTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'start', required
          - ToolStartAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'start', required
          - ToolDelayedTextMessage
            - `type` 'text', required
            - `text` string, required
            - `event` 'delayed', required
            - `after_ms` integer, required
          - ToolDelayedAudioMessage
            - `type` 'audio', required
            - `recording_id` integer, required
            - `event` 'delayed', required
            - `after_ms` integer, required
      - `type` 'mcp', required: Tool type.
      - `config` McpToolConfig, required: Configuration for a customer MCP server tool definition.
        - `transport` 'streamable_http': MCP transport protocol.
        - `url` string, required: MCP server URL. Must use http:// or https://.
        - `credential_uuid` string, nullable: Reference to an external credential for MCP server auth.
        - `tools_filter` string[]: Allowlist of MCP tool names to expose. Empty exposes all tools.
        - `timeout_secs` integer: Connection timeout in seconds.
        - `sse_read_timeout_secs` integer: SSE read timeout in seconds.
        - `discovered_tools` object[]: Server-managed cache of the MCP server's tool catalog [{name, description}]. Populated best-effort by the backend.

## Response `200`

Successful Response

- ToolResponse: Response schema for a reusable tool.
  - `id` integer, required
  - `tool_uuid` string, required
  - `name` string, required
  - `description` string, nullable, required
  - `category` string, required
  - `icon` string, nullable, required
  - `icon_color` string, nullable, required
  - `status` string, required
  - `definition` object, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, nullable, required
  - `created_by` CreatedByResponse: Response schema for the user who created a tool.
    - `id` integer, required
    - `provider_id` string, required

## Other responses

- `404`: Not found
- `422`: Validation Error

## Changes

- **2026-11-03** `faa00cf76fcb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dograh/apis/dograh-api/changes/api/v1/tools/post.md)

---

[API](https://skmtc.dev/dograh/apis/dograh-api.md) - [All operations](https://skmtc.dev/dograh/apis/dograh-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dograh/apis/dograh-api/revisions/faa00cf76fcb?raw)