Update Agent Tool

PATCH

https://api.speechify.ai/v1/agents/:id/tools/:toolId

PATCH

/v1/agents/:id/tools/:toolId

$ curl -X PATCH https://api.speechify.ai/v1/agents/id/tools/toolId \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "id": "tool_01kb9kefcacry5t3662gfsgtzj",
3   "kind": "builtin",
4   "name": "Call Transfer",
5   "description": "Transfers the call to a specified phone number.",
6   "enabled": true,
7   "definition_id": "null",
8   "config": {
9     "builtin": "transfer_to_number",
10     "params": [
11       {
12         "name": "phone_number",
13         "type": "string",
14         "description": "The phone number to transfer the call to.",
15         "required": true,
16         "enum": []
17       }
18     ],
19     "builtin_config": {}
20   },
21   "created_at": "2024-01-15T09:30:00Z",
22   "updated_at": "2024-01-15T09:30:00Z",
23   "webhook_secret": ""
24 }

Update one of the agent’s tools. For a built-in, every field applies. For an attached external tool, only enabled is editable here — its shared config/name is edited on the definition (PATCH /v1/agents/tool-definitions/{id}), since the definition is referenced live by every agent it is attached to; attempting a shared-config edit here returns tool_config_shared.

Update one of the agent's tools. For a built-in, every field applies. For an attached external tool, only `enabled` is editable here — its shared config/name is edited on the definition (`PATCH /v1/agents/tool-definitions/{id}`), since the definition is referenced live by every agent it is attached to; attempting a shared-config edit here returns `tool_config_shared`.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

idstringRequired

toolIdstringRequired

Request

This endpoint expects an object.

namestringOptional

descriptionstringOptional

configobjectOptional

For a built-in, the full BuiltinToolConfig. Rejected for shared kinds.

paramslist of objectsOptional

enabledbooleanOptional

Response

The updated tool.

idstring

Prefixed wire identifier (tool_<26 char Crockford base32>), stable across kinds.

kindenum

What kind of tool this is, and where it executes.

builtin: a worker-resident platform capability (e.g. end_call, play_audio), configured per-agent
webhook: worker signs a payload and POSTs it to your URL
client: worker dispatches to the caller’s browser/SDK via data channel
mcp: worker connects to a customer-hosted MCP server and proxies tool calls

namestring

descriptionstring

enabledboolean

When false the tool is configured but skipped at dispatch.

definition_idstring or null

Provenance: the backing workspace tool definition id for shared kinds (webhook/client/mcp), or null for a built-in. Non-null ⟺ the tool’s config is shared and edited at /v1/agents/tool-definitions/{id}.

configobject

Resolved config - BuiltinToolConfig, WebhookToolConfig, ClientToolConfig, or MCPToolConfig depending on kind.

created_atdatetime

updated_atdatetime

webhook_secretstring

HMAC signing secret for a webhook tool. Returned in full only on the create response; subsequent reads return a masked placeholder.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error