Workflows tools

Author, validate, run, and debug automation workflows from an agent.

19 tools. Each is callable over MCP with a Bearer agx_ key that holds the required scope. The catalog is public (tools/list isn't scope-filtered); the scope below is enforced when the tool is called (tools/call) — a key without it is refused (default-deny).

`search_workflow_templates`

Search the marketplace for workflow templates to start from. Optional category, search, limit, offset. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Description
`search`	string	Free-text search over template name/description.
`category`	string
`limit`	integer
`offset`	integer

Example

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

`get_workflow`

Read a workflow back as the editable YAML authoring spec plus metadata (status, node_count). Use before editing. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓	The workflow id.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_workflow",
    "arguments": {
      "workflow_id": "\u2026"
    }
  }
}

`get_workflow_authoring_guide`

Get the YAML authoring-spec reference (how to write a workflow: trigger, steps, config, branches, wiring rules). Read this before authoring. Requires workflows:read.

Required scope: workflows:read

Input

No input parameters.

Example

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

`get_workflow_execution`

Debug one execution: per-node status, which node failed, the error, and a trimmed output per node (large values previewed). Compact by default so it's readable; pass full=true for the complete raw record. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`execution_id`	string	✓
`full`	boolean		Return the complete raw record instead of the compact debug view.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_workflow_execution",
    "arguments": {
      "execution_id": "\u2026"
    }
  }
}

`get_workflow_node_schema`

Get one node type's full schema: config fields, required fields, and output handles (for branches). Pass an optional config (e.g. {target_table: deals}) to also get resolved_output_fields — the REAL {{alias.field}} columns for that instance, introspected live (so a DB trigger on deals returns deal columns). Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`node_type`	string	✓	The node type, e.g. 'condition'.
`config`	object		Optional intended config (e.g. {target_table: deals}, {entity_type: company}) to resolve instance-specific output fields.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_workflow_node_schema",
    "arguments": {
      "node_type": "\u2026"
    }
  }
}

`get_workflow_variables`

List the REAL {{alias.field}} output variables every node in a workflow exposes, with live config-driven introspection — a DB trigger on deals yields deal columns, crm_manager yields its entity's columns. Opaque nodes (api_request, kb_search, custom_function) are flagged source=runtime (fields only known after a test run). Call this BEFORE wiring {{...}} references so you use real fields, not guesses. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓	The workflow id.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_workflow_variables",
    "arguments": {
      "workflow_id": "\u2026"
    }
  }
}

`create_workflow`

Create a workflow from a YAML spec. Validates first and refuses to save if there are blocking errors. Saved as a DRAFT (won't run automatically until activated; you can test it immediately). Returns {workflow_id, status, warnings}. Requires workflows:author.

Required scope: workflows:author

Input

Parameter	Type	Required	Description
`spec`	string	✓	The YAML authoring spec (see get_workflow_authoring_guide).
`name`	string		Optional name override (else taken from the spec).
`description`	string		Optional description override.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_workflow",
    "arguments": {
      "spec": "\u2026"
    }
  }
}

`delete_workflow`

Delete a workflow permanently. Requires workflows:author.

Required scope: workflows:author

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_workflow",
    "arguments": {
      "workflow_id": "\u2026"
    }
  }
}

`list_workflow_executions`

List recent workflow executions (status, timing) for debugging. Optional workflow_id filter. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`workflow_id`	string
`limit`	integer

Example

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

`list_workflow_nodes`

List the workflow node types you can use, grouped by category (triggers, actions, logic, etc.). Optional category narrows it. Start here when building a workflow. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`category`	string		Optional category to filter by.

Example

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

`list_workflows`

List the org's workflows (id, name, status, trigger, node_count). Optional active filter. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`active`	boolean		Only active (true) or only inactive (false).

Example

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

`activate_workflow`

Activate a workflow so it fires on its triggers. Requires workflows:author.

Required scope: workflows:author

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "activate_workflow",
    "arguments": {
      "workflow_id": "\u2026"
    }
  }
}

`deactivate_workflow`

Deactivate a workflow so it stops firing on its triggers. Requires workflows:author.

Required scope: workflows:author

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "deactivate_workflow",
    "arguments": {
      "workflow_id": "\u2026"
    }
  }
}

`edit_workflow`

Edit an existing workflow with a list of granular operations. Node references accept a step alias OR a node id. Ops: add_node{node_type,config?,alias?,description?}; set_config{node_id,config}; rename_node{node_id,alias}; set_description{node_id,description}; connect{source,target,source_handle?}; disconnect{source,target,source_handle?}; remove_node{node_id}; set_variable{name,value}. Validates and refuses to save blocking errors; active state is preserved. Requires workflows:author.

