> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.default.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build workflows with an AI agent

> Use the Default MCP server to have Claude, Codex, Cursor, or another AI agent build, check, and publish Default workflows: the build loop, prompts that work, common errors, and rules to give your agent.

With the [Default MCP server](https://docs.os.default.com/mcp-server.md) connected, an AI agent can build a workflow for you.
It can read a workflow, add and change steps, check the draft for problems, and publish it. Every
change is shown to you first and saved only after you approve it.

This page is for 2 readers: the person who asks for the workflow, and the agent that builds it.
The last section, [Rules for your agent](#rules-for-your-agent), is a block you can paste into
your agent's instructions.

> [!NOTE]
>
> **Admins and owners can build and publish workflows over MCP.** No extra setup is needed. Members,
> editors, and viewers do not see the workflow tools.

## How a build works

The agent uses 6 tools in a fixed order. Each one answers a question the next one needs.

| Tool | The question it answers |
| - | - |
| `workflow_describe` | Which steps and triggers exist, and what does each one need? |
| `workflow_find_values` | What can go in this field: which queues, channels, CRM fields, or values? |
| `workflow_read_graph` | What does the draft look like now? |
| `workflow_apply_changes` | What would this change do? Then, after you approve: save it. |
| `workflow_validate_graph` | Would this draft publish cleanly? |
| `workflow_publish` | What goes live? Then, after you approve: publish it. |

**1. The agent learns the building blocks**

It calls `workflow_describe` to see the step and trigger types, then once more for each type it
plans to use. This tells it which fields a step takes and which exits the step has.

**2. The agent finds real values**

It calls `workflow_find_values` for each field it fills. This returns the actual queues, Slack
channels, and CRM fields in your workspace, and the outputs of earlier steps it can use.

**3. The agent reads the current draft**

For an existing workflow, it calls `workflow_read_graph`. The answer includes a revision, a
fingerprint of the draft at that moment.

**4. You approve a preview**

The agent sends its change once as a preview. Nothing is saved. It shows you what would change
and any problems Default found. When you say yes, it sends the same change again to save it.

**5. The agent checks the draft**

It calls `workflow_validate_graph` and fixes what it reports. This check takes a few seconds.

**6. You approve the publish**

The agent previews the publish, then publishes after you approve. From then on, every new run
uses the new version.

## Ask for a workflow

A good request names the goal, the steps in order, and the rule for each branch. Ask the agent to
use real values from your workspace and to show you each change before it saves.

**Good requests**

* "Build a workflow for our Contact Sales form. Match the person to a Salesforce account. If there
  is a match, send the lead to the account owner. If not, route it through the 'Inbound AE' queue
  and post the result in #inbound-leads. Use the real queue and channel. Show me each change
  before you save it."
* "In the 'Inbound router' workflow, add a branch for companies with more than 1,000 employees
  that goes to the 'Enterprise AE' queue. Check the draft and fix what it reports, then ask me
  before you publish."
* "What does a Round-Robin step need, and what does it give the next step?"
* "Which Salesforce fields could the Update Record step in 'Inbound router' write to?"

**Requests that go wrong**

* Vague values, such as "set a sensible delay" or "notify the right channel". Name the value, or
  ask the agent to list the options first.
* "Publish anyway" when the check reports problems. Fix the problems first.
* "Delete the workflow" or "turn it off". The agent cannot do these. Use the app.

## Design rules

These rules apply to any workflow, but an agent misses them more often than a person in the builder
does.

* **Check a step's exits before you add after it.** **Match Record** has a fixed Match and No Match
  exit. **Display Scheduler** has a fixed Booked and Not booked exit. You cannot add a third exit to
  either. Most steps allow only 1 next step. Add the new step on a specific branch.
* **Give every Multi-Branch branch a condition.** A new **Multi-Branch** step starts with only the
  **Else** branch. When 2 branches can both match, set their order: the first match wins.
* **Give Run Experiment weights that add up to 100.** A new **Run Experiment** step starts with no
  branches. Add each branch and its weight.
* **Use outputs from earlier steps, not typed text.** Bind an email, a domain, or an owner to the
  step that produced it. After 2 paths join, a value is safe to use only if every path into that
  point produces it.
* **Compare values as the type they are.** Many providers send yes or no flags as the text
  `"true"`, not as a true or false value. Check the field before you write the condition.
* **Use the CRM field, not its label.** For a Salesforce or HubSpot write, use the field the agent
  found with `workflow_find_values`. A restricted picklist accepts only its listed values.
* **Name the exact owner field.** "Owner" can mean the record owner, the account owner, or a custom
  field. Say which one.
* **Name every step.** An unnamed step shows its type on the canvas, which makes a large workflow
  hard to read.

## Test and go live

The agent can check that a draft will publish. It cannot run a draft. Test in the app before your
first publish.

1. Open the workflow in the builder and use **Test** to run it with sample data. See
   [Test a workflow](https://docs.os.default.com/workflows.md#test-a-workflow). A test performs real actions.
2. Read the [run logs](https://docs.os.default.com/workflows/run-logs.md) step by step. A run marked as successful does not prove
   each step did its work. For example, a match step with an empty email takes the No Match path
   without an error.
3. Ask the agent to publish.

> [!WARNING]
>
> **A new workflow goes live the first time you publish it.** Publishing an existing workflow does
> not change whether it is on: a paused workflow stays paused. To pause or resume a workflow, use
> the switch in the builder.

After a publish, the agent can confirm the change with `list_workflows`, and inspect real runs with
`list_workflow_runs` and `get_workflow_logs`. If your workspace has `run_workflow` turned on, the
agent can also start the published version. That run is real, not a test.

## What the agent cannot do

* Delete, pause, or turn on a workflow. Use the app.
* Run a draft. Use **Test** in the builder.
* Work in a different workspace. The workspace comes from your sign-in, not from the prompt.
* Use a CRM field that Default cannot see yet. A new Salesforce or HubSpot field can take up to 15
  minutes to appear. A Salesforce field hidden by field-level security never appears, and the error
  looks the same as a wrong field name.

## Common errors

| What the agent sees | What it means | What to do |
| - | - | - |
| `WRITE_CONFLICT: The draft changed since it was read` | Someone, or another agent, changed the draft. | Read the draft again, then propose the change again. |
| `This node already has a 'default' branch` (or `'matched'`) | The new step went on an exit that is already used. | Read the step's edges and add the new step on a free exit. |
| `This node type only allows one outgoing edge` | The step can have only 1 next step. | Insert the new step after it instead of beside it. |
| `… has 2 outgoing edges; pass via_edge …` | The agent did not say which branch the step goes on. | Name the branch with `via_edge`. |
| `Workflow not found` | The workflow ID is wrong. | Look up the ID with `list_workflows`. |
| `Execution … not found` | The run ID is wrong. | Look up the run with `list_workflow_runs`. |
| A CRM step fails the check with "Unable to describe" | The CRM is not connected, or Default cannot read it. | Check the connection in **Settings**, then check again. |

## Rules for your agent

Paste this block into your agent's instructions, for example a Claude project, a `CLAUDE.md` or
`AGENTS.md` file, or a Cursor rule. It gives the agent the same rules as this page.

```markdown Default workflow rules theme={null}
# Building Default workflows over MCP

Order of work:
1. workflow_describe with no type, then once per step or trigger type you will use.
2. workflow_find_values for every field you fill. Copy option values and reference selectors
   exactly. Never use a value marked availability "downstream". A "blocked" field needs a
   sibling field set first.
3. workflow_read_graph with select "summary" first. Use nodeIds or search to read only what you
   need. Keep the revision it returns.
4. workflow_apply_changes without confirm. Show the person the preview and its issues. Only after
   they approve, send the same arguments plus confirm: true and the confirmationToken.
5. Act on every issue and its repair text before you continue.
6. workflow_validate_graph until it reports valid. It takes a few seconds.
7. workflow_publish without confirm, show the preview, then confirm after approval.

Rules:
- Always send expectedRevision from your latest workflow_read_graph. After any saved change, or
  on WRITE_CONFLICT, read again before the next change. Never retry with an old revision.
- Do not send a new step's exits. The server adds them.
- Before adding after a step, read its edges. Match Record and Display Scheduler have fixed exits.
  Most steps allow one next step. Use via_edge to choose a branch.
- Multi-Branch starts with only Else. Give each new branch a condition and an order.
- Run Experiment starts with no branches. Weights must add up to 100.
- Bind values from earlier steps as references, not typed text.
- Use CRM field API names from workflow_find_values, never display labels.
- Name every step.
- Get workflow IDs from list_workflows and run IDs from list_workflow_runs. Never guess an ID.
- After creating a workflow, use the returned workflowId. Do not send the create again.
- Never publish while validation reports problems. Never publish without the person's approval.
- A new workflow goes live on its first publish. Say so before you ask for approval.
- You cannot delete, pause, turn on, or test-run a draft. Tell the person to use the app.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.