> ## 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 resources: run traces, schemas, catalogs

> Read structured Armature data—run traces, artifacts, workflow schemas, coverage reports, and staged proposals—using addressable armature:// URIs.

Armature exposes eight read-only resources through its MCP endpoint. Each resource has a stable `armature://` URI and returns structured data your agent can read without triggering side effects. All resources are annotated as read-only, non-destructive, idempotent, and closed-world, meaning they never reach external systems and never mutate state. Resource URIs do not accept query strings—use the exact URI patterns listed below.

<Note>
  To read any resource, your MCP client must be authenticated with a valid API key. All roles—viewer, editor, admin, and owner—can read resources. See [Authentication](/mcp-api/authentication) and [Roles](/mcp-api/roles) for details.
</Note>

## Resource reference

<AccordionGroup>
  <Accordion title="armature://catalog/models">
    **URI:** `armature://catalog/models`

    Returns the list of AI models available for running Armature workflows. Use this resource when authoring or validating a workflow spec to confirm that the model you want to assign is active in your organization's catalog.

    The response lists each model's identifier, display name, and provider. Use the identifier value when setting the `model` field in a workflow definition.

    **Typical use:** Read this resource at the start of a `design_workflow_suite` session, or when a `propose_workflow_patch` draft references a model and you need to verify the model ID.
  </Accordion>

  <Accordion title="armature://schemas/workflow">
    **URI:** `armature://schemas/workflow`

    Returns the full JSON schema that defines a valid Armature workflow specification. The schema covers every field: `name`, `description`, `model`, `prompt`, `schedule`, `toolPolicy`, `criteria`, and the nested structures within each.

    Use this resource to validate a draft spec before staging it with `propose_workflow_patch`, or to understand exactly which fields and values are accepted. The `design_workflow_suite` prompt reads this resource automatically as its second step.

    **Typical use:** Load the schema into your agent's context before drafting new criteria or constructing a workflow from scratch. Compare your draft against the schema to catch `validation_failed` errors before they reach the proposal stage.
  </Accordion>

  <Accordion title="armature://docs/evaluation-criteria">
    **URI:** `armature://docs/evaluation-criteria`

    Returns Armature's documentation on how the evaluator scores criteria. The document explains what constitutes a **pass**, **partial**, and **fail** outcome, how the evaluator uses evidence from the agent trace, and how criterion weight and required/optional flags affect the overall run result.

    **Typical use:** Read this resource when writing new criteria to ensure they are externally checkable and specific enough for the evaluator to score consistently. Vague criteria—such as "works well" or "looks good"—produce unreliable evaluations; this document explains what precise, evidence-grounded criteria look like.
  </Accordion>

  <Accordion title="armature://runs/{id}/trace">
    **URI:** `armature://runs/{id}/trace`

    Returns the full agent trace for a specific run, identified by its run ID. The trace includes every tool call, every tool response, every trace event, and every evaluator step, in the order they occurred.

    Replace `{id}` with the UUID of the run you want to inspect. You can find run IDs from `search_runs` or `inspect_run` tool responses.

    **Typical use:** Read the trace when diagnosing a failing run to understand exactly which tool calls failed, what arguments were passed, and what the evaluator observed. The `repair_failing_workflow` prompt uses trace data as the foundation for its diagnosis step.

    <Note>
      The trace resource is the most detailed view of a run. For just the agent's final output, use `armature://runs/{id}/artifact` instead.
    </Note>
  </Accordion>

  <Accordion title="armature://runs/{id}/artifact">
    **URI:** `armature://runs/{id}/artifact`

    Returns the run artifact for a specific run—the final output produced by the agent at the end of the workflow execution. This is the agent's answer or result, not the full tool-call history.

    Replace `{id}` with the UUID of the run.

    **Typical use:** Read the artifact when you need the agent's final answer for comparison, reporting, or regression analysis. Use `armature://runs/{id}/trace` when you need the step-by-step execution record.
  </Accordion>

  <Accordion title="armature://mcp-servers/{id}/tool-catalog">
    **URI:** `armature://mcp-servers/{id}/tool-catalog`

    Returns the full tool catalog for a specific MCP server, identified by its server ID. The catalog includes every tool's name, input schema, and description, as Armature last recorded them from the server's `tools/list` response.

    Replace `{id}` with the MCP server ID. You can find server IDs from workflow definitions or the Armature dashboard.

    **Typical use:** Read the tool catalog when constructing or validating a `toolPolicy` block in a workflow patch. If the catalog is stale, use `sync_mcp_server_capabilities` (admin or owner role required) to refresh it before reading again.

    <Tip>
      Cross-reference this catalog with `armature://mcp-servers/{id}/coverage-report` to identify which tools in the catalog are not yet exercised by any workflow.
    </Tip>
  </Accordion>

  <Accordion title="armature://mcp-servers/{id}/coverage-report">
    **URI:** `armature://mcp-servers/{id}/coverage-report`

    Returns the coverage report for a specific MCP server. The report shows which tools in the server's catalog are exercised by at least one successful workflow run and which tools remain uncovered.

    Replace `{id}` with the MCP server ID.

    **Fixed resource defaults:** Coverage reports always use the most recent 50 runs for the server and consider at most 100 active tools. These limits are fixed—resource URIs do not accept query strings to override them.

    **Typical use:** Read this resource as the first step in the `design_workflow_suite` prompt to understand which tools have no test coverage. Use the gap list to drive decisions about which workflows to create or patch next.

    <Note>
      Coverage comes from successful tool calls in run traces, or from tools explicitly listed in a workflow's `toolPolicy.allowed_tools`. An open-policy workflow—one with no `allowed_tools` constraint—does not count as covering every tool.
    </Note>
  </Accordion>

  <Accordion title="armature://workflow-change-proposals/{id}">
    **URI:** `armature://workflow-change-proposals/{id}`

    Returns the full contents of a staged workflow change proposal, identified by its proposal ID. The response includes the proposed workflow spec, the agent-supplied rationale, a field-level diff showing every changed field, evidence references (run IDs, criterion IDs, tool-call IDs, trace-event IDs), and any warnings generated during validation.

    Replace `{id}` with the proposal UUID returned by `propose_workflow_patch` or `draft_regression_workflow_from_run`.

    Proposals expire after 24 hours. Reading an expired proposal returns a `proposal_expired` error. Once a proposal is applied via `apply_workflow_change`, it is retained for audit purposes and remains readable.

    **Typical use:** Read this resource after staging a patch to review the proposed changes and diff before asking a human to approve them. The `repair_failing_workflow` prompt includes this step explicitly—the agent reads the proposal, presents the diff, and waits for approval before calling `apply_workflow_change`.

    <Warning>
      Never apply a proposal without reviewing the field-level diff and warnings. Warnings such as `unknown_tool_policy_entry` indicate that the proposal references a tool not in the active catalog, which may cause validation failures at run time.
    </Warning>
  </Accordion>
</AccordionGroup>

## Related pages

* [MCP API overview](/mcp-api/overview) — endpoint URL, client setup, and available surfaces
* [Triage tools](/mcp-api/tools/triage) — `search_runs`, `inspect_run`, `diagnose_run`, `get_org_health`
* [Repair tools](/mcp-api/tools/repair) — `propose_workflow_patch`, `apply_workflow_change`, and related tools
* [Prompts](/mcp-api/prompts) — guided multi-step sequences that use these resources
* [Error codes](/mcp-api/errors) — structured errors returned by resource reads