Skip to main content

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.

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 worksArmature 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 waitIf 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.Annotationsrun_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 for guidance on run-scoped data.Arguments
ArgumentTypeRequiredDescription
workflowIdstringYesThe workflow to run.
reasonstringYesA human-readable reason for the manual run. Normalized and included in the audit record.
waitbooleanNoIf true, poll until terminal status and return the result inline.
idempotencyKeystringNoExplicit idempotency key. If omitted, Armature derives one from the reason and timestamp.
ReturnsIf 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
{
  "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.
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 worksArmature 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
ArgumentTypeRequiredDescription
baseRunIdstringYesThe baseline run to compare against (typically the failing run).
newRunIdstringYesThe new run to evaluate (typically the post-patch run).
ReturnsA 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
{
  "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 cooldownTo 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 syncPassing 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 validationWhen 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.Annotationssync_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
ArgumentTypeRequiredDescription
serverIdstringYesThe Armature MCP server ID to sync.
forcebooleanNoIf true, bypasses the 5-minute cooldown. Requires admin or owner.
ReturnsA 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
{
  "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.
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.

​
Error codes

CodeMeaning
dispatch_failedArmature could not queue the run. Check that the workflow is active and your target server is reachable.
run_wait_timeoutThe run did not reach a terminal status within the polling window. The run is still executing.
cooldown_pendingA capability sync was requested before the 5-minute cooldown elapsed.
target_unreachableArmature could not connect to the target MCP server during a sync.
target_returned_invalid_schemaThe target server responded to tools/list but returned a schema Armature could not parse.
forbidden_roleYour API key does not have the role required by this tool.
workflow_inactiveThe target workflow is inactive and cannot be dispatched.
See Errors for the full list of structured error codes and their JSON-RPC shapes.

​
Next steps

Triage tools

Search runs, inspect traces, and diagnose failures before triggering a manual run.

Repair workflow tools

Stage and apply patches to fix failing workflows using the repair loop.