# Role programs: review, staff, vacate

URL: /code/mcp/role/verbs · Id: `page:code/mcp/role/verbs`

> The Role Verbs review, staff, vacate as MCP do programs, with inputs, result, refusals and an example.

Reference for [Role](/business/nouns/role), one group of [Role programs](/code/mcp/role).

### Role.review
Review checks one Role against its contract for a period and records a Role Review. [Verb page](/business/nouns/role/review?interface=mcp).

```text
do: return await $.Role.review(input)
```

Emits [`Role.reviewed`](/business/events/Role.reviewed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role to review. |
| `period` | `string` | Yes | The period it covers, such as `2026-W43`. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The reviewed Role. |
| `roleReview` | [Role Review](/business/nouns/role-review) | Yes | The recorded Role Review. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Role.review({ role: 'role_oloMFMUeCH', period: 'Example period' })"
  }
}
```

### Role.staff
Staff fills a Role with a Worker, human or agent, who then performs the Role’s Verbs under its Permissions. [Verb page](/business/nouns/role/staff?interface=mcp).

```text
do: return await $.Role.staff(input)
```

Emits [`Role.staffed`](/business/events/Role.staffed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role to fill. |
| `worker` | [Worker](/business/nouns/worker) | Yes | The Worker who fills it. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The staffed Role. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
| The record is not in a state that allows this Verb, so the call is refused. | [`refused`](/code/api/errors/refused) | Read the record, run the Verb that moves it to an allowed state, then retry. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Role.staff({ role: 'role_oloMFMUeCH', worker: 'worker_whZFpOKWIV' })"
  }
}
```

### Role.vacate
Vacate takes the Worker out of a Role, and the seat’s Tasks route to the Role it escalates to until a new Worker is staffed. [Verb page](/business/nouns/role/vacate?interface=mcp).

```text
do: return await $.Role.vacate(input)
```

Emits [`Role.vacated`](/business/events/Role.vacated).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The Role to empty. |
| `reason` | `text` | No | Why the seat empties. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [Role](/business/nouns/role) | Yes | The vacant Role. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Role.vacate({ role: 'role_oloMFMUeCH' })"
  }
}
```