SYNAPLAN // DOCS
Launch app

03 / Using Synaplan

Tools & approvals

On this page 10

Some things an assistant does only read data. Others change something outside Synaplan — send mail, write a file, call an HTTP API. This page is how those actions are listed, how an operator decides what may run on its own, and how you approve the rest.

Since 4.8 the tool registry, approvals and custom HTTP tools are all on by default (TOOLS.REGISTRY_ENABLED, TOOLS.APPROVALS_ENABLED, TOOLS.CUSTOM_HTTP_ENABLED); an operator can switch any of them off under Operate → System configuration → Features → Tools & approvals. The registry switch doubles as a kill-switch: off restores the older per-loop catalogues.

In three sentences#

Every callable — web search, file tools, connected apps, and your own HTTP APIs — lives in one registry. Read-class tools run; write-class tools wait for you; destructive tools stay blocked unless you change the default. When something waits, a card appears in the chat and under Manage → Automations → Approvals.

Who this is for#

You are… What you do
Everyone Approve or reject a waiting action in chat or in the Approvals inbox. Pick instant email or a daily digest.
An operator Keep approvals and custom HTTP tools on (or switch them off), set the read / write / destructive defaults, and set how long a request waits.

What you see#

Chat#

When a write-class tool needs consent, the answer shows an approval card: what it wants to do, Approve, Reject, and Always allow for this assistant (a personal override that never loosens a hard block). A rejected or expired request does not run.

Deciding does not leave the thread silent: approving or rejecting — in the chat or from the inbox — appends one follow-up message to that conversation with the outcome ("Done: …", "OK — I didn't run it. Nothing was sent.", or the failure reason). The open thread reloads itself; clients without a live socket catch up on the next refresh.

Approvals inbox#

Manage → Automations → Approvals (/channels/approvals) lists Waiting and Decided; the menu entry carries a badge with the number of pending requests. Open a row to jump back to the chat or the Saved Task that asked. The page is absent while TOOLS.APPROVALS_ENABLED is off.

You choose Email me as soon as something waits or Send me a daily summary. Pending requests expire after the operator's window (default 72 hours).

Saved Tasks#

An unattended run that hits a write-class tool pauses. The task card shows that it is waiting. Approve it in the inbox (or from a link on the task) and the run continues; let it expire and that step is skipped. Three consecutive failures still auto-pause the task, as before. Plan steps that would write (send, create, upload) require approval even when the planner generated them on the fly.

Each saved task also has a Steps editor (WORKFLOWS.BUILDER_ENABLED, on by default): a tool step that calls a connected custom or MCP tool, a condition on a previous result, an outbound webhook (with a write-only secret and an HMAC signature revealed once), and Ask me before on any tool step — the same approval card as above. A task can additionally be started by an incoming webhook (per-task URL and token, rate-limited, queued and answered with 202). Save as template / Use template produce a paused copy that stays off and names the connections and assistants the copy still needs.

Custom HTTP tools#

When TOOLS.CUSTOM_HTTP_ENABLED is on (the default), Manage → Connections → Connected apps (/channels/connections) grows a Custom tools section under your mailboxes and folders. Connected apps itself is visible to every signed-in user; only the custom-tools section follows the flag. Saved custom tools are offered to the assistant in chat like any built-in tool.

  • Add a custom tool — name, title, what it does, HTTP method and URL, an optional JSON body template, and a class: Reads data, Changes something, or Deletes something. That class uses the same policy as built-in tools.
  • Import from OpenAPI — paste a document or a URL, pick operations, set a base URL, import the selected ones.
  • Try it — a test call that never saves the response. Secrets show as ***.

Credentials stay on this server. The backend pins DNS, rejects a templated origin, caps streamed bodies (default 1 MB), and refuses plain HTTP unless an operator allows it. Tokens are never written into an export file.

The flags (operators)#

The three switches sit under Operate → System configuration → Features → Tools & approvals; the policies and the expiry window under Operate → System configuration → Routing → Tool policies. Changes apply without a restart.

Setting Environment pin Default What it does
TOOLS.REGISTRY_ENABLED FEATURE_TOOLS_REGISTRY_ENABLED on One tool registry. Off restores the previous per-loop catalogues (kill-switch).
TOOLS.APPROVALS_ENABLED FEATURE_TOOLS_APPROVALS_ENABLED on Approval cards, the Approvals inbox, and pause / resume on Saved Tasks.
TOOLS.CUSTOM_HTTP_ENABLED FEATURE_TOOLS_CUSTOM_HTTP_ENABLED on Custom HTTP / OpenAPI tools on Connected apps.
WORKFLOWS.BUILDER_ENABLED FEATURE_WORKFLOWS_BUILDER_ENABLED on The Steps editor and the webhook trigger on saved tasks.
TOOLS.POLICY.read – auto Default for tools that only read.
TOOLS.POLICY.write – approve Default for tools that change something.
TOOLS.POLICY.destructive – block Default for tools that delete something.
TOOLS.APPROVAL_EXPIRY_HOURS – 72 Hours a pending request waits (1–720).
TOOLS.CUSTOM_HTTP_ALLOW_PLAIN_HTTP – 0 Allow http:// targets for custom tools.
TOOLS.CUSTOM_HTTP_MAX_RESPONSE_BYTES – 1048576 Cap on a custom tool's response body.

auto / approve / block are the only policy values. Always allow is a per-user, per-assistant override and cannot turn a block into a run.

Setting a FEATURE_* variable to false pins the feature off for the whole deployment and locks the admin toggle (it names the variable). SQL still works for automation that talks to the database (group TOOLS, owner 0, value '1' / '0'); the app picks the change up on the next runtime-config fetch. The full list of flags: Administration → Feature flags.

What is not here#

Running code is not a general tool: the Secure compute module offers one narrow capability — short Python or Node file work on copies of the files a user chose — behind COMPUTE.ENABLED with the sidecar up (Run the compute sidecar), and its unattended runs pause in this same approvals inbox. Interactive chat approvals run the tool when you approve and continue the turn with a follow-up message carrying the outcome.

↑↓ navigate↵ openEsc close