Tools
The server exposes 53 tools over ten resources. Each one mirrors a /v1 endpoint and dispatches to it in-process, so the behaviour — filters, upsert matching, validation, soft-delete, workspace isolation — is identical to the REST API.
How to read these pages
Every tool is documented with the same header line:
Read · scope
inbox/emails· permissionemails.show·GET /emails/{id}
| Field | Meaning |
|---|---|
| Read / Write / Destructive | The annotation the client sees. A destructive tool deletes data, sends something outside (a webhook test or replay, an agent re-run that may reply or act), rotates a secret or changes who may send to an inbox. It runs only after the server asks the user to confirm it, which needs protocol 2026-07-28 with elicitation; any other client gets confirmation_required — see Confirming destructive tools. |
| scope | What the connected client's token must reach. A write needs the resource scope and the global write verb — or the write/all access level, within the token's resources. See Scopes. |
| permission | What the person behind the token must hold in the organization. |
The METHOD /path | The /v1 endpoint the tool dispatches to, for cross-reference with the API reference. |
Parameters marked required must be present; everything else is optional. A tool you cannot run is not listed by tools/list at all. Read tools also back the resources under kobana://inbox/.
Common parameters
These appear across many tools and always mean the same thing.
| Parameter | Type | Description |
|---|---|---|
cursor | string | Opaque cursor from a previous page (meta.next_cursor). |
limit | integer | Page size, default 25, max 100. |
sort | string | Comma-separated sort keys, - prefix for descending (e.g. -created_at). |
idempotency_key | string | Replay guard, 8–255 chars, sent as X-Idempotency-Key. Same key within 24h returns the original response. |
custom_metadata | object | Free-form JSON owned by you; echoed on every read and webhook payload. |
<field>_gte / <field>_lte | string | ISO 8601 range filter on that field. |
The catalogue
| Resource | Tools | Read scope |
|---|---|---|
| Workspaces | 6 | inbox/workspaces |
| Inboxes | 8 | inbox/inboxes |
| E-mails | 5 | inbox/emails |
| Agents | 8 | inbox/agents |
| Agent runs and usage | 4 | inbox/agent_runs, inbox/usage |
| Webhooks | 11 | inbox/webhooks |
| System events | 2 | inbox/system_events |
| Secrets | 6 | inbox/secrets |
| Workflow runs | 2 | inbox/workflow_runs |
| Identity | 1 | none (any token) |
| Tool | Resource | Kind |
|---|---|---|
me | Identity | read |
workspaces_list workspaces_get | Workspaces | read |
workspaces_create workspaces_upsert workspaces_update | Workspaces | write |
workspaces_delete | Workspaces | destructive |
inboxes_list inboxes_get | Inboxes | read |
inboxes_create inboxes_upsert inboxes_update | Inboxes | write |
inboxes_delete inboxes_add_recipient inboxes_remove_recipient | Inboxes | destructive |
emails_list emails_get emails_download_eml | E-mails | read |
emails_reprocess emails_delete | E-mails | destructive |
agents_list agents_get agents_versions_list models_list | Agents | read |
agents_create agents_upsert agents_update | Agents | write |
agents_delete | Agents | destructive |
agent_runs_list agent_runs_get usage_summary usage_cost | Agent runs | read |
webhooks_list webhooks_get webhooks_deliveries_list webhooks_deliveries_get | Webhooks | read |
webhooks_create webhooks_upsert webhooks_update | Webhooks | write |
webhooks_delete webhooks_test webhooks_regenerate_secret webhooks_deliveries_replay | Webhooks | destructive |
system_events_list system_events_get | System events | read |