Marcora

run_workflow

Destructive

Manually run a workflow. Creates a run record and starts an automated agent session that carries out the workflow's steps, using Marcora tools and the user's connected apps; the session is told to use only the tools in the workflow's allowed_tools. Returns the run row — check .status to know what happened.

Input roles:
- workflow_id: UUID string of the workflow to run.
- input_values: object matching the workflow's declared inputs schema. Call get_workflow first if unsure.

Only an **Active** workflow can run. An Inactive (or archived) one is refused, and the refusal can reach you as an unreadable protocol error rather than a clear message — so if you are not sure of the status, check it with get_workflow first. If it is Inactive, tell the user so, and set it Active with update_workflow if they want it to run. The schedule has nothing to do with manual runs: a Paused schedule does not stop run_workflow, and an On schedule does not let an Inactive workflow run.

Usage patterns:
- Always inspect the returned .status:
  - "running" → dispatch succeeded; the agent session is live.
  - "failed" → dispatch failed; .error_reason has the cause. Tell the user specifically what went wrong.
  - "skipped" → the runner decided no work was needed (rare for manual runs, common for scheduled).
- For scheduled runs, prefer creating a trigger via create_workflow's schedule_config — don't loop run_workflow calls.
- input_values must match workflow.inputs schema. For workflows with no declared inputs, pass {} or omit.
- The returned `id` is a UUID string for the workflow_run. Use it as `run_id` in get_workflow_runs (single-mode) to inspect the run.

**Links:** present `link_url` to the user exactly as returned — copy it character 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": {
      "workflow_id": "<workflow_id>"
    },
    "name": "run_workflow"
  }
}

Input Schema

Name	Required	Description	Default
`workflow_id`	Yes	UUID of the workflow to run immediately. The workflow must be "active" — running an inactive or archived one is rejected, so set the status with `update_workflow` first. Its schedule's state (On or Paused) does not matter for a manual run. The call starts the run and returns straight away; it does not wait for the work to finish.
`input_values`	No	Object holding the actual values for this run, matching the fields the workflow declares in its `inputs`. They are handed to the agent as the run's inputs and it is instructed to use only what you provide, so include every id or value the steps depend on. Defaults to an empty object when omitted, which is correct for workflows that take no inputs.

Output Schema

Name	Required	Description
`id`	No	Workflow run UUID.
`status`	No
`link_url`	No	Direct URL to view this run in Marcora.
`error_reason`	No
`trigger_type`	No
`error_summary`	No
`runner_session_id`	No
`workflow_template_id`	No	Parent workflow UUID.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 4, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (destructive, non-idempotent, open-world), the description discloses that dispatch is asynchronous, that the agent session is constrained to the workflow's allowed_tools, and that an Inactive workflow may surface as an unreadable protocol error rather than a clear message — a genuinely non-obvious failure mode. It also enumerates the returned .status values and their meanings, so the agent knows how to interpret success versus failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well structured with a front-loaded summary followed by status semantics and link handling, so the agent can skim. The 'Input roles' block duplicates material already present in the schema, which is the main excess; the rest of the length is earned by non-obvious operational detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, asynchronous dispatch tool with an output schema, the description covers the execution model, status interpretation, error handling, and follow-up navigation (run_id into get_workflow_runs). Nothing an agent needs to invoke it correctly or explain the outcome to a user appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema descriptions already cover the Active requirement, schedule irrelevance, non-blocking behavior, and the empty-object default for input_values. The description's 'Input roles' section largely restates this, adding only the practical nudge to call get_workflow first and to include every id the steps depend on.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Manually run a workflow') and immediately explains the mechanism: creates a run record and starts an agent session that executes the workflow's steps. It is clearly distinguishable from create_workflow, get_workflow_runs, and scheduled triggers, which are named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit preconditions (workflow must be Active), names the sibling to check first (get_workflow), names the sibling to fix status (update_workflow), and rules out a misleading alternative signal ('a Paused schedule does not stop run_workflow'). It also steers scheduled use away from looping this tool toward create_workflow's schedule_config.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Marcora tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?