Required scope: workflows:author

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓	The workflow id to edit.
`operations`	array<object>	✓	Ordered edit operations; each is an object with an `op` field plus its args.
`name`	string		Optional new name.
`description`	string		Optional new description.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "edit_workflow",
    "arguments": {
      "workflow_id": "\u2026",
      "operations": []
    }
  }
}

`import_workflow_template`

Instantiate a marketplace template into this org as a new workflow (by template_id from search_workflow_templates). Returns the new workflow_id. Requires workflows:author.

Required scope: workflows:author

Input

Parameter	Type	Required	Description
`template_id`	string	✓	The marketplace template id.
`name`	string		Optional name for the imported workflow.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "import_workflow_template",
    "arguments": {
      "template_id": "\u2026"
    }
  }
}

`run_workflow`

Run (test) a workflow by id, now, with optional inputs. REAL execution against live data/integrations — no sandbox. Confirm-gated: call without confirm to get a confirmation summary, then re-call with confirm=true once the human approves. Works on drafts too. Requires workflows:run.

Required scope: workflows:run

Input

Parameter	Type	Required	Description
`workflow_id`	string	✓
`inputs`	object		Trigger inputs for the run.
`confirm`	boolean		Must be true to actually execute.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run_workflow",
    "arguments": {
      "workflow_id": "\u2026"
    }
  }
}

`run_workflow_by_name`

Run (test) a workflow by name (must be unique). Same confirm gate and real-execution semantics as run_workflow. Requires workflows:run.

Required scope: workflows:run

Input

Parameter	Type	Required
`name`	string	✓
`inputs`	object
`confirm`	boolean

Example

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

`test_workflow_node`

Execute ONE node in isolation with sample inputs — no saved workflow needed. Give node_type (from list_workflow_nodes), an optional config (the node's data dict; {{templates}} allowed) and optional inputs (sample upstream data). REAL execution — no sandbox. Gated by the node's side_effect_tier: read nodes AUTO-RUN (no confirm); write_internal and external_irreversible nodes are confirm-gated (call without confirm to get config_schema + resolved-config preview, then re-call with confirm=true). dry_run: true resolves + previews what WOULD run WITHOUT executing (any tier) — the safe way to exercise a WALL node (external_irreversible) while building. Every response echoes side_effect_tier. Requires workflows:run.

Required scope: workflows:run

Input

Parameter	Type	Required	Description
`node_type`	string	✓	Node type id (e.g. crm_manager, api_request).
`config`	object		The node's config/data dict ({{templates}} allowed).
`inputs`	object		Sample upstream inputs the node reads / templates resolve against.
`dry_run`	boolean		Resolve config + preview only; never executes (any tier). Use to safely exercise external_irreversible nodes.
`confirm`	boolean		Required to execute write_internal / external_irreversible nodes. Ignored for read nodes (they auto-run).

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "test_workflow_node",
    "arguments": {
      "node_type": "\u2026"
    }
  }
}

`validate_workflow`

Compile and validate a workflow before saving it. Pass spec (YAML authoring spec) or a raw definition. Returns {valid, errors, warnings}; never saves. Requires workflows:read.

Required scope: workflows:read

Input

Parameter	Type	Required	Description
`spec`	string		YAML authoring spec to validate.
`definition`	object		A raw workflow definition (nodes/edges) to validate.

Example

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

search_workflow_templates​

get_workflow​

get_workflow_authoring_guide​

get_workflow_execution​

get_workflow_node_schema​

get_workflow_variables​

create_workflow​

delete_workflow​

list_workflow_executions​

list_workflow_nodes​

list_workflows​

activate_workflow​

deactivate_workflow​

edit_workflow​

import_workflow_template​

run_workflow​

run_workflow_by_name​

test_workflow_node​

validate_workflow​

`search_workflow_templates`

`get_workflow`

`get_workflow_authoring_guide`

`get_workflow_execution`

`get_workflow_node_schema`

`get_workflow_variables`

`create_workflow`

`delete_workflow`

`list_workflow_executions`

`list_workflow_nodes`

`list_workflows`

`activate_workflow`

`deactivate_workflow`

`edit_workflow`

`import_workflow_template`

`run_workflow`

`run_workflow_by_name`

`test_workflow_node`

`validate_workflow`