Writing Workflow Descriptions

Create structured descriptions that enable AI to intelligently select and execute your automation workflows

Overview

When AI assistants like Claude control Qontinui Runner through the MCP (Model Context Protocol) server, they need to understand:

•What each workflow does
•When to use it
•What order to run multiple workflows
•How to verify success or diagnose failures

Structured workflow descriptions provide this context in a format that both humans and AI can easily understand and parse.

Why This Matters

Example: AI-Driven Verification

You make code changes to the web extraction feature and ask Claude:“Verify the extraction feature works end-to-end”

With good workflow descriptions, Claude will:

1.Load your workflow config and read all descriptions
2.Identify workflows related to extraction based on “Use when” and “Verifies” fields
3.Check “Depends on” to determine execution order
4.Run workflows in sequence (e.g., create extraction data first, then verify it displays)
5.Analyze results using success/failure indicators
6.Report findings or autonomously fix issues

Structured Description Format

Use the existing description field in your workflow JSON. No schema changes or additional fields are required. Structure your description using this natural language format:

[One-line summary of what this workflow does]

Use when: [Conditions that indicate this workflow should be run]
Verifies: [What features/functionality this workflow tests]
Prerequisites: [What must be true before running]
Produces: [What state changes or outputs result from running]
Depends on: [Other workflows that must run first, if any]
Success indicators: [How to know the workflow succeeded]
Failure indicators: [Signs that something went wrong]

Field Reference

Field	Required	Purpose
Summary	Yes	First line, clear action-oriented description of what the workflow does
Use when	Yes	Conditions or situations when AI should choose this workflow
Verifies	Recommended	What features or functionality this workflow tests or validates
Prerequisites	Recommended	Required state before running (services running, apps open, login state, etc.)
Produces	Optional	Side effects or outputs (new data created, state changes, files written)
Depends on	Optional	Other workflow names that must run first (use exact names, case-sensitive)
Success indicators	Optional	Observable indicators that the workflow succeeded (visible UI elements, log messages, data created)
Failure indicators	Optional	Signs that something went wrong (error messages, missing elements, API failures)

Examples

Example 1: Navigation Workflow

A simple workflow that navigates to a page and verifies it loads correctly.

Clicks Build > State Machine in the website navigation menu to open the State Machine Builder page.

Use when: Need to test or verify the State Machine Builder feature, or after making changes to state machine related code (state-machine-canvas, state nodes, transitions).
Verifies: Navigation menu works, Build dropdown opens, State Machine Builder page loads, canvas renders correctly, no console errors.
Prerequisites: qontinui-web frontend running on localhost:3001, user logged in to the application, a project is selected.
Success indicators: State Machine canvas is visible, toolbar appears, no errors in browser console, URL shows /build/state-machine, page title shows "State Machine".
Failure indicators: 404 error, blank page, canvas doesn&apos;t render, console errors about missing components, navigation menu doesn&apos;t respond to clicks.

Example 2: Data-Producing Workflow

A workflow that creates new data which other workflows may depend on.

Opens the runner's extraction panel and performs a new web extraction on the currently visible application.

Use when: Need to create new extraction data for testing, or to verify the extraction feature works after code changes to extraction, element detection, or screenshot capture.
Verifies: Runner extraction panel opens, screenshot capture works, element detection runs, accessibility tree is parsed, states are identified and classified.
Prerequisites: qontinui-runner is running, target application is visible on screen and fully loaded, a project is loaded in the runner with valid configuration.
Produces: New extraction data (states, screenshots, element annotations, state metadata) in the current project configuration. Data is immediately available for web display.
Success indicators: Extraction completes without errors, at least one state is detected, screenshots are captured successfully, elements are annotated with bounding boxes, state names are generated.
Failure indicators: Extraction hangs or times out, no states detected ("0 items found" in logs), screenshot capture fails with permission errors, accessibility tree parse errors, Python subprocess crashes.

Example 3: Verification Workflow with Dependencies

A workflow that depends on data from another workflow.

Navigates to the Web Extraction page in the website and verifies that extraction data is displayed correctly in the UI.

Use when: After creating new extraction data, need to verify it appears correctly in the web interface. Use when testing web display logic, image rendering, or state list components.
Verifies: Web Extraction page loads, extraction data is fetched from API, images render correctly without broken image icons, state list is populated with correct count, element annotations are visible on hover.
Prerequisites: qontinui-web frontend running on localhost:3001, user logged in to the application, extraction data exists in the current project (must have run extraction first).
Depends on: "Start New Web Extraction" (if no extraction data exists yet for this project)
Success indicators: Extraction data visible in the UI, images load successfully, state count matches expected (e.g., 3 states detected), element bounding boxes render on hover, state metadata (timestamps, confidence scores) displays correctly, no API errors in network tab.
Failure indicators: Empty state list, broken image icons, "No extractions found" message appears, API returns 404 or 500 errors, network tab shows failed /api/extractions requests, images fail to load with CORS errors, state count is 0 when data should exist.

