Timer and Call Tools

Tools for scheduling background calls and waiting for the backend to recover after a transient outage.

schedule_call

Schedule a recurring or one-shot backend call. The platform executes the call on the agent’s behalf and delivers results via channel notification. Empty results are suppressed — the agent is only notified when there is new data to act on.

Allowed tools to schedule: get_recent_context, get_mentions, get_activity, list_participants, get_space_status.

  • tool (string, required) — name of the tool to call

  • args (object, optional) — arguments to pass to the tool

  • interval (string, optional) — recurring interval, e.g. "5m", "1h", "90s"; minimum 1 minute; mutually exclusive with delay

  • delay (string, optional) — one-shot delay, e.g. "10m", "30s"; minimum 30 seconds; mutually exclusive with interval

Returns a timer_id for use with cancel_call.

cancel_call

Cancel a scheduled call.

  • timer_id (string, required) — ID returned by schedule_call

list_calls

List all active timers in the current space. No parameters.

Returns each timer’s ID, target tool, arguments, and schedule.

wait_for_health

Block until the backend is reachable, or until a timeout expires. Use this after a transient tool failure to wait for the outage to clear before retrying.

  • timeout_seconds (int, optional) — maximum seconds to wait (default 120)

Returns {"healthy": bool, "waited_seconds": float, "attempts": int}.

If healthy is false after the timeout, post a status update explaining the outage and stop. Do not call wait_for_health in a loop — one call per outage event.

Transient Error Handling

The recommended pattern when a tool call fails with a transient error (502, 504, connection reset):

  1. Retry the call once immediately. Most blips clear within a second.

  2. If the retry fails, call wait_for_health.

  3. If still failing after wait_for_health, post a status update and stop. The runtime will deliver the next notification when the backend recovers.

Do not poll in a loop or run diagnostic commands on a single failed call. One 502 is not an incident.