> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Administration

> Users, departments, categories, grantable tools, guardrails, self-learning, credits, pricing, and provider ledger.

Users, departments, categories, grantable tools, guardrails, self-learning provisioning, credits, and (Superadmin) platform pricing.

***

## Users & organization

### `user_create`

Provision a **new user** in this tenant. Link-based onboarding: an invite / set-password link is emailed to the user — **no password is ever returned over the API**. Sets tenant, workspace and role and adds them to the General department. Rejects duplicate emails and enforces the tenant user limit.

| Name          | Type   | Required | Description                                         |
| ------------- | ------ | -------- | --------------------------------------------------- |
| `email`       | string | yes      | The new user's email — the invite link is sent here |
| `name`        | string | yes      | Display name                                        |
| `position`    | string | no       | Job title / position                                |
| `global_role` | string | no       | `admin` \| `member` \| `viewer` (default `member`)  |

**Returns:** `{ user, invite_sent:true, note, warning? }`. `user` is the linked row (`id, email, name, role, global_role, position, is_active, auth_uid`). No password is ever returned; a set-password link is emailed. `warning` appears only if the auto General-department membership step failed.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "user_create", "arguments": {
  "email": "anna@example.com", "name": "Anna Muster", "global_role": "member"
} } }
```

### `department_list`

List the tenant's departments (id, name, slug). Call before setting an agent's `department_id` — pass a listed id, never invent one.

**Parameters:** none.

**Returns:** `{ departments: [{id, name, slug}], count, note }`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "department_list", "arguments": {} } }
```

### `category_list`

List the category options (id, slug, name) for one entity type. Call before setting a category on `memory_save` / `knowledge_save` / `skill_save` — use a listed slug/name.

| Name     | Type   | Required | Description                        |
| -------- | ------ | -------- | ---------------------------------- |
| `entity` | string | yes      | `memory` \| `knowledge` \| `skill` |

**Returns:** `{ entity, categories: [{id, slug, name}], count }`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "category_list", "arguments": { "entity": "knowledge" } } }
```

### `grantable_list`

The agent toolbox: every name valid in an agent's `tools_access[]` (the capability grant list). Returns data tools (`query_`/`update_` on catalog tables), the tenant's registered MCP servers (`mcp:<id>`), vertical tools the user already has, and built-in control tools. `composio:<TOOLKIT|ACTION>` names from the user's connections are also valid. **Grant only from what exists here — never invent a tool string.**

**Parameters:** none.

**Returns:** `{ grantable: [...], count, note }`. Each entry is `{name, label, kind}` where `kind` is `data` (query\_/update\_ tools), `mcp_server` (`mcp:<id>` grants), `federated` (vertical tools), or `control` (built-in). Control entries also carry `display_name, description, category, audience`. `composio:<TOOLKIT|ACTION>` names are valid too but sourced from the user's Connections, not listed here.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "grantable_list", "arguments": {} } }
```

## Governance

### `guardrails_get`

The always-load governance rules (the "Operating Manual" layer) this caller is expected to honor: knowledge entries flagged always-load or with importance ≥ 8, currently valid, non-archived — the exact set that agent runs and the in-app chat inject automatically. MCP clients do **not** get this injected (pull-only): call once at session start and keep the rules in context. Full text via `knowledge_get`.

| Name    | Type   | Required | Description                    |
| ------- | ------ | -------- | ------------------------------ |
| `limit` | number | no       | Max rows (default 20, max 100) |

**Returns:** `{ guardrails: [...], count, note }` — same lean columns as `knowledge_search` rows (id, title, intro, category, importance, tags, scope, …), ordered by importance. Fetch full text via `knowledge_get`.

