Tool safety errors

Webhook tools can call destinations chosen by a workspace, so Operade validates destinations and keeps Secret values out of agent-visible history. Safety rejection is a boundary, not a transient network problem.

Symptom#

A Tool cannot be saved or executed, a request to a private address is rejected, a redirect is blocked, or runtime reports that a referenced Tool is missing. An upstream timeout or non-success response may also stop the Tool path.

Cause#

Operade rejects malformed URLs, local and private-network addresses, unsafe redirects, invalid parameter placement, missing references, and invalid runtime outputs. A public hostname that resolves to a private destination is rejected. Workflow and Procedure references are checked again when they run because resources can change after a draft was authored.

Verify#

Confirm the Tool URL uses an allowed public destination, every redirect stays public, path parameters exist, and required query or body values are supplied. Verify referenced Secrets still exist without exposing their values. Use the Activity view to distinguish validation, network, upstream, and workflow failures.

Recovery#

Correct the destination or parameter mapping, restore the referenced Tool or Secret, then run a new Test Chat. For an upstream timeout, verify the remote service independently and retry once. Never bypass destination validation with an alternate IP, redirect, or encoded host.

Escalation#

Escalate only after the public endpoint works independently and a new Test Chat still fails. Include the hostname, method, safe parameter names, UTC time, and visible code; remove headers and customer payloads. See Tool troubleshooting, Authentication and Secrets, and Activity.

Known boundaries#

Tool-safety failures commonly use the general validation_failed or workflow_failed code, depending on whether the problem is found while authoring or while executing. The canonical home for those codes is Errors and recovery or Workflow and Procedure errors; this page explains the Tool-specific checks.

Google Sheets capability locks and runtime failures have their own Google Sheets error reference.