Troubleshoot Tools

Start with the Tool definition, then inspect Activity in Conversation detail for the exact tool_call status, error, duration, arguments, assigned values, and a bounded result preview. Secret values are deliberately absent.

Request never reaches the endpoint#

Operade rejects non-HTTP URLs and any hostname whose DNS answers include a private, loopback, link-local, or otherwise non-global address. DNS is checked before every call, the public address is pinned for the connection, and redirects are not followed. A private address failure therefore happens before your service sees a request.

Also check for a missing path argument, invalid JSON Schema arguments, a deleted Tool, or a missing Secret. These failures occur before HTTP. A timeout uses the Tool's configured limit and is reported to the model without exposing low-level network details.

Endpoint responds with an error#

HTTP 400 or higher is a failed Tool result. The model receives a bounded error, and response assignments are not extracted. Verify method, URL, query/body routing, authentication mode, and the remote service logs. Operade accepts at most 256 KB of response content; keep responses small and return only fields the agent needs.

A successful response does not need to be JSON unless you configured assignments. Empty success responses become an acceptance message. Non-JSON responses can still inform the model, but cannot produce assigned variables.

Missing or changed behavior#

Deleting a Tool does not check active-resource references. Agent Tool lists skip the missing Tool, so attached Agents continue without that ability. A Procedure or Workflow that still depends on it can fail validation or runtime checks. Detach stale IDs, save the draft, and test again before publishing.

Use the Tool API reference to compare the stored definition, then revisit parameters and authentication.