**Permissions:** read; rights-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "guardrails_get", "arguments": {} } }
```

### `self_learning_enable`

Provision (or disable) the Company-Brain self-learning harness for this tenant from built-in templates: one Brain Keeper (nightly learning sweep) + one Department Summarizer per department with data (weekly knowledge digest), including schedules and review flags. **Idempotent** — existing template agents are skipped, never duplicated. `enabled:false` is a reversible disable (schedules off, agents deactivated — never deletes).

| Name      | Type    | Required | Description                                                         |
| --------- | ------- | -------- | ------------------------------------------------------------------- |
| `enabled` | boolean | no       | `true` (default) = provision/enable; `false` = disable (reversible) |

**Returns:** `{ ok, agents, tenant_defaults, estimated_weekly_budget_usd, notes }`. `agents` is a per-agent receipt (`{action: "created"|"reactivated"|"skipped_exists"|"failed", agent_id?, template_id, reason?}`); `tenant_defaults` reports the defaults upsert action; `notes` is a human-readable summary array. `ok` is true only when no agent failed and the defaults upsert succeeded.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "self_learning_enable", "arguments": { "enabled": true } } }
```

## Credits & operations

### `credit_log_list`

Recent credit movements (kind, amount, balance before/after) for this workspace.

| Name    | Type   | Required | Description |
| ------- | ------ | -------- | ----------- |
| `limit` | number | no       | Max rows    |

**Returns:** `{ credit_logs: [{id, amount, kind, reference, balance_before, balance_after, created_at, user_id}], count }`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "credit_log_list", "arguments": { "limit": 20 } } }
```

### `failed_import_list`

Recent failed data imports (source, type, error) for this workspace.

| Name    | Type   | Required | Description |
| ------- | ------ | -------- | ----------- |
| `limit` | number | no       | Max rows    |

**Returns:** `{ failed_imports: [{id, source, type, external_id, note, error, received_at}], count }`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "failed_import_list", "arguments": { "limit": 20 } } }
```

## Platform pricing (Superadmin)

These tools operate platform-level pricing and are rejected for anyone who is not a **Superadmin**, regardless of scopes.

### `pricing_config_get`

Read the platform pricing config: plan limits (per plan key: price USD, included credits, max agents, max departments, billing price id) and top-up packages (per slug: price USD, credits, active).

**Parameters:** none.

**Returns:** `{ plan_limits: [{plan_key, price_usd, included_credits, max_agents, max_departments, updated_at}], topup_packages: [{slug, price_usd, credits, active, stripe_price_id}] }`.

**Permissions:** read; **Superadmin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "pricing_config_get", "arguments": {} } }
```

### `pricing_config_update`

Update one pricing row (partial; only supplied fields change). `kind:'plan'` patches a plan by `plan_key`; `kind:'topup'` patches a top-up package by `slug`. The billing price id is read-only.

| Name               | Type           | Required    | Description                              |
| ------------------ | -------------- | ----------- | ---------------------------------------- |
| `kind`             | string         | yes         | `plan` \| `topup`                        |
| `plan_key`         | string         | for `plan`  | Plan key                                 |
| `slug`             | string         | for `topup` | Top-up package slug                      |
| `price_usd`        | number         | no          | Plan: ≥ 0 · Topup: > 0                   |
| `included_credits` | number         | no          | Plan: integer ≥ 0                        |
| `max_agents`       | number or null | no          | Plan: agent cap; `null` = unlimited      |
| `max_departments`  | number or null | no          | Plan: department cap; `null` = unlimited |
| `credits`          | number         | no          | Topup: integer > 0                       |
| `active`           | boolean        | no          | Topup: on sale                           |

**Returns:** `{ ok:true, kind, plan_key | slug, updated }` — `updated` lists the field names actually patched. Nothing to change or a bad field → `{ error }`.

**Permissions:** write; **Superadmin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "pricing_config_update", "arguments": {
  "kind": "topup", "slug": "credits_500", "price_usd": 49, "active": true
} } }
```

### `provider_ledger_get`

Read the provider margin ledger (Merchant-of-Record accounting for white-label providers). Without arguments: every provider with its outstanding balance plus the total owed. With `provider_id`: that provider's balance, total earned, total paid out, credits sold and the 20 most recent bookings. Read-only — payouts are booked in the app.

| Name          | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `provider_id` | string | no       | Provider id; omit for all providers |

**Returns:** without `provider_id` → `{ providers: [{provider_id, name, balance_usd}], total_owed_usd }`. With `provider_id` → `{ provider_id, ...summary }` where summary carries the provider's balance, total earned, total paid out, credits sold and the 20 most recent bookings.

**Permissions:** read; **Superadmin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "provider_ledger_get", "arguments": {} } }
```