> ## 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.

# Conventions

> Tool naming, session bootstrap, common parameters, errors, limits, dry-run, and router mode.

## Tool naming

Tools follow a **`namespace_verb`** convention: `agent_list`, `mission_run`, `memory_save`, `data_query`. Namespaces map 1:1 to app resources.

Older verb-first names (`list_agents`, `save_memory`, `query_data`, …) remain **permanent aliases**: `tools/call` accepts both spellings, and keys whose stored scopes carry old names keep working. `tools/list` only ever advertises the canonical names.

Federated (vertical) tools are namespaced with a double underscore: `vertical__vertical_card`, `vertical__vertical_search` (server prefix + `__` + tool name).

## Common parameters

| Parameter | Type          | Notes                                                                                                                      |
| --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string (uuid) | Row identifier. `skill_get`/`skill_save`/`skill_archive` also accept a slug.                                               |
| `limit`   | number        | Row cap. Defaults and maxima vary per tool (stated on each tool); values are clamped, never rejected.                      |
| `search`  | string        | Case-insensitive free-text term. On list tools it matches title/intro; on `data_query` it matches the view's text columns. |
| `dry_run` | boolean       | Where offered: validate and return the would-be effect **without writing** (see below).                                    |
| `confirm` | boolean       | On human-gated mission runtime controls: without `confirm:true` nothing is written and a `would` preview is returned.      |

## Session bootstrap tools

These two tools are always callable, regardless of the key's allowlist.

### `whoami`

Who am I — identity, role, tenant, departments, missions and the enabled tool surface of this credential. Call this **first** in every session.

**Parameters:** none.

**Returns:**

| Field                                               | Description                                                                 |
| --------------------------------------------------- | --------------------------------------------------------------------------- |
| `user`                                              | `{id, name, email, role, role_label, is_admin}`                             |
| `tenant`                                            | `{id, name, slug}`                                                          |
| `workspace_id`, `provider_id`                       | Workspace and (for white-label tenants) provider ids                        |
| `departments`                                       | `[{id, name}]` — your department memberships                                |
| `projects`                                          | Your visible missions with your role on each                                |
| `enabled_tools`                                     | The key's scope allowlist (canonical names)                                 |
| `available_tool_schemas`                            | Exact tool names advertised in `tools/list` for this key                    |
| `registry_version`                                  | Fingerprint of the advertised surface — if it changes, reconnect the client |
| `scope_note`, `tool_schema_note`, `guardrails_note` | Operational hints                                                           |

**Example:**

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

**Permissions:** always allowed.

### `get_context`

The Operating-Manual context block (high-importance memories + knowledge; rights-aware, token-budgeted) — the same block the in-app chat auto-injects into its system prompt. Over MCP it is **pull-only**: call once at session start, right after `whoami`.

**Parameters:**

| Name    | Type   | Required | Description                                                |
| ------- | ------ | -------- | ---------------------------------------------------------- |
| `query` | string | no       | Your current task/question — focuses the relevance ranking |

**Returns:** a formatted context block of the highest-importance entries the calling user may read.

**Example:**

```json theme={null}
{ "method": "tools/call", "params": { "name": "get_context", "arguments": { "query": "prepare the weekly sales report" } } }
```

**Permissions:** always allowed; content is rights-filtered per user.

## Errors

Responses are JSON-RPC 2.0. Application errors inside a successful tool call come back as an `{ "error": "…" }` object in the tool result; protocol/authorization errors use JSON-RPC error codes:

| Code     | HTTP | Meaning                                                                                                                              |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `-32700` | 400  | Parse error (invalid JSON body)                                                                                                      |
| `-32001` | 401  | Authorization required / invalid or expired credential (with a `WWW-Authenticate` challenge pointing at the OAuth resource metadata) |
| `-32003` | 403  | `Tool not enabled for this API key: <name>` — the tool is not on this key's allowlist                                                |
| `-32004` | 429  | Rate limit exceeded                                                                                                                  |
| `-32601` | 200  | Method not found                                                                                                                     |
| `-32602` | 200  | Invalid params (e.g. missing `params.name`)                                                                                          |
| `-32603` | 200  | Internal tool error (details are logged server-side, never leaked)                                                                   |

Database write failures are mapped to one actionable sentence plus the standard SQLSTATE class (e.g. `Insert failed (23505) — a record with these values already exists.`). Raw SQL/schema details are never returned.

## Limits

| Limit              | Value                                                                   |
| ------------------ | ----------------------------------------------------------------------- |
| Rate limit         | 60 tool calls per minute per key (default; may be tuned per deployment) |
| List/read row caps | Per tool: usually default 25–50, max 100–200 (stated on each tool)      |
| `data_query` rows  | default 25, max 200                                                     |
| Mission steps      | max 20 per mission                                                      |
| Artifact content   | default 20,000 chars, max 100,000 (`max_bytes`)                         |
| OAuth token TTL    | 30 days                                                                 |

## Dry-run

Write tools that support `dry_run:true` validate the input, resolve all references and return the **would-be effect** (e.g. a field-level `from → to` diff) without persisting anything:

`agent_update`, `agent_schedule_manage`, `memory_save`, `skill_create`, `data_row_save`, `data_row_create`, `data_row_update`.

Mission runtime controls (`mission_cancel`, `mission_pause`, `mission_resume`, `mission_budget_increase`) use the `confirm` pattern instead: calling **without** `confirm:true` returns a `would` preview; only a second call with `confirm:true` executes.

## Router mode (token-lean surface)

A key whose allowlist contains `execute_tool` is a **router key**: `tools/list` advertises only three meta-tools (plus `whoami`), and every other allowlist entry becomes an execution target. This cuts client input tokens dramatically for keys with large tool surfaces. Router mode is **opt-in per key** — it is never part of a default OAuth scope set.

### `search_tools`

Find platform tools by free-text query over name + description (AND-matched terms; empty query lists everything reachable on this key).

| Name    | Type   | Required | Description                                                     |
| ------- | ------ | -------- | --------------------------------------------------------------- |
| `query` | string | no       | Free-text terms, e.g. `"agent schedule"`; empty = all reachable |
| `limit` | number | no       | Max rows (default 10, max 25)                                   |

**Returns:** lean rows `{name, write flag, summary}`.

**Permissions:** router keys only.

### `describe_tool`

Full definition of one reachable tool: name, description and the complete `inputSchema`. Call before `execute_tool` so inputs are grounded in the real schema.

| Name   | Type   | Required | Description                   |
| ------ | ------ | -------- | ----------------------------- |
| `name` | string | yes      | Tool name from `search_tools` |

**Permissions:** router keys only.

### `execute_tool`

Execute one tool by name with the given input. Dispatches to the exact same implementation as a direct call and enforces the exact same per-key allowlist — the router can never widen a key. Router tools themselves cannot be executed (no recursion); each target still applies its own role gates.

| Name    | Type   | Required | Description                              |
| ------- | ------ | -------- | ---------------------------------------- |
| `name`  | string | yes      | Target tool name                         |
| `input` | object | no       | Arguments per the target's `inputSchema` |

**Example:**

```json theme={null}
{ "method": "tools/call", "params": { "name": "execute_tool", "arguments": { "name": "agent_list", "input": { "limit": 10 } } } }
```

**Permissions:** router keys only; write targets keep their write gates.