---
title: "Invoke one agent tool directly"
method: POST
path: "/v1/agent/tools/{name}/invoke"
tags: ["Agent"]
---

# Invoke one agent tool directly

`POST /v1/agent/tools/{name}/invoke`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/agent/tools/{name}/invoke`
- Auth: HTTP bearer

Run ONE named tool directly, with no model in the loop: the caller supplies the
arguments the agent would otherwise choose. This is the seam for building your
own agent on top of Talonic's retrieval and provenance while driving control
flow yourself.

The same capability matrix the agent loop applies governs this route, so a key
can only run the tools whose `can_invoke` is `true` on `GET /v1/agent/tools`;
a denied tool answers `403` naming the capability it needs. `scope` and
`on_behalf_of` behave exactly as on `POST /v1/ask`: the scope is a bound SQL
predicate, and `on_behalf_of` applies that user's compartment visibility.

Direct invocation charges no credits: every tool this key can reach does no
model work, so there is no model call to meter. The route is bounded by the
`agent_tools` rate-limit namespace instead. A tool that runs but fails answers
`422` with the tool's own failure summary.

## Path parameters

- `name` string, required

## Request body

- object
  - `args` object: Arguments matching the tool's `input_schema` from `GET /v1/agent/tools`.
  - `scope` object: Restrict the invocation to a slice of the workspace, exactly as on `POST /v1/ask`.
  - `on_behalf_of` string, uuid: Apply this workspace user's compartment visibility to the invocation.

## Response `200`

The tool ran; its raw output plus any cards, artifacts, and citations.

- object
  - `tool` string
  - `ok` boolean
  - `content` string: The tool's raw output, usually JSON serialized as a string.
  - `cards` object[]
  - `artifacts` object[]
  - `citations` object[]
    - `quote` string
    - `document_id` string, uuid
    - `kind` 'field' | 'quote'
    - `reference` string
    - `filename` string, nullable
    - `app_url` string

## Other responses

- `401`: Missing or invalid API key.
- `403`: The tool requires a capability this key's role does not grant; the message names it.
- `404`: The requested resource was not found.
- `422`: The tool itself failed; the message is the tool's failure summary.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)