# Tools and permissions

URL: /agents/tools-and-permissions · Id: `page:agents/tools-and-permissions`

> A Worker's Tools are exactly its Role's Permissions, checked below every Interface, so what an Agent can call and may do are one list.

A [Permission](/business/nouns/permission) is a [Verb](/business/nouns/verb) a [Role](/business/nouns/role) may perform; a [Tool](/business/nouns/tool) is that Verb as a [Worker](/business/nouns/worker) reaches it. A Worker's Tools are its Role's Permissions, so what an [Agent](/business/nouns/agent) can call and what it may do are one list.

## Permissions
A Permission names a Verb, a [Noun](/business/nouns/noun), a scope and optionally a [Limit](/business/nouns/limit): "refund an [Order](/business/nouns/order) in this [Startup](/business/nouns/startup), up to $100 each". Roles hold Permissions, and Workers gain them only by filling Roles.

The familiar coarse grants are not Roles. Owner, admin, member and viewer are [Access Levels](/business/nouns/access-level): presets of Permissions a person holds in the app, apart from the seat they fill. The same presets serve a [Customer](/business/nouns/customer)'s admin in their own [Tenant](/business/nouns/tenant).

| Role | Permissions, in part |
| --- | --- |
| [Customer Lead](/agents/customer/customer-lead) | `Conversation.answer`, `Task.delegate`, `Task.escalate` |
| [Billing Specialist](/agents/finance/billing-specialist) | `Invoice.bill`, `Invoice.collect`, `Order.refund` up to $100 |
| [Marketing Lead](/agents/marketing/marketing-lead) | `Campaign.create`, `Mandate.spend` up to $500 a month |

## One name on every Interface
A Tool carries one name, `Noun.verb`, on every [Interface](/business/nouns/interface). `Order.refund` is the SDK call `$.Order.refund`, the CLI command `do Order.refund`, the API route `POST /orders/{order}/refund`, and a line of code inside the MCP `do` Tool.

An Agent that learns a Verb in one place knows it everywhere. A person reading the [Action](/business/nouns/action) record sees the same name the Agent called.

## Code mode
An Agent's default Tools are three: `search`, `fetch` and `do`. `search` finds records, Verbs and docs; `fetch` reads one; `do` runs a short TypeScript program against `$`, the typed client.

The types are cut to the Role. Fetching `/$.d.ts` returns only the Verbs this Role holds, so the Agent reads its whole manual in one file. Fifty Verbs cost one types file, not fifty Tool definitions in every prompt.

```ts
// Inside `do`, as the Billing Specialist
const order = await $.Order.get({ id: 'order_17' })
if (order.status === 'paid') {
  return await $.Order.refund({ order: order.$id, amount: order.total, reason: 'Charged twice for one lesson.' })
}
```

An Agent that does not write code gets flat Tools instead: one Tool per Verb, with the same names and the same checks. A [Setting](/business/nouns/setting) on the Worker chooses between the two.

## Checks below the Interface
Enforcement lives inside `$`, identical for the API, SDK, CLI, MCP and every [App](/business/nouns/app). No Interface holds its own rules, so none offers a way around them.

A Verb outside the Role's Permissions starts as an Action already `refused`, with the missing Permission as its reason. Each call inside a `do` program passes its own check, so a program that refunds three Orders gets three verdicts.

Every call records `by`, the model, and the [Version](/business/nouns/version) of the definition it ran. Any output traces back to the Worker, instructions and model that produced it.

## Access that narrows itself
An Agent acts with a token scoped to its Role's Permissions and its [Task](/business/nouns/task)'s Nouns, and the token expires with the Task or the [Mandate](/business/nouns/mandate). A Permission left unused past its decay Setting narrows each night through an automatic [Change](/business/nouns/change).

Unseating ends access at once. A Worker removed from a Role holds none of its Permissions from that moment.

## Tools beyond the Verbs
Some Roles need more than the Startup's Verbs. The [Engineering Lead](/agents/engineering/engineering-lead) edits code and runs tests; the [Researcher](/agents/product/researcher) reads the web.

Those Tools run in an isolated sandbox or a recorded browser session with no other access. Their effects reach the Startup only through Verbs, as a Change to review or an Action to check.

Each Role page lists the [Systems](/business/nouns/system) the Role works through, such as the CRM or the ledger. Systems are headless: their Verbs are Tools like any other, under the same Permissions.

## Next
- [Mandates and limits](/agents/mandates-and-limits): how much a Permission allows, and for whom.
- [MCP](/code/mcp): the three Tools in detail.
- [Permission](/business/nouns/permission) and [Tool](/business/nouns/tool): the Nouns.