create_workflow
Creates a new workflow template (a saved, repeatable multi-step agent task) for the user's current team. New workflows are saved Inactive; set one Active with update_workflow only once the user confirms. Before creating, check list_workflows with a search filter for a duplicate name, and confirm the name with the user.
Required: name, steps (ordered; each specific enough for a fresh agent to do without follow-up questions) and allowed_tools (non-empty: the tools the runner agent is told it may use; prefer tight allowlists). Include schedule_config ONLY if the user explicitly wants it to run on a schedule.
Two switches, two vocabularies, never mixed. The workflow's status is Active or Inactive. Its schedule, if any, is On or Paused. Never call a schedule "active"/"inactive" or a workflow "paused"/"on". Active does not mean running; it means the workflow is allowed to run. It runs on its own only when it is Active AND its schedule is On.
Schedules are always saved Paused. No MCP tool can turn a schedule On: the user does it in the Marcora app with Resume schedule. update_workflow silently ignores schedule changes and still returns success.
What to tell the user: the response carries a next_step stating what will and won't run, computed from what was saved. Lead your reply with it. When a schedule was saved it also carries schedule (is_enabled: false = Paused, plus a plain-language summary) and link_url for the user to review it and click Resume schedule. Never say or imply the workflow will run on its own unless it is Active and its schedule is On.
Schedule shapes: daily at a set time, or weekly on one or more days at a set time (days_of_week, e.g. [1,3,5], with one hour). There is no second time of day and no every-N-hours interval.
Present link_url exactly as returned.
Input roles:
name: human-readable name. Confirm with the user before creating.
description: one or two sentences. Becomes part of the runner's system prompt.
steps: ordered list. Each step should be specific enough that a fresh agent can do it without follow-up questions.
inputs: declare what the workflow needs (e.g. topic, date_range).
allowed_tools: REQUIRED, non-empty. The tools the runner agent is told it may use when the workflow runs (an instruction in the runner's prompt, not a separate permission check). A workflow cannot be created without an explicit allowlist. Prefer tight allowlists, especially for scheduled runs.
tags: optional.
schedule_config: include ONLY if the user explicitly wants a schedule. See the
schedule_configinput for its two modes; prefer the calendar mode (hour, plusdays_of_weekfor weekly).
What actually runs needs BOTH switches; describe the pair that exists when you finish:
Inactive → nothing runs, by any route (manual runs are refused too).
Active, no schedule → runs only when started manually; never starts by itself.
Active, schedule Paused → manual runs work; it won't run on its schedule until the user turns the schedule on with Resume schedule in the app.
Active, schedule On → runs on its schedule.
Inactive, schedule On → nothing runs until the workflow is set Active.
After a follow-up call: if you then call update_workflow (for example to set the workflow Active), describe the state after THAT call (its next_step), not this one. Activating a workflow whose schedule is Paused still leaves it not running on its schedule; saying "it's inactive, go activate it" after you activated it is just as false. "Created and active" misled a real customer into thinking their workflow was running.
Cadences: "3 times a week", "every weekday" and "Mondays and Thursdays" are expressible exactly: use weekly with days_of_week and one hour, pick the days with the user's intent in mind and say which you chose; do not fall back to an interval. If the user asks for something the two shapes can't express (e.g. "twice a day", "every 36 hours"), save the closest schedule you can, tell the user exactly what you saved (quote schedule.summary) and that it approximates what they asked for. Never present an approximation as the schedule they requested.
Usage patterns:
The returned
idis a UUID string. Use it asworkflow_idin get_workflow / update_workflow / run_workflow / get_workflow_runs.Links: copy
link_urlcharacter for character. Never retype, shorten, or rebuild a link or the IDs inside it.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>",
"steps": "<steps>",
"allowed_tools": "<allowed_tools>"
},
"name": "create_workflow"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name for the workflow, shown in the workflow list and passed to the agent that runs it. Required and must be non-empty — a missing or blank value is rejected. `list_workflows` searches on this name, so make it distinctive and confirm the wording with the user first. | |
| tags | No | Free-form labels for organizing workflows. Must be an array of strings; any other value is ignored and a single blank tag is stored instead. Purely descriptive — listing and search do not filter on tags. | |
| steps | Yes | Ordered list of the actions the workflow should perform, handed to the agent as JSON at run time. Required. Write each step so a fresh agent with no conversation history can carry it out without asking follow-up questions. | |
| inputs | No | Object declaring the values this workflow expects at run time (for example a topic or a date range). It is stored and returned as documentation for callers and for the app UI; the agent itself receives the actual per-run values via `input_values`, not this declaration. Optional — defaults to an empty object. | |
| description | No | One or two sentences on what the workflow accomplishes. It is inserted verbatim into the prompt given to the agent that runs the workflow, so write it as orienting context, not marketing copy. Optional — stored as an empty string when omitted. | |
| allowed_tools | Yes | REQUIRED, non-empty. Tools the workflow runner may use; an empty list is rejected. | |
| schedule_config | No | Include only when the user explicitly asks for the workflow to run on a schedule. A non-empty object creates the schedule, which is always saved Paused — the user turns it on in the app with "Resume schedule", and it fires only while the workflow is Active. Two modes: - **Calendar mode (preferred — it is what the app's editor shows and edits):** set `hour` (integer 0–23, in **UTC**). With `frequency: "weekly"`, set `days_of_week` — an array of 1–7 distinct integers, 0=Sunday … 6=Saturday, in **UTC** — so "3 times a week" is one schedule, e.g. `[1,3,5]`. (The older single `day_of_week` is still read when `days_of_week` is absent; prefer the array.) Any frequency other than weekly runs daily at `hour`. Convert the user's local time (and weekday) to UTC yourself, and set `timezone` to the user's IANA timezone (e.g. "America/Sao_Paulo") for display. - **Interval mode (when `hour` is absent):** runs every `interval_hours` hours, or every 1 / 24 / 168 hours for hourly / daily / weekly if `interval_hours` is omitted. There is no fixed time of day, and the first run is one full interval after the user switches the schedule on. The app's editor cannot show or edit an interval schedule, so use it only when calendar mode can't express what the user needs, and say what you saved. `timezone` is display-only; the scheduler always uses UTC. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Workflow UUID. Use as workflow_id in other workflow tools. | |
| name | Yes | ||
| tags | No | ||
| steps | No | ||
| inputs | No | ||
| status | Yes | ||
| team_id | Yes | ||
| link_url | Yes | Direct URL to view this workflow in Marcora. | |
| schedule | No | Present only when schedule_config created a schedule. Read back from the saved schedule. | |
| next_step | No | Always present. What will and won't run, across both switches — the workflow's status (Active / Inactive) and its schedule (On / Paused / none) — computed from what was saved, with the words to use. Follow it and lead your reply with it. | |
| created_at | Yes | ||
| updated_at | No | ||
| description | No | ||
| allowed_tools | No | ||
| created_by_user_id | No |