Skip to main content
PATCH
Update a tool attached to an agent

Authorizations

Authorization
string
header
required

User-bound credential carrying an identity: either a session JWT or a user access token (at:*) generated from the user settings UI. Send as Authorization: Bearer <token>. Org API keys (iak_*) are not accepted here - they carry no user identity. Use the x-prismeai-api-key header instead (see OrgApiKeyAuth).

Path Parameters

agentId
string
required
Maximum string length: 64
toolId
string
required
Maximum string length: 128

Body

application/json

Fields to merge into a tool entry. id, type, catalog_id, auth and icon_url are ignored if sent. null clears a field (name excepted).

name
string
Maximum string length: 128
Pattern: ^[a-zA-Z0-9_-]+$
display_name
string | null
Maximum string length: 256
description
string | null
Maximum string length: 4096
vector_store_id
string | null

file_search only. A knowledge base the caller can read, in the agent's organization (403 otherwise).

Maximum string length: 128
max_num_results
number | null
server
string | null
Maximum string length: 2048
headers
object | null
scope
string | null
Maximum string length: 256
allowSelfSignedCert
boolean | null
url
string | null
Maximum string length: 2048
parameters
object | null
tool_filter
object | null

MCP tool selection (mcp entries). Names are the server's own tool names (tools/list name), never the <parent>__<child> canonical name. allow: only the listed tools are exposed, tools the server adds later stay hidden. deny: the listed tools are hidden, the others are exposed. Absent or null: every tool is exposed. An organization ceiling (the same shape on the capabilities catalog entry) applies on top; a tool must pass both. On any other tool type it is refused (400), except by POST /v1/agents/{agentId}/tools, which ignores it.

Response

Updated tool entry.

Tool entry attached to an agent. Discriminated by type - file_search (requires vector_store_id), mcp (uses server, headers, scope), or function (uses url, parameters, headers).

id
string
type
enum<string>
Available options:
file_search,
mcp,
function
name
string
Pattern: ^[a-zA-Z0-9_-]+$
display_name
string
description
string
catalog_id
string

Capabilities catalog entry the tool was added from. Fixed once the tool is attached - a tools array sent back through PATCH /v1/agents/{agentId} keeps the stored value - because the organization ceiling of an mcp entry is read through it. An mcp entry without one (a custom server) has no organization ceiling.

auth
object
icon_url
string
vector_store_id
string

Required for file_search.

server
string

MCP server URL (for mcp).

headers
object
scope
string
url
string

Required for function.

parameters
object

JSON Schema describing the function tool's parameters.

tool_filter
object | null

MCP tool selection (mcp entries). Names are the server's own tool names (tools/list name), never the <parent>__<child> canonical name. allow: only the listed tools are exposed, tools the server adds later stay hidden. deny: the listed tools are hidden, the others are exposed. Absent or null: every tool is exposed. An organization ceiling (the same shape on the capabilities catalog entry) applies on top; a tool must pass both. On any other tool type it is refused (400), except by POST /v1/agents/{agentId}/tools, which ignores it.