Update Agent Tool | SpeechifyAI API

curl -X PATCH https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/tools/tool_01jqr8x9zg5k2m3n4p5q6r7s8t \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Example name",
  "description": "Example description.",
  "config": {
    "builtin": "example",
    "builtin_config": {},
    "params": [
      {
        "description": "Example description.",
        "name": "Example name",
        "required": true,
        "type": "string"
      }
    ]
  },
  "params": [
    {
      "name": "Example name",
      "type": "string",
      "description": "Example description.",
      "required": true,
      "enum": []
    }
  ],
  "enabled": true
}'

{
  "id": "tool_01kb9kefcacry5t3662gfsgtzj",
  "kind": "builtin",
  "name": "Example name",
  "description": "Example description.",
  "enabled": true,
  "definition_id": "definition_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "config": {
    "builtin": "example",
    "builtin_config": {},
    "params": [
      {
        "description": "Example description.",
        "name": "Example name",
        "required": true,
        "type": "string"
      }
    ]
  },
  "created_at": "2026-06-24T18:03:11Z",
  "updated_at": "2026-06-24T18:03:11Z",
  "webhook_secret": "whsec_01jqr8x9zg5k2m3n4p5q6r7s8t"
}

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/{tool_definition_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/{tool_definition_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

agent_idstringRequired

Agent id (prefixed external id, agent_...).

tool_idstringRequired

Tool id (prefixed external id, tool_...).

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 headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The updated tool.

idstringformat: "^tool_[0-9a-hjkmnp-tv-z]{26}$"

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/{tool_definition_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