Skip to main content
Glama
usewrit

writ-mcp

Official
by usewrit
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Run a saved workflow

writ_run_workflow
Destructive

Run a saved workflow by ID or name and wait for completion to return extracted data. Pass inputs and files as needed for automated browser tasks.

Instructions

Run a saved workflow by id or name and (by default) wait for it to finish, returning the extracted data. Pass workflow inputs as top-level fields or under inputs, and any file inputs under files.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
waitNoWait for completion and return the data (default true).
filesNoOptional 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. A workflow whose upload step already has a file pinned runs fine with no `files` at all — pass it only to swap the file for THIS run.
deviceNoRun on this linked Writ desktop (an agent_id from writ_devices) — overrides the desktop this connection chose with writ_devices action='use'.
inputsNoRun inputs (or pass them as top-level fields).
outputNoRESPONSE SHAPE — set this whenever the answer is for a program or an API you are building, not for you to read. {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; missing → null so keys are stable), exclude: ['depth'], include_meta: false (page metadata content_kind/depth/thumbnails are STRIPPED unless true), key: 'usage' (wrap)}. On writ_crawl_site with save_as it is SAVED as the API's default shape.
max_ageNoOptional. Reuse a previous result if it is younger than this many seconds, instead of running the workflow again. 0 (the default) always runs fresh. Use it when a recent answer is good enough — much faster and cheaper.
workflowNoWorkflow name (or use workflow_id).
persona_idNoRun 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.
workflow_idNoA 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:...`.
function_nameNoCall 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. Omit to run the whole workflow. It is a control, never a workflow input.
mutation_modeNoHow a WRITE function (one that creates/posts/sends/deletes) runs on THIS run. Default 'live': you invoked the workflow, so its writes ARE sent. Pass 'dry_run' to preview the request without sending, or 'private_test' to send it with the function's safe overrides. (Separately, BUILDING a function — define/compile/test — never sends a write, whatever this is.) Reads ignore this.
function_namesNoCall SEVERAL functions in ONE run instead 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.
timeout_secondsNoMax seconds to wait for completion (default 120).
use_residentialNoPer-call network override for an owned workflow: true uses the platform residential network, false disables the workflow's residential default. Use it for geo-sensitive or datacenter-blocking sites.
execution_targetNoWhere 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. If a 'local' run fails because the app is offline, tell the user and only fall back to 'cloud' with their agreement.
residential_countryNoTwo-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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation profile is partly covered. The description adds the default synchronous wait-and-return-extracted-data behavior, but never mentions the live-write default or the dry_run/private_test escape hatch (that lives only in the schema), leaving key behavioral context on the param descriptions.

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 tight sentences, front-loaded with the core action and the default behavior; no filler or repetition.

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

Completeness3/5

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

For a 16-parameter, nested, open-world execution tool with no output schema, the description is thin: it omits mention of function_name/function_names selection, mutation_mode, execution_target, persona/device routing, and max_age caching. The schema covers these well, but the description does little to orient an agent on this complexity.

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 description coverage is 100%, so the baseline is 3. The description does add the convention that inputs may be passed as top-level fields or under `inputs` and file inputs under `files`, but much of this is also restated in the schema, so marginal added value.

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 specific verb+resource ('Run a saved workflow') and adds useful scope: identified by id or name, defaults to waiting for completion and returning extracted data. It does not name or distinguish itself from siblings like writ_workflow_runs or writ_website_to_api, so it stops short of a 5.

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?

The description implies usage through the default-wait behavior and input-passing conventions, but gives no explicit when-to-use/when-not guidance versus the many sibling run/inspect tools (writ_workflow_runs, writ_replay, etc.).

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

Deploy Server

Other Tools