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

## checkpoint

Save progress on a task you are working on: decisions, files touched, next steps and open questions, so you or another agent can resume it later.

### Example input

```json
{
  "task_id": "example-task-id",
  "checkpoint": {
    "progress": "First draft written.",
    "next_steps": [
      "Check the headline length."
    ]
  }
}
```

### Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "checkpoint": {
      "type": "object",
      "properties": {
        "progress": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "decisions": {
          "default": [],
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 500
          }
        },
        "files_touched": {
          "default": [],
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 300
          }
        },
        "next_steps": {
          "default": [],
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 500
          }
        },
        "open_questions": {
          "default": [],
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "required": [
        "progress"
      ]
    }
  },
  "required": [
    "task_id",
    "checkpoint"
  ]
}
```

### Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "task": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "project": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "state": {
          "type": "string",
          "enum": [
            "requested",
            "routed",
            "accepted",
            "working",
            "waiting",
            "verifying",
            "approval",
            "completed",
            "rejected",
            "cancelled"
          ]
        },
        "waiting_on": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "owner_approval",
                "human",
                "agent"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "requester": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "assignee": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "packet": {
          "type": "object",
          "properties": {
            "task": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "deliverable_type": {
              "type": "string",
              "enum": [
                "code",
                "doc",
                "answer",
                "screenshots",
                "reviewed_pr",
                "design",
                "data",
                "other"
              ]
            },
            "acceptance_criteria": {
              "minItems": 1,
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "context": {
              "default": "",
              "type": "string",
              "maxLength": 4000
            },
            "files": {
              "default": [],
              "maxItems": 50,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            },
            "depends_on": {
              "default": [],
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            }
          },
          "required": [
            "task",
            "deliverable_type",
            "acceptance_criteria",
            "context",
            "files",
            "depends_on"
          ],
          "additionalProperties": false
        },
        "result": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "summary": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4000
                },
                "evidence": {
                  "minItems": 1,
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "test_output",
                          "screenshot",
                          "link",
                          "pull_request",
                          "commit",
                          "note"
                        ]
                      },
                      "summary": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "content": {
                        "type": "string",
                        "maxLength": 8000
                      }
                    },
                    "required": [
                      "kind",
                      "summary"
                    ],
                    "additionalProperties": false
                  }
                },
                "provenance": {
                  "type": "string",
                  "enum": [
                    "agent_generated",
                    "from_approved_context",
                    "owner_approved",
                    "owner_instruction"
                  ]
                },
                "returned_by": {
                  "type": "string",
                  "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
                },
                "returned_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": [
                "summary",
                "evidence",
                "provenance",
                "returned_by",
                "returned_at"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "latest_checkpoint": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "progress": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 2000
                },
                "decisions": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 500
                  }
                },
                "files_touched": {
                  "default": [],
                  "maxItems": 100,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "next_steps": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 500
                  }
                },
                "open_questions": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              },
              "required": [
                "progress",
                "decisions",
                "files_touched",
                "next_steps",
                "open_questions"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "created_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)))$"
        },
        "updated_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": [
        "id",
        "project",
        "state",
        "waiting_on",
        "requester",
        "assignee",
        "packet",
        "result",
        "latest_checkpoint",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "task"
  ],
  "additionalProperties": false
}
```

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

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

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