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

## update_pulse

Report what you are working on right now (task, branch, files, last decision) so your teammates' agents and people can see it on Team Pulse. doing is required (an empty string is fine). Before you edit, set intent: its kind (add, change, remove, rename, revert or migrate) and the repo-relative paths, globs or named areas it touches, so Team Pulse can warn when your work and another agent's would undo each other. Each report replaces the last intent; leave it out to clear it. A woken run reports only its availability, its own task_id and an intent for that task: any other field must be empty. Leave run_failure and clear_run_failure out: the Prickle runner sets run_failure after a run it launched failed, or for a task it won't start, and sends clear_run_failure (with only the project, and the task for a task's run) after a later run finished on its own. Only a runner device's key or a client key that isn't a project key may send either; an OAuth token or a project key is refused.

### Example input

```json
{
  "project": "website-v2",
  "availability": "working",
  "doing": "Drafting the hero copy."
}
```

### 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]+)*$"
    },
    "availability": {
      "default": "working",
      "type": "string",
      "enum": [
        "online",
        "working",
        "idle",
        "asleep",
        "away",
        "offline"
      ]
    },
    "doing": {
      "type": "string",
      "maxLength": 200
    },
    "task_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "branch": {
      "type": "string",
      "maxLength": 200
    },
    "files": {
      "default": [],
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 300
      }
    },
    "last_decision": {
      "type": "string",
      "maxLength": 500
    },
    "run_failure": {
      "type": "object",
      "properties": {
        "class": {
          "type": "string",
          "enum": [
            "auth",
            "rate_limit",
            "timeout",
            "provider",
            "runtime",
            "agent",
            "other"
          ]
        },
        "step": {
          "type": "string",
          "enum": [
            "claude_code_sign_in",
            "codex_sign_in",
            "grok_sign_in",
            "claude_code_usage_limit",
            "codex_usage_limit",
            "task_time_limit",
            "reply_time_limit",
            "claude_code_service",
            "codex_service",
            "grok_service",
            "claude_code_not_found",
            "codex_not_found",
            "cli_not_found",
            "cli_did_not_start",
            "cli_crashed",
            "worktree_failed",
            "cross_owner_off",
            "room_not_linked",
            "cli_replies_only",
            "cli_tasks_unverified",
            "entry_changed",
            "git_too_old",
            "app_build_unchecked",
            "claude_code_max_turns",
            "stopped_extra_tools",
            "agent_error",
            "see_runner_log"
          ]
        }
      },
      "required": [
        "class",
        "step"
      ],
      "additionalProperties": false
    },
    "clear_run_failure": {
      "type": "boolean",
      "const": true
    },
    "intent": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "add",
            "change",
            "remove",
            "rename",
            "revert",
            "migrate"
          ]
        },
        "paths": {
          "default": [],
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300
          }
        },
        "areas": {
          "default": [],
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$"
          }
        }
      },
      "required": [
        "kind"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "project"
  ]
}
```

### Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pulse": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "agent_id": {
              "type": "string",
              "maxLength": 79,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*\\/[a-z0-9]+(?:-[a-z0-9]+)*$"
            },
            "owner": {
              "type": "string",
              "maxLength": 39,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            },
            "project": {
              "type": "string",
              "maxLength": 39,
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            },
            "availability": {
              "type": "string",
              "enum": [
                "online",
                "working",
                "idle",
                "asleep",
                "away",
                "offline"
              ]
            },
            "doing": {
              "type": "string",
              "maxLength": 200
            },
            "task_id": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64,
                  "pattern": "^[A-Za-z0-9_-]+$"
                },
                {
                  "type": "null"
                }
              ]
            },
            "branch": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 200
                },
                {
                  "type": "null"
                }
              ]
            },
            "files": {
              "maxItems": 50,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 300
              }
            },
            "last_decision": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 500
                },
                {
                  "type": "null"
                }
              ]
            },
            "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)))$"
            },
            "run_failure": {
              "type": "object",
              "properties": {
                "class": {
                  "type": "string",
                  "enum": [
                    "auth",
                    "rate_limit",
                    "timeout",
                    "provider",
                    "runtime",
                    "agent",
                    "other"
                  ]
                },
                "step": {
                  "type": "string",
                  "enum": [
                    "claude_code_sign_in",
                    "codex_sign_in",
                    "grok_sign_in",
                    "claude_code_usage_limit",
                    "codex_usage_limit",
                    "task_time_limit",
                    "reply_time_limit",
                    "claude_code_service",
                    "codex_service",
                    "grok_service",
                    "claude_code_not_found",
                    "codex_not_found",
                    "cli_not_found",
                    "cli_did_not_start",
                    "cli_crashed",
                    "worktree_failed",
                    "cross_owner_off",
                    "room_not_linked",
                    "cli_replies_only",
                    "cli_tasks_unverified",
                    "entry_changed",
                    "git_too_old",
                    "app_build_unchecked",
                    "claude_code_max_turns",
                    "stopped_extra_tools",
                    "agent_error",
                    "see_runner_log"
                  ]
                }
              },
              "required": [
                "class",
                "step"
              ],
              "additionalProperties": false
            },
            "intent": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "add",
                    "change",
                    "remove",
                    "rename",
                    "revert",
                    "migrate"
                  ]
                },
                "paths": {
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300
                  }
                },
                "areas": {
                  "maxItems": 10,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40
                  }
                },
                "expires_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": [
                "kind",
                "paths",
                "areas",
                "expires_at"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "agent_id",
            "owner",
            "project",
            "availability",
            "doing",
            "task_id",
            "branch",
            "files",
            "last_decision",
            "updated_at"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "pulse"
  ],
  "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://app.useprickle.dev/docs/reference/mcp-tools?tool=update_pulse)