Multi-Workflow Sequences

For complex verification tasks that require multiple workflows, the Depends on field enables AI to understand ordering requirements and execute workflows in the correct sequence.

How AI Chains Workflows

When you ask: “Verify web extraction works end-to-end”

Load and analyze: AI loads the workflow config and reads all descriptions

Identify relevant workflows: Finds “Start New Web Extraction” and “Navigate to Web Extraction Page” based on “Use when” and “Verifies” fields

Determine order: Sees that page verification “Depends on” extraction workflow (which “Produces” data)

Execute in sequence: Runs extraction first (produces data), then page verification (consumes data)

Verify results: Checks success/failure indicators in logs, screenshots, and API responses

Report or fix: Reports findings and can autonomously fix issues discovered during verification

Best Practices

Do

✓Write the summary as a clear, action-oriented first line (e.g., “Clicks the login button...”)
✓Be specific about prerequisites: which services must be running, ports, login state
✓List concrete, observable success/failure indicators AI can verify in logs or screenshots
✓Use consistent terminology across all workflows in your configuration
✓Reference specific UI elements, page names, routes, and features
✓Use exact workflow names in “Depends on” (case-sensitive)
✓Include specific error messages or log patterns in failure indicators

Don't

✗Leave descriptions empty or use vague text like “Tests stuff” or “Automation workflow”
✗Assume AI knows your application's structure, routes, or component names
✗Forget to mention required login state or authentication tokens
✗Use ambiguous terms like “the page” without specifying which page
✗Skip the “Use when” field - it's critical for AI workflow selection
✗Omit failure indicators - AI needs to diagnose what went wrong
✗Use generic indicators like “check if it works” without specifics

Writing Tips

1. Start with the Action

Begin your summary with an active verb that describes what the workflow does.

Good

“Clicks the Submit button and verifies the form submits”

Bad

“Form submission workflow”

2. Be Specific About State

Clearly describe what state the system should be in before and after the workflow.

Good

Prerequisites: User logged in with admin role, database contains test data
Produces: New project record in database with status “active”

Bad

Prerequisites: Logged in
Produces: New project

3. Make Indicators Observable

Success and failure indicators should be things AI can verify in logs, screenshots, or API responses.

Good

Success: “Success message appears”, API returns 200 status, log shows “Project created”
Failure: 404 error, blank screen, console error “Cannot read property”

Bad

Success: It works
Failure: Something broke

4. Link Related Workflows

Use “Depends on” to create workflow chains. Reference the exact workflow name as it appears in the config.

Good

Depends on: “Create Test User” (if no test user exists), “Start Backend Server”

Bad

Depends on: The user workflow

JSON Format Example

The description is stored as a single string field in the workflow JSON. Use \n for newlines:

{
  "id": "workflow-navigate-state-machine",
  "name": "Navigate to State Machine Builder",
  "description": "Clicks Build > State Machine in the website navigation menu to open the State Machine Builder page.\n\nUse when: Need to test or verify the State Machine Builder feature, or after making changes to state machine related code.\nVerifies: Navigation menu works, State Machine Builder page loads, canvas renders correctly.\nPrerequisites: Website running on localhost:3001, user logged in.\nSuccess indicators: Canvas visible, no console errors, URL shows /build/state-machine.\nFailure indicators: 404 error, blank page, console errors.",
  "category": "Main",
  "format": "graph",
  "version": "1.0.0",
  "actions": [
    // ... workflow actions
  ],
  "connections": {
    // ... action connections
  }
}

Workflow Categories

Organize workflows into categories to help AI understand their purpose and whether they can be executed directly:

Category	Purpose	Executable
Main	Primary workflows for execution	Yes
Testing	Test verification workflows	Yes
UI Automation	UI interaction workflows	Yes
Utilities	Helper workflows	Yes
Transitions	State machine transitions	Via state machine only

Writing Workflow Descriptions

Overview

Why This Matters

Example: AI-Driven Verification

Structured Description Format

Field Reference

Examples

Example 1: Navigation Workflow

Example 2: Data-Producing Workflow

Example 3: Verification Workflow with Dependencies

Multi-Workflow Sequences

How AI Chains Workflows

Best Practices

Do

Don't

Writing Tips

1. Start with the Action

2. Be Specific About State

3. Make Indicators Observable

4. Link Related Workflows

JSON Format Example

Workflow Categories

Related Documentation

AI Integration Overview

Running Automations

Writing Workflow Descriptions

Overview

Why This Matters

Example: AI-Driven Verification

Structured Description Format

Field Reference

Examples

Example 1: Navigation Workflow

Example 2: Data-Producing Workflow

Example 3: Verification Workflow with Dependencies

Multi-Workflow Sequences

How AI Chains Workflows

Best Practices

Do

Don't

Writing Tips

1. Start with the Action

2. Be Specific About State

3. Make Indicators Observable

4. Link Related Workflows

JSON Format Example

Workflow Categories

Related Documentation

AI Integration Overview

Running Automations