Skip to main content
PATCH
Update a tool

Authorizations

Authorization
string
header
required

Your organization API key (it starts with anek_org_). The same key works on the Voice API and the Support API. See Authentication.

Path Parameters

projectId
string
required

Project id

id
string
required

Tool id

Body

application/json

Send the fields to change; the others keep their value. Fields not listed here are ignored. On hold_message, hold_messages, async_config, session and parameter_mapping, null clears the stored value.

name
string
Minimum string length: 1
Pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
description
string
agent_id
string | null

Move the tool to this agent's private tools, or null to make it project-wide. Refused while other agents use the tool.

type
enum<string>
Available options:
http,
knowledgebase,
code,
builtin,
workflow,
messaging,
handoff,
ticket
configs
http · object

The tool's configuration. Its shape depends on the tool's type, and it is checked against that type; on update without type, against the stored type. builtin takes one of three shapes, by action.

parameters
object | null

JSON Schema of the arguments the model passes.

parameter_mapping
object | null
hold_message
string | null
hold_messages
object | null
async_config
object | null

Lets the conversation go on while the tool runs instead of waiting for the result. Not allowed on builtin tools. null turns it off.

session
object | null

The tool's part in the call-scoped caller authentication session. Null means the tool takes no part. A non-null verification makes it a verification tool and carries the verification policy; caller authentication is on for an agent exactly when an attached tool verifies the caller or requires a verified caller. On PATCH, an absent key keeps the stored value and an explicit null clears it.

channels
enum<string>[]

For a tool from the organization tool library, which kinds of agents can use it.

Required array length: 1 - 2 elements
Available options:
chat,
voice

Response

The tool, updated.

A tool an agent can call during a conversation. Project-wide tools (agent_id: null) can be attached to any agent of the project; a private tool belongs to one agent.

id
string
required

Tool id.

project_id
string
required
agent_id
string | null
required

The agent the tool is private to, or null for a project-wide tool.

name
string
required

The name the model calls the tool by.

description
string
required

What the tool does and when to use it, as the model reads it.

type
string
required

What the tool does, which decides the shape of configs: http, knowledgebase, code, builtin, workflow, messaging, handoff or ticket.

configs
object
required

The tool's configuration, in the shape of its type (see configs in Create a tool). It can also carry values Clarity fills in on save, such as a workflow's url or a knowledge base's search target.

parameters
object
required

JSON Schema of the arguments the model passes when it calls the tool.

parameter_mapping
object | null
required

Renames arguments before the request is built, {argument: request_field}. null when none.

hold_message
string | null
required

What the agent says while the tool runs, or null for nothing.

hold_messages
object | null
required

The hold message per language of a multilingual agent, keyed by language label.

async_config
object | null
required

Settings that let the conversation go on while the tool runs, in the shape of async_config in Create a tool. null means the agent waits for the result.

session
object | null
required

The tool's part in the call-scoped caller authentication session. Null means the tool takes no part. A non-null verification makes it a verification tool and carries the verification policy; caller authentication is on for an agent exactly when an attached tool verifies the caller or requires a verified caller. On PATCH, an absent key keeps the stored value and an explicit null clears it.

updated_at
integer<int64> | null
required

When the tool was last changed, in milliseconds since the Unix epoch. null for a tool not changed since this field was added.

library_tool_id
string | null

The organization tool library entry this tool comes from, or null for a tool that belongs to this project only.

library_revision
integer | null

The library entry's revision this tool holds, or null.

library_channels
string[] | null

Which kinds of agents (chat, voice) can use the library entry, or null.

used_by_count
integer

How many agents of the project have the tool attached. A published agent keeps calling the tool it was published with until it is published again, whatever this count says. Present on reads and lists.

used_by_agents
object[]

The agents the tool is attached to. Returned when you get one tool, not in lists.