---
title: "Execute Tool"
method: POST
path: "/api/assistant/tool/{name}"
tags: ["Assistant"]
---

# Execute Tool

`POST /api/assistant/tool/{name}`

Execute a tool on behalf of the assistant and continue the conversation with the result. Note that more permissions may be checked depending on the tool being executed.

## Path parameters

- `name` string, required

## Request body

- ModelToolRequest

## Response `200`

AI assistant response messages after tool execution

- ModelMessage[]
  - `id` string — The unique identifier for the message. Not required.
  - `role` string — Indicates who authored the message. Either `user` or `assistant`.
  - `stop_reason` string — The reason the message was stopped.
  - `stop_sequence` string — The sequence in which the message was stopped.
  - `thoughts` string — The plain text thoughts from the model's response
  - `usage` ModelUsage — Usage statistics after deducting the costs of the message.
    - `credits` integer — The number of credits remaining after this message.
    - `input_tokens` integer — The number of input tokens used.
    - `output_tokens` integer — The number of output tokens used.

## Other responses

- `400` — The provided input object or parameters are malformed or invalid
- `401` — Request was not properly authenticated
- `403` — Insufficient permissions for this request
- `500` — Internal SOC error; review SOC logs

## Changes

- **2026-02-27** `c7b650ad3d3e` — 1 info
  - added the optional property `items/thoughts` to the response with the `200` status
- **2025-10-23** `dd1538426ed4` — 1 info
  - endpoint added
- **2024-12-10** `ee1120fd1e20` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/security-onion-solutions/apis/security-onion-connect-api/changes/api/assistant/tool/:name/post.md)

---

[API](https://skmtc.dev/security-onion-solutions/apis/security-onion-connect-api.md) · [All operations](https://skmtc.dev/security-onion-solutions/apis/security-onion-connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/security-onion-solutions/security-onion-connect-api/revisions/0576ce393f8d/schema)