Skip to main content

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.

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

Register capabilities with the decorator: 
@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

FieldTypeDescription
namestrUnique identifier for the capability.
typestrCategory of capability.
riskstrRisk classification: none, low, medium, high, or critical.
effectEffectPrimary expected outcome of using this capability.
side_effectslist[SideEffect]Secondary consequences. May be disableable.
scopeslist[Scope]Required scopes. Used by ctx.agent_has_scope().
tenant_id`strNone`Tenant constraint for multi-tenant deployments.
environment`strNone`Environment constraint, such as dev, staging, or prod.
data_namespace`strNone`Data classification namespace.
owner`strNone`Owning team or service.
description`strNone`Human-readable description.
input_schema`dictNone`Expected input shape. Schema validation is planned.
output_schema`dictNone`Expected output shape. Schema validation is planned.
metadatadictArbitrary 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

TypeDescription
toolGeneric tool call. Custom business logic.
modelLLM or embedding model call.
memoryAgent memory read or write.
retrievalVector or semantic search.
databaseDatabase query.
external_apiExternal HTTP API call.
mcp_serverMCP server as a resource.
mcp_toolSpecific MCP tool.
mcp_resourceMCP resource read.
mcp_promptMCP prompt template.
sandboxCode execution sandbox.
filesystemFile read or write.
secretCredential or secret access.
approval_groupHuman approval workflow.
agentAnother agent for handoffs.
workflowWorkflow 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.