> ## 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.
# Triage MCP tools: search, inspect, diagnose
> Read-only tools for searching workflow runs, inspecting run details, diagnosing failures, and reviewing organization health — available to all roles.
The triage tools give you and your agents read-only access to everything Armature knows about past runs, failures, and system health. You can search for runs by status or workflow, pull a full trace for a specific run, get a structured diagnosis of what went wrong, or check the health of your entire organization — all without modifying any state. Every triage tool is annotated as read-only, non-destructive, idempotent, and closed-world: calling them never triggers side effects in your target MCP server or changes any Armature record.
All triage tools are available to every role: viewer, editor, admin, and owner. All responses include both a `text` JSON body and a `structuredContent` field for agent-native consumption. See [Authentication](/mcp-api/authentication) and [Roles](/mcp-api/roles) for access details.
## Tools
`search_runs` returns a paginated list of workflow runs matching your filters. Use it to find recent failures, audit activity for a specific workflow, or surface runs that need attention before kicking off a repair loop.
**Arguments**
| Argument | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------------------------ |
| `workflowId` | string | No | Filter to runs belonging to this workflow. |
| `status` | string | No | One of `pass`, `fail`, `partial`, `running`, `pending`. |
| `limit` | number | No | Maximum number of results to return (default: 20, max: 100). |
| `before` | string | No | ISO 8601 timestamp — return runs started before this time. |
| `after` | string | No | ISO 8601 timestamp — return runs started after this time. |
**Returns**
A list of run summaries, each including: run ID, workflow name, status, start and end timestamps, and trigger type (scheduled, manual).
**Example invocation**
```json theme={null}
{
"name": "search_runs",
"arguments": {
"workflowId": "wf_abc123",
"status": "fail",
"limit": 20
}
}
```
To find all failing runs across your organization regardless of workflow, omit `workflowId` and set `status` to `"fail"`. Pair the returned run IDs with `inspect_run` or `diagnose_run` for deeper investigation.
`inspect_run` returns the full record for a single run identified by its run ID. This is the most detailed view available: you get every criterion result, the complete tool-call trace, evaluator output, cost, duration, and the model used by the tester agent.
**Arguments**
| Argument | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------- |
| `runId` | string | Yes | The ID of the run to inspect. |
**Returns**
A run detail object containing: run metadata (ID, workflow ID, status, timestamps), criterion-level results with pass/fail/partial status and evaluator reasoning, tool-call trace with arguments and responses, total cost in USD, duration in milliseconds, and the model identifier used for the run.
**Example invocation**
```json theme={null}
{
"name": "inspect_run",
"arguments": {
"runId": "run_xyz789"
}
}
```
You can also access the raw trace and artifact for a run via the `armature://runs/{id}/trace` and `armature://runs/{id}/artifact` resources. See [Resources](/mcp-api/resources) for details.
`diagnose_run` performs a structured diagnostic analysis of a single run and returns a structured explanation of what went wrong, along with suggested remediation. Unlike `inspect_run`, which returns raw data, `diagnose_run` interprets the failure — identifying which criteria failed, which tool calls contributed to the failure, and what changes to the workflow or target server might resolve the issue.
**Arguments**
| Argument | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------ |
| `runId` | string | Yes | The ID of the run to diagnose. |
**Returns**
A diagnosis object containing: a summary of the failure, per-criterion analysis with failure reasons, tool call observations, and suggested next steps. The suggestions are structured to feed directly into `propose_workflow_patch` if you want to enter the repair loop.
**Example invocation**
```json theme={null}
{
"name": "diagnose_run",
"arguments": {
"runId": "run_xyz789"
}
}
```
`diagnose_run` is the recommended entry point for the repair loop. After calling it, pass its output as context when calling `propose_workflow_patch`. See [Repair workflow tools](/mcp-api/tools/repair) for the full loop.
`get_org_health` returns an organization-level health summary. Use it to get a high-level picture of which workflows are failing, what your pass rates look like, and whether any monitors are in a degraded state — without needing to enumerate individual runs.
**Arguments**
`get_org_health` takes no arguments.
**Returns**
A health summary object containing: overall pass rate across all workflows, count of passing and failing workflows, a list of currently failing workflows with their most recent run status, and the status of any configured monitors.
**Example invocation**
```json theme={null}
{
"name": "get_org_health",
"arguments": {}
}
```
For per-server tool coverage, use the `armature://mcp-servers/{id}/coverage-report` resource instead. Coverage reports aggregate the most recent 50 runs per server and track up to 100 active tools. See [Resources](/mcp-api/resources).
## Error codes
If a triage tool cannot complete, it returns a JSON-RPC error with an `ApiError` data body. Common codes you may encounter:
| Code | Meaning |
| -------------------------- | -------------------------------------------------------------------------- |
| `forbidden_role` | Your API key does not have sufficient role permissions for this operation. |
| `auth_profile_unavailable` | The API key could not be resolved to an Armature organization. |
See [Errors](/mcp-api/errors) for the full list of structured error codes and their JSON-RPC shapes.
## Next steps
Stage and apply patches to fix failing workflows using the repair loop.
Dispatch manual runs, compare results, and sync your MCP tool catalog.