> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armature.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Run and sync tools: trigger runs and catalog sync
> Dispatch manual workflow runs with idempotent keys, compare run results across versions, and refresh your MCP server tool catalog.
The run and sync tools let you take action beyond reading and proposing: you can trigger a workflow run on demand, compare its results against a baseline to measure improvement, and keep Armature's view of your target MCP server in sync with the server's actual capabilities. These tools sit at the boundary between Armature's closed world and your target MCP server — dispatching a run or syncing capabilities reaches out to the target server, so their behavior depends on the server's current state.
## Tools
`run_workflow_now` dispatches a manual run of a workflow immediately, outside of any scheduled trigger. It is the standard tool for verifying a fix after applying a workflow patch, for on-demand health checks, or for forcing a run during an incident.
**How idempotency works**
Armature normalizes the `reason` field and builds or accepts an explicit idempotency key. From those inputs it derives a deterministic UUIDv5 run ID. If you call `run_workflow_now` again with the same idempotency key before the run reaches a terminal state, Armature returns the in-progress run rather than dispatching a second one. This makes it safe to retry the tool call if your agent loses its connection.
**Optional wait**
If you pass `wait: true`, Armature polls the run until it reaches a terminal status (`pass`, `fail`, or `partial`) and returns the full result inline. If the run does not complete within the polling window, Armature returns a `run_wait_timeout` error — the run is not canceled and continues to completion asynchronously.
**Annotations**
`run_workflow_now` is marked **destructive** and **open-world**. It exercises the workflow's tester agent against your target MCP server, which means tool calls in the workflow may create orders, send messages, modify records, or trigger other side effects in the target system. Design your workflows with run-scoped data to limit blast radius — see [Authoring workflows](/workflows/authoring) for guidance on run-scoped data.
**Arguments**
| Argument | Type | Required | Description |
| ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| `workflowId` | string | Yes | The workflow to run. |
| `reason` | string | Yes | A human-readable reason for the manual run. Normalized and included in the audit record. |
| `wait` | boolean | No | If true, poll until terminal status and return the result inline. |
| `idempotencyKey` | string | No | Explicit idempotency key. If omitted, Armature derives one from the reason and timestamp. |
**Returns**
If `wait` is false or omitted: a dispatch confirmation with the derived run ID and a link to poll status via `inspect_run`. If `wait` is true: the full run result, equivalent to the response from `inspect_run`.
**Example invocation**
```json theme={null}
{
"name": "run_workflow_now",
"arguments": {
"workflowId": "wf_abc123",
"reason": "Verifying fix for criteria failure on order creation",
"wait": true
}
}
```
`run_workflow_now` requires **editor, admin, or owner** role. Viewers cannot dispatch runs. See [Roles](/mcp-api/roles).
After a `run_wait_timeout`, call `search_runs` or `inspect_run` with the returned run ID to check on the run's progress. Do not dispatch a second run with the same idempotency key — the original run is still executing.
`compare_runs` compares a new run to a baseline run and returns a structured delta. Use it after applying a workflow patch and dispatching a new run to quantify the improvement — which criteria moved from failing to passing, which tool calls changed, and whether any new failures were introduced.
**How criteria alignment works**
Armature aligns criteria between the two runs using the following strategy, in order:
1. **Same-version runs**: criteria are aligned by criterion ID (exact match).
2. **Cross-version runs**: criteria are aligned by normalized text when the criterion IDs differ (for example, after a patch added, removed, or reworded criteria).
3. **Position fallback**: when text alignment is unavailable, criteria are aligned by their position in the criteria list.
Tool-call deltas identify which tool calls changed between the two runs, with particular focus on tools that were failing in the baseline and are no longer called or are now succeeding in the new run.
**Arguments**
| Argument | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------------------------------------------- |
| `baseRunId` | string | Yes | The baseline run to compare against (typically the failing run). |
| `newRunId` | string | Yes | The new run to evaluate (typically the post-patch run). |
**Returns**
A comparison object containing: per-criterion status delta (pass/fail/partial before and after), a summary of criteria that improved or regressed, tool-call deltas highlighting changed failed tools, and overall status change.
**Example invocation**
```json theme={null}
{
"name": "compare_runs",
"arguments": {
"baseRunId": "run_xyz789",
"newRunId": "run_abc001"
}
}
```
`compare_runs` is available to all roles (viewer and above) and is non-destructive. It reads existing run records and does not trigger any new execution.
`sync_mcp_server_capabilities` refreshes Armature's snapshot of the tools exposed by your target MCP server. Armature uses this catalog when validating tool policy entries in workflow proposals — keeping the catalog current ensures validation is accurate.
**Sync cooldown**
To avoid hammering the target server, Armature enforces a **5-minute cooldown per server**, based on the timestamp of the most recent snapshot. If you call `sync_mcp_server_capabilities` before the cooldown has elapsed, Armature returns a `cooldown_pending` error with the time remaining.
**Force sync**
Passing `force: true` bypasses the cooldown. This is only available to **admin and owner** roles making explicit calls — it cannot be triggered by agents with editor or lower permissions, and it does not apply to implicit catalog syncs that occur during proposal validation.
**Implicit syncs during proposal validation**
When `propose_workflow_patch` references a tool that is not in the active catalog, Armature may attempt an implicit `tools/list` call to the target server. This implicit sync shares the same 5-minute cooldown, is audited, and is available even for viewer-role agents. If the sync fails, validation continues against the stale catalog and returns a `catalog_stale_sync_failed` warning.
**Annotations**
`sync_mcp_server_capabilities` is non-destructive but **open-world**: it calls `tools/list` on your target MCP server to retrieve the current tool list. The target server must be reachable. If it is not, Armature returns `target_unreachable` or `target_returned_invalid_schema`.
**Arguments**
| Argument | Type | Required | Description |
| ---------- | ------- | -------- | ----------------------------------------------------------------- |
| `serverId` | string | Yes | The Armature MCP server ID to sync. |
| `force` | boolean | No | If true, bypasses the 5-minute cooldown. Requires admin or owner. |
**Returns**
A sync result containing: the server ID, the timestamp of the new snapshot, the number of tools discovered, and any schema warnings returned by the target server.
**Example invocation**
```json theme={null}
{
"name": "sync_mcp_server_capabilities",
"arguments": {
"serverId": "mcp_srv_99z",
"force": false
}
}
```
`sync_mcp_server_capabilities` requires **admin or owner** role. Editors and viewers cannot trigger explicit capability syncs. See [Roles](/mcp-api/roles).
After syncing, you can inspect the updated tool catalog via the `armature://mcp-servers/{id}/tool-catalog` resource. Coverage reports at `armature://mcp-servers/{id}/coverage-report` use the most recent 50 runs and up to 100 active tools. See [Resources](/mcp-api/resources).
## Error codes
| Code | Meaning |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `dispatch_failed` | Armature could not queue the run. Check that the workflow is active and your target server is reachable. |
| `run_wait_timeout` | The run did not reach a terminal status within the polling window. The run is still executing. |
| `cooldown_pending` | A capability sync was requested before the 5-minute cooldown elapsed. |
| `target_unreachable` | Armature could not connect to the target MCP server during a sync. |
| `target_returned_invalid_schema` | The target server responded to `tools/list` but returned a schema Armature could not parse. |
| `forbidden_role` | Your API key does not have the role required by this tool. |
| `workflow_inactive` | The target workflow is inactive and cannot be dispatched. |
See [Errors](/mcp-api/errors) for the full list of structured error codes and their JSON-RPC shapes.
## Next steps
Search runs, inspect traces, and diagnose failures before triggering a manual run.
Stage and apply patches to fix failing workflows using the repair loop.