tools

Create a scheduled task for one of the user's agents

Create a scheduled task for one of the user's agents. Supported schedule types: once (run_at ISO local time + timezone), interval (interval_minutes 5-1440), hourly, daily (time HH:MM + timezone), weekly (time + timezone + days_of_week 0=Sunday..6), cron (5-field expression + timezone), manual (only runs on demand). Returns the normalized schedule and the computed next_run_at so you can read the fire time back to the user in their timezone.

post/api/mcp/tools/schedule_agent_task

Request

  • Base URL: https://finestructure.ai
  • URL: https://finestructure.ai/api/mcp/tools/schedule_agent_task
  • Auth: HTTP bearer

Request body

agent_idstring required

The agent id (from create_agent or list_agents)

titlestring required

Short task title

instructionsstring required

What the agent should do on each run, written as instructions to the agent

scheduleobject required

Schedule object, e.g. {"type":"daily","time":"08:30","timezone":"Asia/Jerusalem"} or {"type":"weekly","time":"09:00","timezone":"Asia/Jerusalem","days_of_week":[0]} or {"type":"once","run_at":"2026-08-20T09:00","timezone":"Asia/Jerusalem"}

max_runsinteger

Optional cap on total runs (0 = unlimited)

activateboolean

Start the schedule immediately (true) or save as draft (false)

Response

Tool executed successfully

okboolean required
toolstring required
resultobject required

Changes

No recorded changes to this operation across all 2 revisions of this API.