Edit tool description
Update an existing tool's `description` and/or `displayName`. Identify the tool by toolName (its snake_case name) or toolId. The description is the highest-leverage prompt surface, the LLM reads it every turn. Most behaviour tweaks ('only call this after the caller has confirmed their phone', 'falls back to email if SMS fails') belong here, not in the system prompt.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/operations/set_tool_description" \ -H "Content-Type: application/json" \ -d '{ "agent": "string" }'{
"property1": null,
"property2": null
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Set tool background-safe POST
Mark whether an HTTP tool is a read-only / parallel-safe lookup or a write. Identify the tool by toolName (its snake_case name) or toolId. This is the single signal the runtime and the readiness validator both key off: a `backgroundSafe: true` tool runs without holding up the conversation, and on a slow lookup the agent tells the caller it is still working rather than going quiet; the validator treats it as a harmless read. A `backgroundSafe: false` tool is treated as a write that should usually require `verify_customer` first. **Use this to clear a false 'write tool with no preconditions' warning**, if the tool only fetches data and changes nothing (a plan catalogue, a coverage check, a usage lookup), the warning is firing because the tool is wrongly marked as a write; set `backgroundSafe: true` rather than adding `requires`. Only set `false` for tools that genuinely mutate customer state.
Set tool endpoint POST
Update an HTTP tool's method + URL (always together, they're coupled). Identify the tool by toolName (its snake_case name) or toolId. URL may contain `{{variable_name}}` placeholders.