Tools & policies

An agent’s tools.json, sitting next to its agent.md, grants it tools and sets a trust policy for each one.

{
  "defaultPolicy": "ask",
  "tools": [
    {
      "name": "send_email",
      "policy": "ask",
      "description": "Send an outbound email. Consequential and irreversible — always requires human approval."
    }
  ],
  "mcpServers": {}
}

Fields

Field	Type	Notes
defaultPolicy	auto | ask | deny	Applied to any tool not explicitly listed
builtins	readonly | none	Whether this agent gets read-only built-in tools
tools	array	Per-tool overrides — { name, policy, description }
mcpServers	object	External MCP servers this agent can reach (stdio | http | sse)
env	array	Env var names this agent’s tools/plugin expect (declared, not defined here)

Policies

• auto — the tool call runs immediately.
• ask — the call becomes a proposal: it’s queued, and a human approves or rejects it before anything executes. This is the default posture for anything consequential or hard to reverse.
• deny — the agent can see the tool exists but can never call it.

Approving a proposal runs the same executor action deterministically — no extra model call, no chance the approved action drifts from what was actually proposed.

Managing the proposal queue

ravel proposals list
ravel proposals approve <id>
ravel proposals reject <id>

Or use the operator console (ravel serve, or the platform’s console) to review and act on proposals as they arrive.

A tool needs a matching plugin action

If a tool comes from your team’s plugin.ts, a gated (ask) tool needs a same-named entry in the plugin’s actions — otherwise there’s nothing for an approved proposal to actually run. See Plugins.

Next

• Plugins
• Processes — where approvals ties into a process’s definition of done