OpenPlaybook

Tools & capabilities

A step declares the tools it is allowed to call; it never imports them. That allow-list is the step's capability boundary, and a conforming runtime honors it as one.

The allowedTools list

On an agent step, allowedTools is a list of tool names. A name resolves against the document's own embedded tools array and the runtime's tool registry; a call to any name not on the executing step's list is refused.

an agent step declaring tools

{
  "id": "recover",
  "kind": "agent",
  "agent": "lou",
  "purpose": "Draft a recovery email for the failed charge and record the attempt.",
  "allowedTools": [
    "customer.get",
    "charge.history",
    "mcp.acme.search_orders"
  ],
  "next": "gate"
}

Three naming families cover the surface:

Built-in tools, plain names over the runtime's primitives: customer.get, today.surface.
Connector tools, named by the provider's tool set: charge.history from the Stripe connector, and kin, documented per provider.
MCP tools, composed as mcp.<server>.<tool> where <server> is a logical name the document declares in requires.mcpServers. The name is a local handle: never a URL, never auth material.

Embedded tool definitions

A document carries the definitions of the tools it references in its tools array, so a foreign reader can explain what the playbook does without any registry. Each entry:

namestring · required
sourceenum · required
primitiveconnectormcp
descriptionstring · required
permissionsarray · required
inputSchemaobject · required
outputSchemaobject · required
harnessInputSchemaunknown
harnessOutputSchemaunknown
dataScopeResourcesarray
dataScopeWritesarray
requiresApprovalboolean
riskClassenum
readinternalcustomer_commsmoney
sideEffectingboolean
connectorTypeenum
stripegithubvercelposthoggmailresendlinearslacknotionmercurysquareplaidshopifyrampcloverbrexstripe_financial_connectionstellerpaypaletsyamazongusto
scopeenum
appworkspace

Read tools declare sideEffecting: false and never require approval; write tools declare their side effects and may require an approval gate. A runtime importing a document checks the embedded definitions against its own registry and flags drift.

The requires declaration

The envelope's requires block is the machine-readable statement of what a harness must satisfy before the playbook can run: provider connections, MCP servers by logical name, and named secrets. Names and purposes only; never credentials.

connectionsarray · required
The machine-readable credential declaration — one entry per manifest.requiredConnectors member.
connections[].providerenum · required
The connector this connection is for.
stripegithubvercelposthoggmailresendlinearslacknotionmercurysquareplaidshopifyrampcloverbrexstripe_financial_connectionstellerpaypaletsyamazongusto
connections[].authKindenum · required
How this connector authenticates.
oauthapi_tokenaggregator_link
connections[].scopesarray
Best-effort OAuth scopes to request; [] where the provider has no scopes concept.
connections[].capabilitiesarray
Embedded tool names this playbook uses from this provider.
mcpServersarray
MCP servers this playbook's mcp.<name>.<tool> tool names require — logical names + tool names, never URLs or auth. [] on pre-1.6 documents.
mcpServers[].namestring · required
Logical MCP server name — the local handle tool names compose from (mcp.<name>.<tool>). Never a URL and never auth material.
mcpServers[].toolNamesarray
The mcp.<name>.* tool names this playbook references from this server.
mcpServers[].capabilitiesarray
Reserved best-effort capability hints; empty today.
secretsarray
Named secrets this playbook's bindings reference — names + purposes only, never values. [] on pre-1.6 documents.
secrets[].namestring · required
The named secret this playbook's bindings reference — the name only, never a value.
secrets[].purposestring · required
Human-readable reason the secret is needed (e.g. auth for MCP server "acme").

Future direction

A richer per-reference object form, carrying a kind discriminator, declared operations for credit pricing, and skill:// references to SKILL.md procedural knowledge, is planned direction for a future OpenPlaybook version. It is not part of the current wire format: today's documents declare tool names, and the current schemas are the contract. Track the evolution in the spec repository's RFC process.