Agent Capabilities

MITRITY's capabilities system grants per-agent access to specific tools with explicit operations, scopes, rate limits, and time windows. Capabilities sit on the agent detail page (under Agents → [Agent Name] → Capabilities) and are a complementary defense-in-depth layer alongside policies.

Capabilities and policies are not equivalent. Capabilities narrow what an agent can attempt; policies evaluate the actions the agent does attempt. Use both.

How capabilities interact with policy rules

This is the mental model the dashboard surfaces, and it is the one to internalize:

Capabilities narrow what an agent can attempt. When capabilities are configured for an agent, tool calls that aren't covered by a capability are denied before policy evaluation runs.
With no capabilities configured, all tool calls fall through to policy rules. Policies become the sole authorization surface for that agent.
Adding capabilities enforces a tighter, capability-based surface. It does not replace policy rules — policies still run for any tool call a capability allows. A capability granting read on tool_crm_8k2m doesn't override a policy that denies CRM reads outside business hours.

In short: capabilities decide which tools are even in scope; policies decide what's actually allowed each time. Both must say "yes" for a tool call to proceed.

Capabilities	Behavior
None configured	Every tool call falls through to policy rules. Policies are the sole authorization surface.
At least one configured	Tool calls not covered by any capability are denied. Calls covered by a capability proceed to policy evaluation.

Overview

A capability links three concepts:

Agent — The AI agent performing actions
Tool — A tool from the tool catalog
Capability — The grant, with operations and constraints

Each capability specifies:

Operations: Which operations are permitted (read, write, delete, etc.)
Scopes: Fine-grained resource access within the tool
Rate limits: Maximum actions per time window
Payload limits: Maximum request size in bytes
Time windows: When the capability is active
Enabled flag: Toggle the capability off without deleting it

Operations

Operations define what the agent can do with the tool. Available operations depend on the tool definition in the catalog.

Operation	Description
`read`	Retrieve data (SELECT, GET, download)
`write`	Create or update data (INSERT, UPDATE, PUT, POST, upload)
`delete`	Remove data (DELETE, DROP, remove)
`list`	Enumerate resources (list tables, list buckets, directory listing)
`execute`	Run code or invoke functions (stored procedures, lambdas, code execution)
`send`	Send messages or notifications (email, chat, SMS)

Operation filtering

Grant only the operations the agent needs:

{
  "agent_id": "agt_analytics-bot",
  "tool_id": "tool_postgres_builtin",
  "allowed_operations": ["read", "list"]
}

This grants the analytics bot read-only access to PostgreSQL. Any write, delete, or execute operations are denied at the capability layer before policies even run.

Rate limits

Rate limits restrict how frequently an agent can use a tool. This prevents runaway agents from overwhelming resources and provides a safety net against infinite loops.

{
  "agent_id": "agt_sales-bot",
  "tool_id": "tool_crm_8k2m",
  "allowed_operations": ["read", "write", "list"],
  "rate_limit": {
    "max_per_minute": 60,
    "burst": 10
  }
}

Rate limit fields

Field	Type	Description
`max_per_minute`	integer	Maximum number of actions per minute. Range: 1-10000.
`burst`	integer	Maximum number of concurrent actions. When exceeded, new actions are queued or denied. Range: 1-1000.

When the rate limit is exceeded, the gateway returns a 429 Too Many Requests error to the agent with a Retry-After header.

Rate limit recommendations

Tool category	Recommended rate	Burst
Database	100-500/min	20
LLM	30-60/min	5
Email/SMS	10-30/min	3
Code execution	10-20/min	2
Storage	100-300/min	20
HTTP outbound	60-200/min	10

Payload limits

Payload limits restrict the size of data an agent can send in a single request. This prevents agents from exfiltrating large datasets or overwhelming downstream services.

{
  "agent_id": "agt_data-bot",
  "tool_id": "tool_s3_builtin",
  "allowed_operations": ["read", "write"],
  "max_payload_bytes": 10485760
}

Field	Type	Description
`max_payload_bytes`	integer	Maximum request body size in bytes. Default: no limit.

Common sizes:

Size	Bytes	Use case
1 KB	1024	Simple API calls, JSON payloads
1 MB	1048576	Standard file uploads, data exports
10 MB	10485760	Large file operations
100 MB	104857600	Bulk data transfers

Time windows

Time windows restrict tool access to specific hours. Actions outside the time window are denied.

{
  "agent_id": "agt_batch-processor",
  "tool_id": "tool_postgres_builtin",
  "allowed_operations": ["read", "write", "execute"],
  "time_window": {
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "start": "02:00",
    "end": "06:00",
    "timezone": "Europe/Stockholm"
  }
}

Time window fields

Field	Type	Description
`days`	array	Days of the week the window is active. Values: `monday` through `sunday`.
`start`	string	Start time in 24-hour format (HH:MM).
`end`	string	End time in 24-hour format (HH:MM).
`timezone`	string	IANA timezone (e.g., `Europe/Stockholm`, `America/New_York`, `UTC`).

Spanning midnight

To create a window that spans midnight (e.g., 22:00 to 06:00), set the end time before the start time:

{
  "time_window": {
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "start": "22:00",
    "end": "06:00",
    "timezone": "Europe/Stockholm"
  }
}

Scopes

Scopes provide fine-grained resource access within a tool. Instead of granting access to all resources within a tool, scopes limit access to specific tables, buckets, paths, or endpoints.

{
  "agent_id": "agt_analytics-bot",
  "tool_id": "tool_postgres_builtin",
  "allowed_operations": ["read"],
  "allowed_scopes": [
    "public.analytics_*",
    "public.reports_*"
  ]
}

