# Diagnose

Why an agent might be failing, in one call: findings with severity and resolution, validation, recent generation and tool failures, failed imports, unanswered questions and the last test run.

|  |  |
| --- | --- |
| REST | `GET /api/v1/agents/{agent_id}/diagnostics` |
| MCP tool | `diagnose_agent` |
| Classification | **Read** (changes nothing) |
| Scope | `agents:read` |
| Minimum role on the agent | editor |
| Confirmation | Not needed |
| Retry safety | Safe to retry with the same input |
| Success status | 200 |

## What it does

Why an agent might be failing, in one call: findings with severity and resolution, validation, recent generation and tool failures, failed imports, unanswered questions and the last test run.

## Side effects

None. It only reads.

## Inputs

| Name | Type | Required | In | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | string | yes | path | The agent id (agt_...), from list_agents. |
| `days` | integer | no | query | Default 7. |

## Example

REST:

```bash
curl "https://covo.lanaai.io/api/v1/agents/agt_4edc89bb2964/diagnostics?days=7" \
  -H "Authorization: Bearer $COVO_TOKEN"
```

MCP (POST /mcp):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "diagnose_agent",
    "arguments": {
      "agent_id": "agt_4edc89bb2964",
      "days": 7
    }
  }
}
```

## Response

Returns an object with `healthy`, `findings`, `validation`, `recent`, `unanswered_questions` and `last_test_run`. This is a real response, shortened to two items per list.

200 response:

```json
{
  "healthy": true,
  "findings": [],
  "validation": {
    "valid": true,
    "state": "ready",
    "errors": [],
    "warnings": [
      {
        "step": "knowledge",
        "field": null,
        "severity": "recommended",
        "message": "Add a few common questions. Short, specific answers work best."
      }
    ],
    "checks": [
      {
        "name": "ai_provider",
        "status": "pass",
        "message": "The AI provider is configured."
      },
      {
        "name": "reply_allowance",
        "status": "pass",
        "message": "2999 AI replies left this month."
      }
    ]
  },
  "recent": {
    "days": 7,
    "generation_failures": 0,
    "rate_limited": 0,
    "unanswered": 0,
    "tool_failures": [],
    "source_failures": []
  },
  "unanswered_questions": [],
  "last_test_run": {
    "id": "68c583c0-3bb6-42d3-85b4-193ea6eeca79",
    "revision": 7,
    "passed": 1,
    "failed": 0,
    "cases": [
      {
        "name": "Explains the studio",
        "turns": [
          {
            "reply": "Northwind Labs\nNorthwind Labs builds private AI systems for small law firms.",
            "message": "What does Northwind Labs do?",
            "grounding": "known",
            "components": [
              "suggested_questions"
            ],
            "latency_ms": 40,
            "handed_to_person": false
          }
        ],
        "passed": true,
        "failures": [],
        "conversation_id": "b2412a0b-9da5-4df5-adc9-031895e6a98c"
      }
    ],
    "client": {
      "name": "docs-examples",
      "interface": "rest"
    },
    "created_at": "2026-10-07T20:14:41.959Z"
  }
}
```

Over MCP the same object comes back as the tool result, in `structuredContent` and as JSON text.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthorized` | No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect. |
| 403 | `account_suspended` | The account that owns the token is paused. |
| 403 | `insufficient_scope` | The token lacks `agents:read`. |
| 404 | `agent_not_found` | Unknown agent, or not reachable with this token. |
| 400 | `bad_request` | An input is invalid; `field` names it. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |