> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute a specific tool

> Execute a project tool synchronously with caller-supplied parameters and get its result.

[Back to the Tools Execution API overview](https://koreai.mintlify.site/agent-platform/api-reference/tool-execution-overview.md)

Executes a tool in a project and returns its result. The request supplies the tool's caller-defined input parameters in a JSON body. Execution is synchronous: the request waits for the tool to complete or reach its timeout.

Use this endpoint to run an executable tool after [identifying it](https://koreai.mintlify.site/agent-platform/api-reference/tools-execute-table-tools-list) and [retrieving its input schema](https://koreai.mintlify.site/agent-platform/api-reference/tools-execute-table-tools-retrieve). The tool's output is returned without being reshaped by the platform, except that an Agent Table tool's output is returned as a JSON object.

**Permission:** `tool:execute`, granted by the platform API key scope `tools.execute`.

## Path parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `projectSlug` | string | Yes | Project slug, not the project ID or UUID. A project UUID returns `404`. |
| `toolName` | string | Yes | Tool name as authored. For MCP tools, use the `alias__toolName` format. |

## Request body

Send a JSON object with the following properties:

| Property | Type | Required | Description |
| - | - | - | - |
| `params` | object | Yes | Tool input matching the `input` schema returned by the Describe a tool endpoint. |
| `timeout` | integer | No | Per-call timeout in milliseconds. Minimum: `1000`; maximum: `300000`. |
| `mode` | string | No | Execution mode. Omit this property or set it to `sync`. Other values return `400 ASYNC_NOT_SUPPORTED`. |

The request body is strict. Unknown top-level properties and platform-derived fields are rejected rather than ignored. Platform-derived fields include values such as `tenantId`, `environment`, and `agentSession`.

For Agent Table tools without a query template, `params` contains a structured call with `op` and the operands for that operation. The accepted operations depend on the tool's binding.

## Authentication

Use one of the supported credentials:

* `x-api-key: abl_...` for a platform API key.
* `Authorization: Bearer <abl_... | JWT>` for a platform API key or Studio user JWT.
* `auth: <assertion>` for a JWT App assertion.

Public SDK keys (`pk_...`) are not accepted. The JWT App assertion must be sent in the `auth` header, not the `Authorization` header.

The credential must have the `tool:execute` permission. A sensitive-column lookup also requires `table:sensitive:reveal`.

A JWT App created with payload encryption enforced doesn't send a plain JSON body. It sends a JWE in compact serialization with `Content-Type: application/jose` and receives `application/jose` back. Errors from the encryption layer, such as `PAYLOAD_MALFORMED` or `PAYLOAD_DECRYPT_FAILED`, are returned unencrypted.

## Response

A successful response contains `success` and `data`. The `data` object includes the execution `status`, the tool's `output` when provided, and `trace` information when the caller is entitled to it.

A `200` response means the tool ran. The `status` field reports the tool executor's own outcome.

The response headers identify the tool type, resolved environment, and configuration source:

| Header | Description |
| - | - |
| `X-ABL-Tool-Type` | Type of tool that ran. |
| `X-ABL-Environment` | Environment against which the tool definition was resolved. Always `draft` on this API surface. |
| `X-ABL-Config-Source` | Indicates whether the configuration came from a pinned version or the working copy. |

For Agent Table tools, `output` is a JSON object rather than a serialized JSON string. For other tool types, the output is returned without platform-level reshaping.

## Execution considerations

* Only tool types enabled for public API execution can be invoked. Agent Table tools are enabled by default; other supported types require explicit enablement.
* A tool's declared effect can indicate whether it is read-only, writes state, or has side effects. Review this metadata before invoking the tool.
* Tool failures are returned using status codes appropriate to the failure. Do not assume every execution failure is a transient server error or safe to retry.

## Errors

| HTTP status | Description |
| - | - |
| `400` | Malformed or invalid request, unknown key, unsupported platform field, unsupported execution mode, or forbidden operation. |
| `401` | Missing or invalid credentials, or an unsupported public SDK key. |
| `403` | Missing execution permission, insufficient project scope, or a sensitive-column lookup without the required permission. |
| `404` | Project or tool not found, tool type disabled, tool not executable, or public execution disabled. Some of these cases intentionally return the same response. |
| `409` | Conflict requiring caller action, such as a unique-constraint violation, row-version conflict, or unsupported authentication-profile mode. |
| `413` | Request payload exceeds the allowed size or structural limits. The caller payload limit is 512 KiB serialized, a depth of 32, and 10,000 nodes. The global body limit is 1 MiB. |
| `415` | Unsupported media type or charset. A JWT App configured to require payload encryption must use the required encrypted format. |
| `422` | Tool configuration or execution failure, invalid tool response, or SOAP fault. |
| `429` | Tenant request or tool-call rate limit exceeded. |
| `500` | Unexpected execution failure. This also covers an undeclared parameter that the tool's policy rejects. |
| `502` | Tool network, HTTP, authentication, or upstream failure. |
| `503` | A dependency is unavailable, such as an MCP server or Agent Table service. |
| `504` | The tool did not respond within its timeout. |

The `429` response uses a rate-limiter-specific response format rather than the standard API error envelope. Check the response headers for rate-limit information and retry guidance.

For transient dependency failures (`503`), retry with backoff. Resolve conflicts such as `409` before retrying. Do not automatically retry operations with side effects unless their retry behavior is known to be safe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.