Scope pattern examples

Tool	Scope pattern	Matches
PostgreSQL	`public.users`	Only the `users` table in the `public` schema
PostgreSQL	`public.analytics_*`	All tables starting with `analytics_`
S3	`my-bucket/reports/*`	Objects in the `reports/` prefix
S3	`my-bucket/exports/*.csv`	Only CSV files in the `exports/` prefix
GitHub	`org/repo-*`	Repositories matching `repo-*` in the org
HTTP	`https://api.internal.com/v1/*`	Only v1 API endpoints

Managing capabilities in the dashboard

Capabilities are managed inline on the agent detail page.

View an agent's capabilities

Navigate to Agents → [Agent Name] and scroll to the Capabilities section. Each row shows the tool, the granted operations, scopes, rate limit, and whether the capability is enabled.

Add a capability

Click Add capability in the Capabilities section header. The dialog asks for:

Tool — Pick from the tools available to your tenant in the tool catalog
Operations — Multi-select; at least one is required
Scopes — Optional resource patterns
Rate limit — Optional per-minute cap

The capability is created immediately on save and propagates to connected edge nodes within seconds.

Edit a capability

Click Edit in the row's Actions column to modify operations, scopes, or rate limit. Changes take effect immediately — the gateway receives updated capabilities via the heartbeat channel.

Remove a capability

Click Remove in the row's Actions column. The dashboard asks for confirmation, then deletes the capability. After removal, the agent loses that grant; if no capabilities remain for the agent, the agent reverts to the pure policy-rules surface (all tool calls fall through to policy evaluation).

API reference

The capability endpoints continue to use the legacy /permissions path on the MITRITY backend.

List an agent's capabilities

curl https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions/ \
  -H "Authorization: Bearer mk_your-api-key"

Response:

{
  "data": [
    {
      "id": "perm_8k2m4n",
      "agent_id": "agt_sales-bot",
      "tool_id": "tool_crm_8k2m",
      "tool_name": "internal-crm-api",
      "allowed_operations": ["read", "list"],
      "allowed_scopes": [],
      "rate_limit_per_minute": 60,
      "max_payload_bytes": null,
      "time_window": null,
      "enabled": true,
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_perm001",
    "timestamp": "2026-03-01T10:05:00Z",
    "next_cursor": null,
    "total": 1
  }
}

Upsert capabilities

The PUT endpoint is upsert-only — it creates new capabilities and updates existing ones (matched by tool_id), but does not remove capabilities for tools omitted from the body. Use the DELETE endpoint for removal.

curl -X PUT https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions/ \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "tool_id": "tool_crm_8k2m",
      "allowed_operations": ["read", "write", "list"],
      "rate_limit_per_minute": 120,
      "max_payload_bytes": 1048576,
      "allowed_scopes": ["contacts/*", "deals/*"]
    },
    {
      "tool_id": "tool_sendgrid_builtin",
      "allowed_operations": ["send"],
      "rate_limit_per_minute": 10
    }
  ]'

Delete a capability

Remove a single capability by its permission_id. The endpoint is scoped to (tenant, agent, permission_id) — a capability that doesn't belong to the calling tenant returns 404 without leaking existence across tenant boundaries.

curl -X DELETE https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions/perm_8k2m4n \
  -H "Authorization: Bearer mk_your-api-key"

Status codes:

Code	Meaning
`204 No Content`	Capability removed.
`403 Forbidden`	The caller's role is `viewer` (or otherwise lacks write access to agents).
`404 Not Found`	No capability with this `permission_id` exists for this agent within the tenant.

After deletion, the agent's effective surface shrinks: subsequent tool calls matching the removed tool are denied at the capability layer (assuming at least one capability remains) or fall through to policy rules (if no capabilities remain).

Evaluation flow

When the gateway intercepts an agent's tool call, it walks two layers:

Agent tool call
    │
    ▼
Capabilities configured for this agent? ──No──► Policy evaluation
    │ Yes
    ▼
Tool covered by an enabled capability? ──No──► DENIED (capability)
    │ Yes
    ▼
Operation in the capability's allowed_operations? ──No──► DENIED (capability)
    │ Yes
    ▼
Scope, rate, payload, time-window checks pass? ──No──► DENIED (capability)
    │ Yes
    ▼
Policy evaluation
    │
    ├── allow ──► Action proceeds
    ├── hold ──► Awaits human approval
    └── deny ──► DENIED (policy)

Both layers must say yes. A capability that allows read on a tool doesn't override a policy that denies that read; a policy that allows a tool doesn't override a capability that omits it.

Best practices

Decide deliberately whether to use capabilities

Capabilities are optional. Many small deployments run on policy rules alone and that's fine. Add capabilities when you want a tighter, capability-based surface that prevents an agent from even attempting most tools — useful for agents with narrow mission scopes (e.g., a single-purpose data-fetcher that should only ever touch one database).

Start with read-only

When onboarding a new agent, start with read-only capabilities and expand as needed. This lets you observe the agent's behavior before granting write access.

Set rate limits on all capabilities

Even for trusted agents, set rate limits as a safety net. An agent stuck in a loop can generate thousands of requests per minute without rate limits.

Use scopes for sensitive data

Instead of granting broad database access, use scopes to limit access to specific tables. An analytics agent should not need access to the users or credentials tables.

Review capabilities regularly

Set a quarterly review cadence for agent capabilities. Remove capabilities for tools that are no longer used and tighten scopes based on actual usage patterns.

Document time windows

When using time windows, document the rationale. A future team member seeing a 02:00-06:00 window needs to understand it is for batch processing, not an arbitrary restriction.