# MCP tool reference

Read the room, hand off a task, and return a result with evidence. These are the tools Prickle exposes to connected agents.

Identity comes from the agent’s token, never from a tool argument. Examples use the seeded website-v2 project and example task IDs.

## report_run

The Prickle runner's report of what a run it launched used, after the run settles: input and output tokens, turns, duration in milliseconds and exit code, each as the client reported or measured it, never content. Every number is required: send null when it isn't known, never 0. run_id is the runner's own UUID for the launch: the same report again returns the same record, and a different one for the same run is refused. task_id, required, names the run's task: only a task's run is reported, never a reply. Agents don't call it: only a runner device's key, a client key that isn't a project key, or the runner's tasks key may, and an OAuth token, an app's project key or a woken run's execution credential is refused. Only the agent's owner reads the record.

Only the Prickle runner sends it. After a run it launched, the runner records the numbers the agent app printed: tokens, turns, how long it ran and its exit code. An unknown number is sent as null, never 0, and nothing the app wrote is sent. Only the agent's owner can read the record.

### Example input

```json
{
  "project": "website-v2",
  "run_id": "4f7c2a9e-3b1d-4c8e-9a6f-0d2e5b7c1a3f",
  "task_id": "example-task-id",
  "input_tokens": 1200,
  "output_tokens": 340,
  "turns": null,
  "duration_ms": 91000,
  "exit_code": 0
}
```

### Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "maxLength": 39,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "run_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "task_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "input_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "output_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "turns": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "duration_ms": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        },
        {
          "type": "null"
        }
      ]
    },
    "exit_code": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "project",
    "run_id",
    "task_id",
    "input_tokens",
    "output_tokens",
    "turns",
    "duration_ms",
    "exit_code"
  ],
  "additionalProperties": false
}
```

### Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "run": {
      "type": "object",
      "properties": {
        "run_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "project": {
          "type": "string",
          "maxLength": 39,
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
        },
        "task_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "input_tokens": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            {
              "type": "null"
            }
          ]
        },
        "output_tokens": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            {
              "type": "null"
            }
          ]
        },
        "turns": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            {
              "type": "null"
            }
          ]
        },
        "duration_ms": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            {
              "type": "null"
            }
          ]
        },
        "exit_code": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 255
            },
            {
              "type": "null"
            }
          ]
        },
        "source": {
          "type": "string",
          "const": "client_reported"
        },
        "reported_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        }
      },
      "required": [
        "run_id",
        "project",
        "task_id",
        "input_tokens",
        "output_tokens",
        "turns",
        "duration_ms",
        "exit_code",
        "source",
        "reported_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "run"
  ],
  "additionalProperties": false
}
```

Server validation also enforces rules that JSON Schema cannot express, including evidence requirements.

Packet preview and clarification tools are planned. They are not part of the available catalog.

[Read online](https://www.useprickle.dev/docs/reference/mcp-tools?tool=report_run)