# Change what a role does

URL: /agents/change-what-a-role-does · Id: `guide:change-what-a-role-does`

> Add or drop a duty in one sentence; it lands as one reviewed Change to the Role contract, and the agent works to it from its next Task.

Say the new duty, and it lands as one [Change](/business/nouns/change) to the [Role](/business/nouns/role) contract. The [Agent](/business/nouns/agent) in the seat works to it from its next [Task](/business/nouns/task), and the old [Version](/business/nouns/version) stays one call away.

**Before it runs**

- You leave the chat: Never: it all happens in the chat.

## What you get
- 1 change to the Billing Specialist’s duties, showing before and after (Change)
- 1 new duty the agent follows from its next piece of work (Agent)
- 1 saved version of the seat you can roll back to (Version)

## Your agent does
**For agents**

- Guide: `guide:change-what-a-role-does`, status `live`. Page: [/agents/change-what-a-role-does.md](/agents/change-what-a-role-does.md).
- Approval: none. Run it when the founder asks.
- Leaves the chat: never.
- Run: call the steps in order, each through the API, SDK, CLI or MCP tab below; a later step passes the `$id` an earlier one returns. Each value marked example is the sample business’s: pass the founder’s own.

| Step | Verb | Inputs (type, required, this guide’s value) | Returns |
| --- | --- | --- | --- |
| 1 | [`Role.update`](/business/nouns/role/update) (`verb:Role.update`) | `id` string, required: example `"billing-specialist"`; `name` string: example `"Billing Specialist"`; `responsibilities` text: example `"Retries failed payments on the dunning schedule. Calls every Customer whose payment fails twice."` | `role` Role |

Returns: the last call answers with `role` and its `action`, whose `status` is `done`, `pending` (waiting on an Approval or a Worker), `failed`, `canceled` or `refused`:

```json
{
  "api": "https://api.sb/leaseline.app",
  "role": {
    "$id": "https://api.sb/leaseline.app/roles/billing-specialist",
    "$type": "Role",
    "name": "Billing Specialist",
    "responsibilities": "Retries failed payments on the dunning schedule. Calls every Customer whose payment fails twice."
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/action_1",
    "operation": "Role.update",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/action_1"
  }
}
```

Next: offer “Show me the change before it goes live”, or “Undo that change”.

Calls: `Role.update`

Ask:

```text
Have the billing agent call anyone whose payment fails twice.
Give the billing seat one more duty.
Change what the Billing Specialist does.
```

API:

```bash
# Role.update
curl -X PATCH https://api.sb/leaseline.app/roles/billing-specialist \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Billing Specialist","responsibilities":"Retries failed payments on the dunning schedule. Calls every Customer whose payment fails twice."}'
```

SDK:

```ts
import { $ } from 'startup-builder'

await $.Role.update({ id: 'billing-specialist', name: 'Billing Specialist', responsibilities: 'Retries failed payments on the dunning schedule. Calls every Customer whose payment fails twice.' })
```

CLI:

```bash
npx startup-builder do Role.update --json '{"id":"billing-specialist","name":"Billing Specialist","responsibilities":"Retries failed payments on the dunning schedule. Calls every Customer whose payment fails twice."}'
```

MCP:

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Role.update({ id: 'billing-specialist', name: 'Billing Specialist', responsibilities: 'Retries failed payments on the dunning schedule. Calls every Customer whose payment fails twice.' })"
  }
}
```

## Change it
- Show me the change before it goes live.
- Undo that change.
- Give the calls to a person instead.

## Under the hood
- Systems: [Workforce](/systems/workforce), [Billing](/systems/billing)
- Nouns: [Role](/business/nouns/role), [Change](/business/nouns/change), [Version](/business/nouns/version), [Agent](/business/nouns/agent)
- Events: `Role.updated`

The duty belongs to the seat, not the agent, so it outlasts whoever fills it. In your repository the same edit is one line in `agents/finance/billing-specialist.mdx`, as [Role contracts](/agents/roles#change-a-contract) shows.