> ## 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.

# MCP prompts for workflow repair and authoring

> Use Armature MCP prompts to start structured repair and coverage-driven authoring sessions—with sequenced steps that guide agents through each workflow.

Armature's MCP endpoint exposes two prompts that give agents a structured starting point for common tasks. Prompts are returned from `prompts/list` and invoked via `prompts/get` with the prompt name. When your agent receives a prompt, it gets an ordered set of instructions and context—the prompt does not execute automatically. Your agent then follows the steps, calling tools and reading resources in sequence, and pauses where human input is required.

<Note>
  Prompts are available to all roles. The tools and resources each prompt references are subject to their own role requirements—for example, `apply_workflow_change` requires editor role or higher. See [Roles](/mcp-api/roles) for the full permission matrix.
</Note>

## repair\_failing\_workflow

Use this prompt when a workflow run has failed and you want to diagnose the failure, propose a fix, get it approved, apply it, and confirm the repair in a single guided session. The prompt sequences all seven steps of the repair loop for you.

<Steps>
  <Step title="Diagnose the failing run">
    Call `diagnose_run` with the ID of the failing run. This tool inspects the run trace, identifies which criteria failed or received partial scores, and surfaces the tool calls and trace events most likely responsible for the failure.

    Read `armature://runs/{id}/trace` alongside the diagnosis to get the full picture of what the agent attempted and where execution broke down.
  </Step>

  <Step title="Propose a patch">
    Call `propose_workflow_patch` with your proposed changes and a rationale explaining why the patch addresses the diagnosed failure. Reference specific run IDs, criterion IDs, tool-call IDs, or trace-event IDs as evidence.

    Armature validates the proposed spec against the current workflow version and the active tool catalog, then persists the proposal and returns a proposal ID and a field-level diff.
  </Step>

  <Step title="Review the proposal and diff">
    Read `armature://workflow-change-proposals/{id}` using the proposal ID returned in the previous step. Review the proposed spec, rationale, field-level diff, and any warnings before presenting the changes to a human reviewer.

    Pay particular attention to warnings such as `unknown_tool_policy_entry`, which indicate that a tool referenced in the patch is not in the active catalog.
  </Step>

  <Step title="Wait for human approval">
    Present the diff and rationale to a human and wait for explicit approval before proceeding. Do not call `apply_workflow_change` without a human decision.

    Proposals expire after 24 hours. If the proposal expires before approval, re-run `propose_workflow_patch` to stage a fresh proposal against the current workflow version.
  </Step>

  <Step title="Apply the approved change">
    Call `apply_workflow_change` with the approved proposal ID. This requires editor role or higher.

    Apply uses optimistic concurrency against `baseVersionId`. If the workflow has been updated since the proposal was staged, Armature returns `base_version_stale` with the current version ID—re-propose against the new version before retrying.

    Repeated apply calls for the same proposal are idempotent: if the proposal has already been applied, the response returns success with `alreadyApplied: true`.
  </Step>

  <Step title="Run the patched workflow">
    Call `run_workflow_now` with `wait: true` to dispatch a manual run of the patched workflow and wait for it to reach a terminal state.

    If the run does not complete within the wait timeout, Armature returns `run_wait_timeout`. The run continues in the background—poll `inspect_run` with the returned run ID to check its status.
  </Step>

  <Step title="Compare the new run to the baseline">
    Call `compare_runs` with the new run ID and the ID of the original failing run as the baseline. The comparison aligns criteria by ID for same-version runs, by normalized text across versions, and by position when text is unavailable.

    The response surfaces which criteria improved, which remain failing, and a summary of changed tool-call failures. Use this to confirm the patch resolved the original failure without introducing regressions.
  </Step>
</Steps>

***

## design\_workflow\_suite

Use this prompt when you want to expand workflow coverage for an MCP server by identifying uncovered tools and authoring new workflows or regression drafts to fill the gaps.

<Steps>
  <Step title="Read the coverage report">
    Read `armature://mcp-servers/{id}/coverage-report` for the target MCP server. The report lists which tools in the server's active catalog are exercised by at least one successful run and which tools have no coverage.

    Coverage reports use fixed defaults: the most recent 50 runs and at most 100 active tools. Use the uncovered tool list to prioritize which gaps to address first.
  </Step>

  <Step title="Read the workflow schema">
    Read `armature://schemas/workflow` to load the full JSON schema for valid Armature workflow specs. Use the schema to construct well-formed workflow definitions and to avoid `validation_failed` errors when staging proposals.

    Also read `armature://docs/evaluation-criteria` to understand how criteria will be evaluated, so the criteria you write are specific, externally checkable, and evidence-grounded.
  </Step>

  <Step title="Stage proposals or regression drafts to cover gaps">
    For each uncovered tool or group of tools, choose one of two approaches:

    * Call `propose_workflow_patch` to stage a patch against an existing workflow that adds coverage for the uncovered tool—for example, by adding criteria that require the tool to be called, or by updating `toolPolicy.allowed_tools`.
    * Call `draft_regression_workflow_from_run` to create a focused, manual-only regression workflow based on a previous failed run that exercised the tool. Regression drafts copy the source run prompt verbatim, select failed or partial required criteria, narrow `allowed_tools` to tools actually called in that run, and set the schedule to manual-only.

    Review each staged proposal using `armature://workflow-change-proposals/{id}` before presenting it for human approval.
  </Step>
</Steps>

<Tip>
  Write workflow criteria as externally checkable outcomes tied to specific tool calls or observable state changes. Criteria like "The agent calls `create_order` and returns the order ID" are easier for the evaluator to score reliably than broad assertions like "The order is created successfully."
</Tip>

***

## Related pages

* [MCP API overview](/mcp-api/overview) — endpoint and client setup
* [Triage tools](/mcp-api/tools/triage) — `diagnose_run`, `search_runs`, `inspect_run`
* [Repair tools](/mcp-api/tools/repair) — `propose_workflow_patch`, `apply_workflow_change`, `run_workflow_now`, `compare_runs`
* [Run tools](/mcp-api/tools/runs) — `run_workflow_now`, `compare_runs`
* [Resources](/mcp-api/resources) — all `armature://` URIs used by these prompts
* [Error codes](/mcp-api/errors) — errors you may encounter during prompt execution