> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brane.membranelabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Capability

> A capability is anything an agent can use.

A capability is anything an agent can use. Not just tools: the governed object in the control loop.

## Definition

A capability is any resource an agent can use. The mental shift from the conventional "tool" framing is intentional: capabilities include tools, models, memory, databases, MCP servers, sandboxes, secrets, and other agents. Everything that can cause a consequence is a governed capability.

Without capabilities, an agent calls code. With capabilities, the runtime knows what is behind the door: the risk, the effect, the side effects, the required scopes, the tenant, the environment, and the data namespace. That metadata is what makes policy possible.

```python theme={null}
from brane import Capability, Effect

refund_cap = Capability(
    name="refund_customer",
    type="tool",
    risk="high",
    effect=Effect(type="financial", reversible=False, external=True),
    data_namespace="billing.refunds",
    owner="payments-team",
)
```

## Registering Capabilities

Register capabilities with the decorator:

```python theme={null}
@runtime.capability(
    name="execute_sql",
    type="database",
    risk="high",
    data_namespace="customer.records",
)
def execute_sql(query: str):
    return {"rows": []}
```

Or register a capability directly:

```python theme={null}
runtime.register_capability(Capability(
    name="mcp.github.create_pr",
    type="mcp_tool",
    risk="medium",
    owner="platform-team",
))
```

## Fields

| Field            | Type               | Description                                                          |                                                              |
| ---------------- | ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------ |
| `name`           | `str`              | Unique identifier for the capability.                                |                                                              |
| `type`           | `str`              | Category of capability.                                              |                                                              |
| `risk`           | `str`              | Risk classification: `none`, `low`, `medium`, `high`, or `critical`. |                                                              |
| `effect`         | `Effect`           | Primary expected outcome of using this capability.                   |                                                              |
| `side_effects`   | `list[SideEffect]` | Secondary consequences. May be disableable.                          |                                                              |
| `scopes`         | `list[Scope]`      | Required scopes. Used by `ctx.agent_has_scope()`.                    |                                                              |
| `tenant_id`      | \`str              | None\`                                                               | Tenant constraint for multi-tenant deployments.              |
| `environment`    | \`str              | None\`                                                               | Environment constraint, such as `dev`, `staging`, or `prod`. |
| `data_namespace` | \`str              | None\`                                                               | Data classification namespace.                               |
| `owner`          | \`str              | None\`                                                               | Owning team or service.                                      |
| `description`    | \`str              | None\`                                                               | Human-readable description.                                  |
| `input_schema`   | \`dict             | None\`                                                               | Expected input shape. Schema validation is planned.          |
| `output_schema`  | \`dict             | None\`                                                               | Expected output shape. Schema validation is planned.         |
| `metadata`       | `dict`             | Arbitrary metadata for policy use.                                   |                                                              |

## Computed Properties

* `is_high_risk`: `True` if `risk` is `high` or `critical`
* `has_side_effects`: `True` if `side_effects` is non-empty
* `disableable_side_effects`: list of side effects with `can_disable=True`

## Capability Types

| Type             | Description                               |
| ---------------- | ----------------------------------------- |
| `tool`           | Generic tool call. Custom business logic. |
| `model`          | LLM or embedding model call.              |
| `memory`         | Agent memory read or write.               |
| `retrieval`      | Vector or semantic search.                |
| `database`       | Database query.                           |
| `external_api`   | External HTTP API call.                   |
| `mcp_server`     | MCP server as a resource.                 |
| `mcp_tool`       | Specific MCP tool.                        |
| `mcp_resource`   | MCP resource read.                        |
| `mcp_prompt`     | MCP prompt template.                      |
| `sandbox`        | Code execution sandbox.                   |
| `filesystem`     | File read or write.                       |
| `secret`         | Credential or secret access.              |
| `approval_group` | Human approval workflow.                  |
| `agent`          | Another agent for handoffs.               |
| `workflow`       | Workflow trigger.                         |

## Risk Levels

* `none`: no meaningful risk
* `low`: read-only, reversible, internal only
* `medium`: writes to internal state or reads external data
* `high`: external writes, financial actions, credential access, irreversible changes
* `critical`: destructive, broadly scoped, or impossible to audit after the fact

Risk is metadata. It does not enforce anything by itself. Policies use `ctx.is_high_risk` to enforce behavior.

## Naming Conventions

Flat strings work. Namespaced names are recommended for complex deployments:

```text theme={null}
refund_customer
execute_sql
tool.refund_customer
database.customer_readonly
mcp.github.create_pr
secret.stripe_api_key
agent.billing_specialist
sandbox.python_network_off
```

The wildcard policy target `"*"` matches all capabilities regardless of naming.

## Why Not Just Tools

Tool is only one capability type. Model calls consume budget, affect quality, and route to different providers. Memory writes can poison future context. Secrets, if misused, expose credentials. MCP servers expose entire action surfaces.

Treating all of these as capabilities gives the same policy runtime governance over the entire agent action surface, not just the tools the developer explicitly thought about.