Capabilities & Grants
Capabilities are the permission model behind agent tools. Each tool declares a capability scope of the form domain:action (for example inventory:read). An assistant can only use a tool — in chat or over MCP — if its owner granted that scope.
The model
Scopes are intentionally coarse (read / write, plus a few sensitive verbs like send) so the grant UI stays manageable as domains grow. A grant lives on the assistant as a grantedScopes array and is enforced at resolve time: tools whose scope is not granted simply do not appear.
Owner-bounded (confused-deputy safe)
You can only grant scopes you yourself hold — they are bounded by your organization role and plan. Tools always execute with the owner’s identity, never the model’s, so an assistant can never exceed its owner.
Available scopes
| Scope | Grants |
|---|---|
| inventory:read | List / search catalog items, categories, tags |
| inventory:write | Create / update / delete catalog items |
| orders:read | List and read orders |
| orders:write | Update order status |
| appointments:read | List, get, availability, stats |
| appointments:write | Create / update / cancel appointments |
| contacts:read | List, search, read contacts and groups |
| contacts:write | Upsert / update / delete contacts |
| tasks:read | List tasks |
| tasks:write | Create / update tasks |
| knowledge_base:read | Semantic search, list entries, stats |
| email:send | Send email on the owner’s behalf |
The list grows as more domains are wrapped as tools. Query the live catalog below for the authoritative set.
Discover the catalog
GET https://api.cognitiondesk.com/capabilities
Authorization: Bearer <firebase-id-token>
# →
{
"domains": { "inventory": { "label": "Inventory & Catalog" }, ... },
"capabilities": [
{ "scope": "inventory:read", "domain": "inventory", "action": "read" },
{ "scope": "inventory:write", "domain": "inventory", "action": "write" },
{ "scope": "email:send", "domain": "email", "action": "send" }
]
}And the subset you are allowed to grant, given your role and plan:
GET https://api.cognitiondesk.com/capabilities/grantable
Authorization: Bearer <firebase-id-token>
# → the scopes YOU may grant (bounded by your role + plan)
{ "role": "owner", "planId": "small", "grantableScopes": ["inventory:read", "inventory:write", "email:send", ...] }Grant capabilities to an assistant
Easiest from the dashboard: Assistants → Connect via MCP → Granted capabilities. Or via the API — grants are validated against your entitlements and rejected if you exceed them:
PATCH https://api.cognitiondesk.com/assistants/<assistantId>
Authorization: Bearer <firebase-id-token>
Content-Type: application/json
{
"grantedScopes": ["inventory:read", "orders:write"],
"grantedConnectionIds": ["conn_abc123"]
}Credential grants
Tools that call an external API (REST API Connections) are gated separately by grantedConnectionIds. Grant only the connections an assistant needs; their secrets are encrypted at rest and never exposed over MCP.