Tools and permissions

A Permission is a Verb a Role may perform; a Tool is that Verb as a Worker reaches it. A Worker's Tools are its Role's Permissions, so what an Agent can call and what it may do are one list.

PermissionsCopy Anchor Link

A Permission names a Verb, a Noun, a scope and optionally a Limit: "refund an Order in this 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: presets of Permissions a person holds in the app, apart from the seat they fill. The same presets serve a Customer's admin in their own Tenant.

One name on every InterfaceCopy Anchor Link

A Tool carries one name, Noun.verb, on every 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 record sees the same name the Agent called.

Code modeCopy Anchor Link

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.

// 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 on the Worker chooses between the two.

Checks below the InterfaceCopy Anchor Link

Enforcement lives inside $, identical for the API, SDK, CLI, MCP and every 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 of the definition it ran. Any output traces back to the Worker, instructions and model that produced it.

Access that narrows itselfCopy Anchor Link

An Agent acts with a token scoped to its Role's Permissions and its Task's Nouns, and the token expires with the Task or the Mandate. A Permission left unused past its decay Setting narrows each night through an automatic Change.

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

Tools beyond the VerbsCopy Anchor Link

Some Roles need more than the Startup's Verbs. The Engineering Lead edits code and runs tests; the 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 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.

NextCopy Anchor Link

• Mandates and limits: how much a Permission allows, and for whom.
• MCP: the three Tools in detail.
• Permission and Tool: the Nouns.