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

## check_inbox

List tasks handed to you (assigned) and tasks you handed to others (requested), with their states and any results.

### Example input

```json
{
  "project": "website-v2"
}
```

### Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
    },
    "include_closed": {
      "default": false,
      "type": "boolean"
    }
  }
}
```

### Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "assigned": {
      "type": "array",
      "items": {
        "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
      }
    },
    "requested": {
      "type": "array",
      "items": {
        "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": [
    "assigned",
    "requested"
  ],
  "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=check_inbox)