Skip to main content
Glama

Run a saved workflow

writ_run_workflow
Destructive

Runs a saved workflow by workflow_id or name and returns its extracted data (it waits by default). The answer's data is what the run returned and records_path names its records; pass output with only the fields the question needs (fields: ['price', 'data.date as date']) for a far smaller answer. Inputs go as top-level fields or under inputs; function_name runs one function of a multi-function API (with the sign-in it needs). max_age reuses a recent result at no cost. A write function previews with mutation_mode='dry_run'. Runs sign in as the workflow's persona or persona_id; no password is ever passed. Venue, network, files and output shape: writ_help('writ_run_workflow').

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "writ_run_workflow"
  }
}

Input Schema

NameRequiredDescriptionDefault
waitNo
filesNo
deviceNo
inputsNoRun inputs (top-level fields work too).
outputNo
max_ageNoReuse a result younger than this many seconds (free). 0 = fresh.
workflowNoWorkflow name (or workflow_id).
persona_idNoRun as this saved identity.
workflow_idNoA number, or 'local:<id>' (a workflow on the user's desktop).
function_nameNoOne function of a multi-function workflow; writ_list_workflows names them (`functions`).
mutation_modeNolive (default) | dry_run (preview, nothing sent) | private_test.
function_namesNo
idempotency_keyNo
timeout_secondsNo
use_residentialNo
execution_targetNocloud | auto | local (the user's own desktop app).
residential_countryNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "type": "string"
      +}
  2. Changed9 schema fields changed
    • addedInput schema / properties / device
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / files
      Added value: +{
      +  "type": "object"
      +}
    • changedInput schema / properties / function_name / description
      Previous value: -"One function of a multi-function workflow."New value: +"One function of a multi-function workflow; writ_list_workflows names them (`functions`)."
    • addedInput schema / properties / function_names
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / output
      Added value: +{
      +  "type": "object"
      +}
    • addedInput schema / properties / residential_country
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / timeout_seconds
      Added value: +{
      +  "type": "integer"
      +}
    • addedInput schema / properties / use_residential
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / wait
      Added value: +{
      +  "type": "boolean"
      +}
  3. Changed14 schema fields changed
    • removedInput schema / properties / device
      Removed value: -{
      -  "description": "Run on this linked Writ desktop (an agent_id from writ_devices) — overrides the desktop this connection chose with writ_devices action='use'.",
      -  "type": "string"
      -}
    • changedInput schema / properties / execution_target / description
      Previous value: -"Where this run executes: 'cloud' (managed fleet), 'auto' (prefer the user's OWN linked Writ desktop app when online, else cloud), or 'local' (require their own desktop app — keeps the run on their machine + IP). Omit to keep the workflow's own configured target. A 'local' run fails while that desktop app is offline; 'cloud' runs the same workflow on Writ's fleet, off the user's machine and IP."New value: +"cloud | auto | local (the user's own desktop app)."
    • removedInput schema / properties / files
      Removed value: -{
      -  "additionalProperties": {
      -    "type": "string"
      -  },
      -  "description": "Optional file inputs for this run, as {slot: file_id}. Slot names come from the workflow's `file_slots` (writ_list_workflows); file_ids come from the account's file library. An upload step with a pinned file uses it when `files` is omitted; a value here swaps the file for this run only.",
      -  "type": "object"
      -}
    • changedInput schema / properties / function_name / description
      Previous value: -"One named function of a multi-function workflow (an API built with writ_website_to_api / writ_browser_compose define_function): only that function and the sign-in functions it depends on run. Omitted, the whole workflow runs. It is a control, never a workflow input."New value: +"One function of a multi-function workflow."
    • removedInput schema / properties / function_names
      Removed value: -{
      -  "description": "Several functions in one run, in place of `function_name`: the union of their steps runs once, in recorded order (a prerequisite they share runs once). Not for a desktop (`local:`) workflow. A control, never a workflow input.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": "array"
      -}
    • changedInput schema / properties / max_age / description
      Previous value: -"Optional. Reuse a previous result if it is younger than this many seconds, instead of running the workflow again. 0 (the default) always runs fresh. A reused result answers at once and costs nothing."New value: +"Reuse a result younger than this many seconds (free). 0 = fresh."
    • changedInput schema / properties / mutation_mode / description
      Previous value: -"How a write function (one that creates/posts/sends/deletes) runs on this run. Default 'live': a run is an explicit call, so its writes are sent. 'dry_run' previews the request without sending it; 'private_test' sends it with the function's safe overrides. (Separately, BUILDING a function — define/compile/test — never sends a write, whatever this is.) Reads ignore this."New value: +"live (default) | dry_run (preview, nothing sent) | private_test."
    • removedInput schema / properties / output
      Removed value: -{
      -  "description": "Response shape, for an answer a program or an API consumes rather than a reader. {shape: 'envelope' (default: Writ's full answer, projected) | 'table' ({columns, rows, total}) | 'records' (bare list of records) | 'record' (the newest record alone: one entity, a usage meter, a dashboard), fields: ['used', 'percent_used as pct', 'items.0.price as first_price'] (ordered pick, renames, dotted paths; a missing path is null, so keys are stable), exclude: ['depth'], include_meta: false (page metadata content_kind/depth/thumbnails is stripped unless true), key: 'usage' (wrap)}. On writ_crawl_site with save_as it is saved as the API's default shape.",
      -  "properties": {
      -    "exclude": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "fields": {
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "include_meta": {
      -      "type": "boolean"
      -    },
      -    "key": {
      -      "type": "string"
      -    },
      -    "shape": {
      -      "enum": [
      -        "envelope",
      -        "table",
      -        "records",
      -        "record"
      -      ],
      -      "type": "string"
      -    }
      -  },
      -  "type": "object"
      -}
    • changedInput schema / properties / persona_id / description
      Previous value: -"Run AS this saved identity (see writ_personas) — the run signs in with the persona's warm session. Omit to use the workflow's default persona, if it has one. A persona of the user's linked DESKTOP (`device:<agent>:<id>`, source='device' in writ_personas) sends the run to that desktop, which signs in from its own vault: the credentials never leave it."New value: +"Run as this saved identity."
    • removedInput schema / properties / residential_country
      Removed value: -{
      -  "description": "Two-letter ISO-3166 exit country for this call (for example ca, us, fr). Keep it aligned with the requested storefront, coordinates or delivery market. It is applied when the run uses residential egress.",
      -  "type": "string"
      -}
    • removedInput schema / properties / timeout_seconds
      Removed value: -{
      -  "description": "Max seconds to wait for completion (default 120).",
      -  "type": "integer"
      -}
    • removedInput schema / properties / use_residential
      Removed value: -{
      -  "description": "Per-call network override for an owned workflow: true uses the platform residential network, false disables the workflow's residential default. For geo-sensitive sites and sites that block datacenter addresses.",
      -  "type": "boolean"
      -}
    • removedInput schema / properties / wait
      Removed value: -{
      -  "description": "Wait for completion and return the data (default true).",
      -  "type": "boolean"
      -}
    • changedInput schema / properties / workflow_id / description
      Previous value: -"A number, or `local:<id>` for a workflow that lives on the user's linked Writ desktop (writ_list_workflows, runs_on='desktop') - it runs there, signed in as one of that desktop's personas when persona_id is `device:...`."New value: +"A number, or 'local:<id>' (a workflow on the user's desktop)."
  4. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false; the description adds genuinely new behavior: it blocks by default, results can be reused for free via max_age, write functions can be previewed, and runs authenticate as the workflow's persona with no password ever passed. It stops short of naming what the destructive action actually affects or how failures surface.

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

Conciseness5/5

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

Two dense sentences with the core behavior first, then a compact list of the levers an agent needs (output, inputs, function_name, max_age, mutation_mode, persona) and the escalation pointer. Nothing is padding; each clause maps to a parameter or a behavioral fact.

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

Completeness4/5

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

Given a destructive, open-world, 17-parameter tool with no output schema, the definition covers the high-consequence defaults (waiting, dry_run, auth) and explicitly delegates venue/network/files/output shape to writ_help. The remaining gaps are the operational parameters and error behavior, which the delegation only partly excuses.

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

Parameters4/5

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

With 17 parameters and only 47% schema coverage, the description carries real weight: it explains the output field-selection syntax, that inputs may be top-level or nested under `inputs`, what function_name does, max_age semantics, mutation_mode's dry_run, and persona-based auth. Several parameters (wait, files, timeout_seconds, execution_target, use_residential, idempotency_key) are left entirely to the schema or to writ_help.

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

Purpose4/5

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

States a concrete verb and resource: 'Runs a saved workflow by workflow_id or name and returns its extracted data', with the waiting default disclosed up front. It doesn't name a sibling (e.g., writ_workflow_data or writ_run_saved_crawl) to contrast against, so an agent must infer the boundary between running and retrieving.

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

Usage Guidelines3/5

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

Gives real decision cues: use max_age to reuse a recent result at no cost, use mutation_mode='dry_run' to preview a write function, use function_name to target one function of a multi-function API. However, it never states when to prefer this over the many sibling run/data tools, relying instead on a pointer to writ_help for the remaining shape questions.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.