> ## Documentation Index > Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a tool > Create a tool. Two payload shapes exist: - `function_type: external:api` creates an API tool from a `url` and an OpenAI-style `function_definition`. - Any other `function_type` with `creatable_via_api: true` in `GET /api/v2/tools/types` creates a built-in or provider-backed tool from its template; pass type-specific settings in `params`. Behaviours that belong to the agent itself (`system:end_call`, `system:transfer_call`, `system:check_forward_availability`, `system:check_warm_transfer_availability`, `system:get_caller_info`, `system:extract_intent`, `system:chat_handover`) are not creatable and are rejected with `mf-core:tool-invalid-function-type`. Call forwarding (`system:forward_call`), warm transfer (`system:warm_transfer`) and DTMF input (`system:dtmf_input`) are configurable and stay creatable. Cal.com tools (`cal:get_availability`, `cal:book_appointment`) require `params.eventTypeId` and `params.timezone`; a missing or invalid value is rejected with `mf-core:tool-validation-failed` and `details.missing_param` names the key. Call-forwarding and warm-transfer types create two tools (a check and an execute tool) and return both in `tools`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v2/tools openapi: 3.1.0 info: title: Customer API version: 1.0.0-beta description: > **Beta.** This API is in beta. Contracts can still change while we complete it, including breaking changes; we announce changes in the release notes and keep them as rare as we can. Pin your integration to the field names and status codes documented here and treat unknown fields as optional. REST API to create and configure voice agents, add tools, test them with evals, read conversations, and place AI outbound calls. **Authentication.** Voice agents, settings, tools, evals and conversations use an API token created on the **Keys** page of your dashboard. Each operation lists the scope it needs under `x-required-scopes`; `:*` grants every action of a resource. Outbound calls use a separate outbound API token from the **Outbound Calls** page. Send either token as `Authorization: Bearer `. **Responses.** A single resource is returned as a flat JSON object; a collection is wrapped in a plural key (`voice_agents`, `tools`, `evals`, `conversations`) next to its paging fields. Deleting returns `204 No Content`. Everything is addressed by the voice agent's `id`; prompts and numbers are internal. **Errors.** Authentication failures return `{ "error", "message" }`. Request quotas return `429` with a `Retry-After` header and `{ "error", "message", "details" }`, where `error` is a stable machine-readable code. Every API call must finish within 30 seconds; longer requests return `503` with `mf-core:api-request-timeout`. Validation errors list the problems per field; the exact shape is shown on each operation. servers: - url: https://app.miyon.ai security: [] tags: - name: Voice Agents description: >- Create and manage voice agents. Configure them through the voice, prompt and knowledge-base settings endpoints. - name: Voice Agent Settings description: >- Read and change a voice agent's voice, prompt and knowledge-base settings. A voice agent has one prompt (its instructions, greeting and conversation settings). Read the schema of a settings group, then update one `key`/`value` pair per request. - name: Tools description: >- Create, configure, enable and execute agent tools. Tools are enabled per voice agent with `agent_id`. These endpoints accept scoped API tokens only; every error uses the `{ "error", "message", "details" }` envelope with a stable `mf-core:tool-*` code. - name: Outbound Calls description: >- Place AI calls and review their outcome. Authenticate with the outbound API token from the **Outbound Calls** page. - name: Conversations description: >- List and inspect the conversations of your account, including transcripts when your retention settings allow. - name: Evals description: >- Evals are automated test conversations that check how a voice agent responds. A scenario contains cases; each case contains the caller's turns and what the agent must say or do. Run a scenario to get pass/fail results. paths: /api/v2/tools: post: tags: - Tools summary: Create a tool description: > Create a tool. Two payload shapes exist: - `function_type: external:api` creates an API tool from a `url` and an OpenAI-style `function_definition`. - Any other `function_type` with `creatable_via_api: true` in `GET /api/v2/tools/types` creates a built-in or provider-backed tool from its template; pass type-specific settings in `params`. Behaviours that belong to the agent itself (`system:end_call`, `system:transfer_call`, `system:check_forward_availability`, `system:check_warm_transfer_availability`, `system:get_caller_info`, `system:extract_intent`, `system:chat_handover`) are not creatable and are rejected with `mf-core:tool-invalid-function-type`. Call forwarding (`system:forward_call`), warm transfer (`system:warm_transfer`) and DTMF input (`system:dtmf_input`) are configurable and stay creatable. Cal.com tools (`cal:get_availability`, `cal:book_appointment`) require `params.eventTypeId` and `params.timezone`; a missing or invalid value is rejected with `mf-core:tool-validation-failed` and `details.missing_param` names the key. Call-forwarding and warm-transfer types create two tools (a check and an execute tool) and return both in `tools`. operationId: createTool requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/ExternalApiToolRequest' title: API tool - $ref: '#/components/schemas/BuiltInToolRequest' title: Built-in or provider tool examples: external_api: summary: API-request tool value: function_type: external:api url: https://api.example.com/customers/{{customer_number}} method: GET headers: Authorization: Bearer {{api_key}} access_token: example-api-key function_definition: type: function name: get_customer description: Look up a customer by customer number. parameters: type: object properties: customer_number: type: string required: - customer_number agent_id: 123 built_in: summary: Built-in tool value: function_type: system:dtmf_input name: collect_pin params: mode: fixed numDigits: 4 finishDigit: '#' agent_id: 123 calcom: summary: Cal.com tool value: function_type: cal:get_availability name: get_availability integration_id: 456 params: eventTypeId: 98765 timezone: Europe/Berlin responses: '201': description: The created tool, or tool pair. content: application/json: schema: $ref: '#/components/schemas/ToolWriteResponse' '400': $ref: '#/components/responses/ToolBadRequest' '401': $ref: '#/components/responses/ToolUnauthorized' '403': $ref: '#/components/responses/ToolForbidden' '404': $ref: '#/components/responses/ToolNotFound' '409': $ref: '#/components/responses/ToolConflict' '422': $ref: '#/components/responses/ToolUnprocessable' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' security: - scopedJwt: [] components: schemas: ExternalApiToolRequest: type: object description: >- Create an API tool. `integration_id` is ignored; the backing integration is created automatically. properties: function_type: type: string const: external:api description: Must be `external:api`. url: type: string pattern: ^https?:// description: >- URL to call. `{{param}}` placeholders are filled from the call arguments. method: type: string default: GET description: HTTP method, for example `GET` or `POST`. headers: type: object additionalProperties: type: string description: >- Request headers. `{{param}}` placeholders are filled from the call arguments; `{{api_key}}` resolves to the access token or OAuth token. fixed_parameters: type: object additionalProperties: true description: Values always sent with the request, not chosen by the agent. function_definition: $ref: '#/components/schemas/FunctionDefinition' description: OpenAI-style function schema. Its `name` becomes the tool name. name: type: string description: Optional. Must equal `function_definition.name`. access_token: type: string description: Mutually exclusive with `oauth_provider_id`. oauth_provider_id: type: - integer - 'null' description: >- ID of an OAuth connection in your account. Mutually exclusive with `access_token`. say_before: type: string description: Phrase the agent says before calling the API. condition: type: string description: When the agent should use this tool. agent_override_condition: type: string description: >- Condition override for one agent. Only applied when `agent_id` is given. response_fields: type: array items: type: string description: Fields of the API response the agent may use. response_variables: type: array maxItems: 25 items: $ref: '#/components/schemas/ResponseVariable' description: >- Values extracted from the response and stored as variables for later steps. prompt_id: type: integer description: Deprecated alias of `agent_id` (the agent's prompt id). deprecated: true agent_id: type: integer description: Enable the tool for this voice agent right away. required: - function_type - url - function_definition BuiltInToolRequest: type: object description: >- Create a built-in or provider-backed tool from its template. Use `GET /api/v2/tools/types` to discover the types with `creatable_via_api: true`. Types with `creatable_via_api: false` are rejected with `mf-core:tool-invalid-function-type`. properties: function_type: type: string description: >- Any type with `creatable_via_api: true` other than `external:api`, for example `system:forward_call`, `system:dtmf_input`, `send:sms` or `cal:get_availability`. Agent behaviours such as `system:end_call` are not accepted. name: type: string description: Tool name as the agent's model sees it. description: type: string description: What the tool does, as the agent's model sees it. integration_id: type: integer description: >- Required for types with `requires_integration: true`. Must belong to your account. params: type: object additionalProperties: true description: >- Type-specific configuration. See `params_schema_hint` in the types catalog. Cal.com tools require `eventTypeId` (positive integer, the Cal.com event type) and `timezone` (IANA name such as `Europe/Berlin`); both are applied by the agent on every call and are not exposed to the model. prompt_id: type: integer description: Deprecated alias of `agent_id` (the agent's prompt id). deprecated: true agent_id: type: integer description: Enable the tool for this voice agent right away. required: - function_type - name ToolWriteResponse: description: >- Returned by create and update. Call-forwarding and warm-transfer types return the pair. oneOf: - $ref: '#/components/schemas/ExternalApiTool' title: API tool - $ref: '#/components/schemas/ToolSummary' title: Built-in or provider tool - $ref: '#/components/schemas/ToolPair' title: Tool pair FunctionDefinition: type: object description: OpenAI-style function schema. The tool name is taken from `name`. properties: type: type: string const: function description: Always `function`. name: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ description: 'Tool name: letters, digits, `_` and `-`, up to 64 characters.' description: type: string minLength: 1 description: When and why the agent should call this tool. parameters: type: object additionalProperties: true description: JSON Schema of the arguments the agent provides. required: - type - name - description additionalProperties: true ResponseVariable: type: object properties: key: type: string pattern: ^[a-z][a-z0-9_]*$ description: Variable name, lower snake_case. path: type: string description: Path to the value in the response, for example `data.customer.name`. default_value: type: string description: Used when the path is missing. required: - key - path description: One value extracted from the API response. ExternalApiTool: type: object description: Full configuration of an API tool. Secrets are never returned. properties: id: type: integer description: ID of the tool. name: type: string description: >- Tool name as the agent's model sees it. Equals `function_definition.name`. description: type: - string - 'null' description: >- What the tool does. Empty for API tools; the model reads `function_definition.description`. function_type: type: string const: external:api description: Always `external:api`. integration_id: type: integer description: ID of the integration created for this tool. ai_action_id: type: - integer - 'null' description: ID of the action record backing this tool. external_api: type: object properties: url: type: - string - 'null' method: type: string description: HTTP method, for example `GET` or `POST`. headers: type: object additionalProperties: type: string description: >- Request headers. `{{param}}` placeholders are filled from the call arguments; `{{api_key}}` resolves to the stored access token or OAuth token. fixed_parameters: type: object additionalProperties: true description: Values always sent with the request, not chosen by the agent. access_token_set: type: boolean description: True when an access token is stored for this tool. oauth_provider_id: type: - integer - 'null' description: ID of the OAuth connection used for authentication, if any. say_before: type: string description: Phrase the agent says before calling the API. condition: type: string description: When the agent should use this tool. response_fields: type: array items: type: string description: Fields of the API response the agent may use. response_variables: type: array items: $ref: '#/components/schemas/ResponseVariable' description: >- Values extracted from the response and stored as variables for later steps. required: - url - method - headers - fixed_parameters - access_token_set - oauth_provider_id - say_before - condition - response_fields - response_variables description: How the API is called. function_definition: type: object additionalProperties: true description: >- OpenAI-style function schema the agent's model uses to decide when and how to call the tool. enabled_for_agent: type: boolean description: >- Only returned by create. True when `agent_id` was supplied and the tool was enabled for that agent. required: - id - name - description - function_type - integration_id - ai_action_id - external_api - function_definition ToolSummary: type: object description: >- Minimal tool record returned by create and update for built-in and provider-backed tools. properties: id: type: integer description: ID of the tool. name: type: string description: Tool name as the agent's model sees it. description: type: - string - 'null' description: What the tool does, as the agent's model sees it. function_type: type: - string - 'null' description: Tool type, for example `system:end_call`. required: - id - name - description - function_type additionalProperties: false ToolPair: type: object description: >- Call-forwarding and warm-transfer tools consist of a check tool and an execute tool. properties: tools: type: array minItems: 2 maxItems: 2 items: $ref: '#/components/schemas/ToolSummary' required: - tools ApiError: type: object description: >- Error format with a stable machine-readable `error` code, a human-readable `message` and request-specific `details`. properties: error: type: string description: >- Stable machine-readable error code, for example `mf-core:rate-limit-exceeded`. message: type: string description: Human-readable explanation. details: type: object additionalProperties: true description: >- Request-specific data, for example the offending parameter or the quota policy. required: - error - message - details responses: ToolBadRequest: description: >- Missing or invalid parameters, an unknown `function_type`, a type with `creatable_via_api: false`, or a type without a template. Also returned for a malformed JSON body. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: arguments: value: error: mf-core:tool-invalid-arguments message: Tool request is invalid details: {} functionType: value: error: mf-core:tool-invalid-function-type message: Invalid function_type details: {} template: value: error: mf-core:tool-template-not-found message: No template is available for this function type details: {} ToolUnauthorized: description: >- The request did not carry a valid scoped API token. Browser sessions and legacy API keys are rejected on the Tools endpoints. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: missing: value: error: mf-core:tool-authentication-failed message: Missing authorization token details: {} expired: value: error: mf-core:tool-authentication-failed message: Token expired details: {} invalid: value: error: mf-core:tool-authentication-failed message: Invalid authorization token details: {} ToolForbidden: description: >- The token lacks the required scope (`details.scope` names it), the tool's integration is not enabled for your account, or your plan does not include the tool type. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: scope: value: error: mf-core:tool-scope-required message: Required tool scope is missing details: scope: tools:write feature: value: error: mf-core:tool-feature-disabled message: This tool integration is not enabled details: {} warmTransfer: value: error: mf-core:tool-warm-transfer-unavailable message: Warm transfer is unavailable details: {} plan: value: error: mf-core:plan-warm-transfer-not-entitled message: Your plan does not include warm transfer details: {} ToolNotFound: description: Tool, voice agent or integration not found in your account. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: tool: value: error: mf-core:tool-not-found message: Tool not found details: {} prompt: value: error: mf-core:tool-prompt-not-found message: Prompt not found details: {} integration: value: error: mf-core:tool-integration-not-found message: Integration not found details: {} agent: value: error: mf-core:tool-agent-not-found message: Voice agent not found details: {} ToolConflict: description: An API tool with the same name already exists. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: name: value: error: mf-core:tool-name-conflict message: A tool with this name already exists details: {} ToolUnprocessable: description: >- The tool configuration was rejected. `details` carries safe occurrence data such as the API-tool validation `reason`, the rejected forwarding entry's `intent_index` or the `missing_param` of a Cal.com tool; request values are never echoed. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: validation: value: error: mf-core:tool-validation-failed message: Tool configuration is invalid details: {} calcom: value: error: mf-core:tool-validation-failed message: Tool configuration is invalid details: missing_param: timezone externalApi: value: error: mf-core:tool-external-api-validation-failed message: API request tool configuration is invalid details: reason: invalid_url nameTaken: value: error: mf-core:tool-name-taken message: A tool with this name already exists details: {} template: value: error: mf-core:tool-template-invalid message: Tool template is missing or invalid details: {} forwarding: value: error: mf-core:tool-forwarding-target-disallowed message: Forwarding targets must use +49, +43 or +41 details: intent_index: 0 dtmf: value: error: mf-core:tool-dtmf-already-active message: A DTMF tool is already active on this prompt details: {} delete: value: error: mf-core:tool-delete-failed message: Tool could not be deleted details: {} RateLimited: description: >- Too many requests. Wait the number of seconds given in `Retry-After` before retrying. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: mf-core:rate-limit-exceeded message: Rate limit exceeded details: policy: api_write retry_after: 3 ServiceUnavailable: description: >- The request was not completed. Either it exceeded the 30-second request time limit that applies to every API call (narrow the request and retry), or rate limiting is temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: timeout: value: error: mf-core:api-request-timeout message: The API request exceeded the 30-second time limit details: {} limiter: value: error: mf-core:rate-limiter-unavailable message: API rate limiting is temporarily unavailable details: policy: api_write securitySchemes: scopedJwt: type: http scheme: bearer bearerFormat: JWT description: >- Scoped API token. Required scopes are listed on each operation in x-required-scopes. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.