Add a tool to the draft
Validates definition and authorized references. Does not invoke a webhook or remote MCP tool. All tools execute unattended after publication. Reserved names end_call, transfer and transfer_to_number are refused with invalid_request on every write/validation; use default_tools. Secret headers pin an exact secret version; to adopt a rotated version, supply the new {secret_id, version} here and publish. An archived agent is refused with agent_archived. tool_name_conflict: another tool in this draft has the same name. conflict with details.reason=name_taken: the secret name of an inline credential is taken. resource_key_conflict: the resource_key of an inline credential is taken. Inline credential material also requires secrets.manage, because it creates a secret; a {secret_id, version} reference also requires secrets.read.
Authentication
Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.
Path parameters
Headers
Strong ETag from the resource being changed. Draft/tool/variable/publication operations use the complete agent draft ETag; number operations use the number ETag; MCP update uses its own ETag. Never retry a stale edit by blindly using a fresh ETag. Agent identity edits use the identity ETag; knowledge-source reingest uses the source ETag. A stale revision returns 409: draft_conflict for agent, draft, variable, tool, MCP server and publication-token checks; conflict with details.reason=stale_revision for phone numbers and knowledge sources. A missing header returns 428 revision_required. Same-intent replay uses the original If-Match and returns its receipt before checking current revision.
Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.
Request
Unattended execution only. Automatic retry of an idempotent webhook requires name and placement and an idempotent downstream contract; no automatic retry of unknown non-idempotent effects. Unknown side effect forbids automatic retry.
Unattended execution only. Automatic retry of an idempotent webhook requires name and placement and an idempotent downstream contract; no automatic retry of unknown non-idempotent effects. Unknown side effect forbids automatic retry. Tool name must equal definition.remote_tool_name.
Response headers
true when this response replays a stored Idempotency-Key result. The status and body equal the original.