> ## 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. # Execute a tool > Run a tool with the given arguments and return its result, for example to test an API tool. Test runs are not recorded in any conversation's tool history. When the tool itself fails, the response is `mf-core:tool-execution-failed` with the upstream HTTP status. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v2/tools/{id}/execute 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/{id}/execute: parameters: - name: id in: path required: true schema: type: integer description: ID of the tool. post: tags: - Tools summary: Execute a tool description: > Run a tool with the given arguments and return its result, for example to test an API tool. Test runs are not recorded in any conversation's tool history. When the tool itself fails, the response is `mf-core:tool-execution-failed` with the upstream HTTP status. operationId: executeTool requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ToolExecuteRequest' example: arguments: customer_number: '4711' responses: '200': description: The tool ran; its result. content: application/json: schema: $ref: '#/components/schemas/ToolExecutionResult' '400': $ref: '#/components/responses/ToolBadRequest' '401': $ref: '#/components/responses/ToolUnauthorized' '403': $ref: '#/components/responses/ToolForbidden' '404': $ref: '#/components/responses/ToolNotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ToolExecutionFailed' '503': $ref: '#/components/responses/ServiceUnavailable' security: - scopedJwt: [] components: schemas: ToolExecuteRequest: type: object properties: arguments: type: object additionalProperties: true description: >- Function-call arguments. If omitted, all other top-level body fields are used as arguments. context: type: object additionalProperties: true description: >- Optional context passed to the tool. Call-specific fields are ignored. ToolExecutionResult: type: object properties: function_call_process: type: string description: What the tool did, as a short status text. function_call_succeeded: type: boolean description: Whether the tool call succeeded. response: description: The tool's result, for example the parsed API response. status_code: type: integer description: HTTP status of the upstream API, when applicable. required: - function_call_process - function_call_succeeded additionalProperties: true description: Result of a successful tool run. 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: {} 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 ToolExecutionFailed: description: >- The tool ran but failed. The HTTP status of the upstream call is passed through when the tool reports one (for example 502 from the called API); the upstream response body is never returned. headers: Cache-Control: schema: type: string const: no-store content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: failed: value: error: mf-core:tool-execution-failed message: Tool execution failed details: {} 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.