Require approval before a tool runs

Use this for tools whose effect is hard to undo, such as posting in public. You need an integration that offers the tool. If you don't have one, see Give stations a tool from an HTTP API.

Add an approval to the toolCopy Anchor Link

In the integration's definition, give the tool an approval with because: the reason a person reads before they decide.

tools = {
  comment = {
    does        = "comment"
    description = "Comment on the issue."
    inputs = {
      issue = { type = "string", required = true }
      body  = { type = "string", required = true }
    }
    approval = {
      because = "It posts publicly, under the team's name."
    }
  }
}

The agent says what it would like to do in its own words when it calls the tool, working from the tool's description and because. Write both so that a person reading that sentence knows what the call does and why it waits for them.

Don't give the tool an input named intent. Spotlight keeps that name for the agent's sentence, and refuses the integration otherwise.

Run terraform apply.

Tools generated from an API descriptionCopy Anchor Link

Tools that an integration generates from an API description already wait for approval when they change data: every OpenAPI POST, PUT, PATCH and DELETE operation, and every GraphQL mutation. The reason a person reads is It changes data in <name>., with the integration's name.

To change that for one tool, add it under the block's tools.approval, by its generated name. Give because for another reason, which also makes a tool that only reads wait. Give false for a tool that should run without asking:

openapi = {
  url     = "https://petstore3.swagger.io/api/v3/openapi.json"
  baseUrl = "https://petstore3.swagger.io/api/v3"
  tools = {
    approval = {
      "delete-pet" = { because = "It deletes a pet for good." }
      "update-pet" = false
    }
  }
}

Tools from a remote MCP server wait for approval unless the server marks them as only reading. Change one the same way, under the mcp block's tools.approval.

If the apply warns that it passes over an operation because it takes intent, that operation needs approval and has an input with the name Spotlight keeps for the agent's sentence. Set its approval to false to offer it, or leave it out.

Run terraform apply.

Let a person ask first or block a toolCopy Anchor Link

Where an integration acts as the person who started the task (its connection.holder is requester), each person can choose what to ask of calls made with their own connection. Open Settings, then Integrations under the team's name, and open an integration you have connected. Under Acting as you, pick a rule for each tool:

• Allow: follow the team. This is the default.
• Ask me first: wait for your approval.
• Block: never run.

The stricter of the team's rule and yours applies, and only to calls made with your own connection. When a call waits because you chose Ask me first, the task is put to you, and only you can approve the call. See Person rules for each combination. To set rules over the API, see OAuth connect and callback.

Approve, edit or dismiss each callCopy Anchor Link

When an agent calls the tool, nothing is sent: the task's inbox item shows what the agent would like to do and the call itself, with Approve and Dismiss. A person can change the call's inputs before approving it. The work resumes once someone decides. See Answer the inbox.

If agents should ask before commands or file changes instead of tool calls, use a harness profile's ask rules. See Limit what agents may do.

RelatedCopy Anchor Link

• spotlight_integration, for the approval field.
• Approvals: the rules an approval follows.
• Asking a person