Capability
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.
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
You can register capabilities in two ways:
Via the decorator (recommended):
@runtime.capability(
name="execute_sql",
type="database",
risk="high",
data_namespace="customer.records",
)
def execute_sql(query: str):
return {"rows": []}Via the registry (for capabilities without a backing Python function, or for pre-registration):
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. See types table below. |
| 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 (dev, staging, 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 (JSON Schema). 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—Trueifriskis"high"or"critical"has_side_effects—Trueifside_effectsis non-emptydisableable_side_effects— list of side effects withcan_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 (the server itself 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 risklow— read-only, reversible, internal onlymedium— writes to internal state or reads external datahigh— external writes, financial actions, credential access, irreversible changescritical— destructive, broadly scoped, or impossible to audit after the fact
Risk is a metadata field. 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:
# Flat
"refund_customer"
"execute_sql"
# Namespaced
"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.