Approval behavior

The Tools view reports approval metadata, but approvals are resolved in the Playground. Keeping those responsibilities separate prevents a dangerous assumption: an approval badge in the registry does not make direct invocation safe.

What the Tools registry can discover

When a tool declares requiresApproval, Studio marks it required:

const issueRefund = createTool({
  name: 'issue_refund',
  description: 'Issue a customer refund.',
  inputSchema: z.object({
    orderId: z.string(),
    amount: z.number().positive(),
    reason: z.string(),
  }),
  outputSchema: z.object({
    refundId: z.string(),
    status: z.literal('issued'),
  }),
  requiresApproval: ({ orderId, amount }) =>
    amount > 0
      ? { reason: `Review refund of $${amount} for order ${orderId}.` }
      : false,
  execute: issueRefundHandler,
})

The table can identify that an approval requirement exists. A fixed string reason can also be exposed as metadata. A function-valued reason depends on parsed arguments, so Studio evaluates and displays it only when the agent actually requests approval during a Playground run.

The badge means this tool can require approval, not every possible call will pause. The callback decides that from parsed input at runtime.

Registry, runner, and Playground

Surface	Purpose	Approval behavior
Tools registry	Inspect definitions and policy metadata.	Shows required when a tool declares a policy.
Tools runner	Invoke a chosen handler with manual arguments.	Executes directly; it does not create an approval request.
Playground	Run the agent through its prompt lifecycle.	Pauses a guarded call and presents Approve and Reject.

The direct runner bypasses declarative tool approval. Never use it as evidence that an approval requirement is correctly enforced. It is also capable of performing the underlying side effect immediately.

What happens in the Playground

For a guarded agent tool call, Studio records the run, agent, tool, raw arguments, request time, and approval reason. Execution waits until the operator responds:

• Approve resumes the same tool call and lets the handler execute.
• Reject resolves the tool call as denied and records the operator reason.
• stopping the run changes a pending approval to cancelled and resolves it as denied.

A resolved approval cannot be decided twice. These requests live inside the Studio process and are intended for development workflows, not as a durable production approval queue.

Test both layers

Use a two-part check for guarded tools:

1. In Tools, run safe inputs against a development dependency to validate the input/output contract and handler behavior.
2. In Playground, prompt the agent to propose the guarded action, verify the generated reason and arguments, then exercise both approval and rejection.

This separates handler debugging from orchestration testing without confusing one for the other. See Approvals and questions for the complete interactive flow, or return to the Tools overview.