---
title: "Execute a tool"
method: POST
path: "/api/tools/{name}/execute"
tags: ["execution"]
---

# Execute a tool

`POST /api/tools/{name}/execute`

## Request

- Base URL: `https://claw-link.dev`
- URL: `https://claw-link.dev/api/tools/{name}/execute`
- Auth: one of:
  - API key in header `x-clawlink-api-key`
  - HTTP bearer

Runs the named tool against the user's connected app. Write and destructive tools are refused with HTTP 412 unless the request sets "confirmed": true. When the user has several connections for one app, pass "connectionId" to pick one; omitting it uses the default connection. On failure, read "error.message" and "hint": they are written for agent self-correction.

## Path parameters

- `name` string, required

## Request body

- object
  - `arguments` object: Tool arguments matching the input schema from describeTool. If "arguments" is omitted, all top-level body fields except connectionId, confirmed, and files are treated as the arguments.
  - `connectionId` union: Connection id from the user's account. Omit to use the default connection for the tool's integration.
    - integer
    - string
  - `confirmed` boolean: Required as true for write and destructive tools.
  - `files` FileAttachment[]: File attachments for tools with file-uploadable fields. Total decoded size is capped at 100 MB per request (HTTP 413 above it).
    - `pointer` string, required: JSON pointer to the file-uploadable field in the arguments this attachment fills.
    - `name` string, required: File name.
    - `mimetype` string, required
    - `md5` string, required: MD5 hex digest of the raw bytes.
    - `dataBase64` string, required: Base64-encoded file bytes.

## Response `200`

Execution succeeded

- ExecutionResult: Execution envelope returned for both success and failure. On failure, "error.message" and "hint" are written for agent self-correction; "details" may carry additional lines.
  - `ok` boolean, required
  - `result` unknown
  - `data` unknown
  - `error` object, nullable
    - `code` string: Machine-readable code, for example needs_connection, confirmation_required, tool_not_found.
    - `type` string: Error class, for example validation, auth, missing_scopes, rate_limit.
    - `message` string
  - `hint` string: Actionable next step for the agent.
  - `details` string[]
  - `requiresConfirmation` boolean
  - `canonical` object: Canonical execution summary.

## Other responses

- `400`: Invalid arguments or malformed files envelope
- `401`: Missing or invalid API key, or the connection needs re-authentication
- `402`: Billing limit reached
- `403`: The connection is missing OAuth scopes the tool needs
- `404`: Tool not found
- `409`: No connection for the integration, or several connections and no connectionId given
- `412`: Confirmation required: re-send with "confirmed": true after the user approves
- `413`: Files envelope over the 100 MB cap
- `422`: Integration configuration problem
- `429`: Provider rate limit
- `503`: Upstream provider unavailable
- `default`: Execution failed

---

[API](https://skmtc.dev/claw-link/apis/clawlink-agent-api.md) · [All operations](https://skmtc.dev/claw-link/apis/clawlink-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/claw-link/apis/clawlink-agent-api/revisions/6ce0c62d160a?raw)