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

@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:

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:

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.

Start Here

Core Model

Answer Guides

Build With Python

Recipes

Reference

Definition

Registering Capabilities

Fields

Computed Properties

Capability Types

Risk Levels

Naming Conventions

Why Not Just Tools

​Definition

​Registering Capabilities

​Fields

​Computed Properties

​Capability Types

​Risk Levels

​Naming Conventions

​Why Not Just Tools

Definition

Registering Capabilities

Fields

Computed Properties

Capability Types

Risk Levels

Naming Conventions

Why Not Just Tools