Set tool background-safe
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.
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_background_safe" \ -H "Content-Type: application/json" \ -d '{ "backgroundSafe": true, "agent": "string" }'{}{
"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 term blocklist POST
Set the workspace's exact-match term blocklist, deterministic term blocking. Available only to a workspace whose plan includes it; the operation refuses otherwise, and enabling it is a conversation with the Vertical AI team rather than a setting. Unlike safety guardrails, which score a confidence and act above a threshold, this matches literally: a term either appears or it does not, so there is no sensitivity to set. `terms` REPLACES the whole list, send every term you want blocked, or an empty array to clear it. Each term is trimmed, empties are dropped, and duplicates are removed case-insensitively. A term may be at most 3 words and may not contain a line break, and the list is capped at 10000 entries, which is the engine's own ceiling. Use it for a specific, enumerable list the business must never say: competitor names, a claim its legal team has not cleared, a term a regulator has asked it to stop using. Do NOT use it to steer a topic. Exact matching has no sense of context and the failure is silent, a dental practice that blocks "extraction" has stopped its agent discussing the procedure it books most, and nobody finds out until bookings fall. Topics belong in the system prompt, where the model can weigh them in context.
Edit tool description POST
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.