curl --request PATCH \
--url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/tools/{toolId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/tools/{toolId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/tools/{toolId}"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"type": "file_search",
"name": "<string>",
"display_name": "<string>",
"description": "<string>",
"catalog_id": "<string>",
"auth": {},
"icon_url": "<string>",
"vector_store_id": "<string>",
"server": "<string>",
"headers": {},
"scope": "<string>",
"url": "<string>",
"parameters": {},
"tool_filter": {
"mode": "allow",
"tools": [
"<string>"
]
}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}Update a tool attached to an agent
Shallow-merges the body into the entry (matched by id, or by name
when it has none). id, type, catalog_id, auth and icon_url
are ignored: they stay as attached. The resulting tools[] is checked
like PATCH /v1/agents/{agentId} (tool names, tool_filter shape,
knowledge base access). When the agent is published,
has_draft_changes is set to true. Returns the updated entry.
curl --request PATCH \
--url https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/tools/{toolId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{}'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/tools/{toolId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:agent-factory/webhooks/v1/agents/{agentId}/tools/{toolId}"
payload = {}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"id": "<string>",
"type": "file_search",
"name": "<string>",
"display_name": "<string>",
"description": "<string>",
"catalog_id": "<string>",
"auth": {},
"icon_url": "<string>",
"vector_store_id": "<string>",
"server": "<string>",
"headers": {},
"scope": "<string>",
"url": "<string>",
"parameters": {},
"tool_filter": {
"mode": "allow",
"tools": [
"<string>"
]
}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}Authorizations
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
64128Body
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).
128^[a-zA-Z0-9_-]+$2564096file_search only. A knowledge base the caller can read, in the agent's organization (403 otherwise).
12820482562048MCP 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).
file_search, mcp, function ^[a-zA-Z0-9_-]+$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.
Required for file_search.
MCP server URL (for mcp).
Required for function.
JSON Schema describing the function tool's parameters.
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.
Was this page helpful?