Update Client Tool

PATCH /client-tools/:id Edit a catalog tool. Any of description, url, method, parameters, headers, query_parameters, or timeout_ms that changes is propagated to every agent that has assigned (inherited) this tool, along with is_active. Voice/runtime fields (speak_during_execution, speak_after_execution, response_variables, execution_message_type, execution_message_description) and sort_order/llm_response_fields are copied once at assign time but are not propagated by later edits — they become workflow-scoped.

Path Parameters

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	Client tool ID

Request Body

Any subset of the fields below. At least one is required.

Field	Type	Required	Description
`description`	string	No	Non-empty, max 1024 characters. Cannot be cleared to null/blank
`url`	string	No	Non-empty. Cannot be cleared to null/blank
`method`	string	No	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
`parameters`	object	No	JSON-schema-style object describing the tool’s call arguments
`headers`	object	No	Static headers sent with every call
`query_parameters`	object	No	Static query string params sent with every call
`timeout_ms`	integer	No	Clamped to 1,000–120,000
`speak_during_execution`	boolean	No	Workflow-scoped after assign — not propagated
`speak_after_execution`	boolean	No	Workflow-scoped after assign — not propagated
`response_variables`	object	No	Workflow-scoped after assign — not propagated
`execution_message_type`	string	No	Workflow-scoped after assign — not propagated
`execution_message_description`	string	No	Workflow-scoped after assign — not propagated
`llm_response_fields`	string[]	No	Catalog-only, never copied or propagated
`is_active`	boolean	No	Propagated to inherited mirrors
`sort_order`	integer	No	Catalog-only, never copied or propagated

name cannot be changed here — delete and recreate the tool to rename it.

Responses

`200` — Updated

{
  "success": true,
  "tool": {
    "id": "7c1b2c3d-0000-4000-8000-000000000002",
    "name": "check_subscription",
    "description": "Checks whether the lead has an active subscription and its plan tier",
    "url": "https://api.acme.com/subscriptions/status",
    "method": "GET",
    "timeout_ms": 10000
  },
  "propagated_workflow_tools": 3
}

propagated_workflow_tools is the number of inherited workflow_tools rows updated by this edit (0 if the update touched only non-propagated fields). See List Client Tools for the full ClientTool field reference.

`400` — Validation error

{
  "error": "Invalid input",
  "message": "name is immutable (the agent references it); delete + recreate to rename"
}

Also returned as "description must be a non-empty string", "description must be at most 1024 characters", "url must be a non-empty string", "method must be one of: GET, POST, PUT, PATCH, DELETE", "timeout_ms must be a number", or "Nothing to update".

`401` — Authentication error

See Authentication.

`404` — Not found

{
  "error": "Not found",
  "message": "Tool not found"
}

​Path Parameters

​Request Body

​Responses

​200 — Updated

​400 — Validation error

​401 — Authentication error

​404 — Not found

​500 — Internal server error