Agent tools and permissions

Tools determine what data your Agent can read or change, and which actions it can trigger.

Effective tool design is the main way to keep Agent behaviour safe and predictable.

Principle: least privilege

Only enable tools required for the Agent's job.

Example for a support triage Agent:

• Required: list tickets, get ticket, update ticket
• Not required: delete ticket, manage users, publish apps

Configuring tools for operations

Tools are configured at the Operation level. While Budibase automatically discovers available tools from your data sources and automations, you must explicitly enable and configure them for each operation.

Adding tools

You can add tools to an operation in two ways:

1. Rail Actions: Click the Add tools button in the Tools section of the operation rail. When you select a tool, a configuration modal will appear allowing you to set its execution principal and approval rules before it is added.
2. Editor Autocomplete: While writing instructions, type {{ and select Add tool from the autocomplete menu. This will open the configuration modal and insert the tool binding in a single step.

Execution principals

When a tool is enabled, you can configure its Run as (Execution principal) setting in the tool configuration modal. This determines the role used to access data and perform the action.

• Requester: The tool runs using the permissions of the user interacting with the Agent. This is the safest default for most user-facing tools.
• Admin (elevated): The tool runs with full administrative permissions. Use this sparingly for background tasks or strictly controlled operations.

🚀

Automations

Agents triggered via an Automation step execute as Admin by default. If a tool requires escalation, the Agent will pause and, once approved, will resume using the role of the original automation requester.

Approval rules and policies

Approval rules ensure that high-impact actions are reviewed by a human before they are executed. You can configure rules to always apply, or only apply when specific conditions are met.

Approval policies

An approval policy defines who is notified and responsible for reviewing a gated action. Policies are reusable and managed in the Approvals tab of an operation.

• Policy name: A recognisable name for the policy, shown on approval rules.
• Approval type: Determines how many responses are needed to resolve the request.
  • Any approver: Approval from any one approver is enough to proceed.
  • Unanimous: Every approver must approve before it can proceed. A single rejection will reject the request.
  • Majority: More than half of the approvers must approve to proceed.
• Approvers: A list of Budibase users responsible for reviewing and responding to the escalated request.
• Notification: The messaging channel and destination (user or channel) where the approval request will appear.
• Approval expiration: How long approvers have to respond before the approval expires. The default is 1 day. Available presets are 1 day, 3 days, 1 week, 30 days, and 90 days, subject to the limit for your Budibase plan. Enterprise plans can also use a custom duration or choose Never expires.
• What happens on expiry: Choose the automatic outcome if the approval expires before a human responds.
  • Expire: The request expires without running the tool, and the Agent tells the user that the request timed out.
  • Approve request: The request is automatically approved and the tool runs.
  • Reject request: The request is automatically rejected and the tool does not run.

Approval rules

An approval rule determines when a policy should be applied to a specific tool. Rules are configured within the tool configuration modal.

• Unconditional rules: Require approval every time the tool is called.
• Conditional rules: Only require approval if the tool's input data matches specific criteria (e.g., only escalate a create_row tool if the Total field is greater than 1000).

Sharing parameters with reviewers

To help reviewers make informed decisions without leaving their messaging app, you can select which tool parameters should be included in the notification card.

• Default behavior: No parameters are shared by default.
• Selection: Use the Shared with reviewers multiselect in the rule configuration to pick the relevant fields.
• Limits: You can share up to 40 parameters per rule.
• Context: Notifications also include the identity of the requester (the user's name and email, or the Agent name for automations) and the specific tool being used.

⚠️

Privacy and Security

Parameters are shared as plain text in Slack or MS Teams. Avoid sharing parameters that contain sensitive information like passwords or API keys unless the messaging channel is secure.

Tools with configured rules display a status indicator (e.g., "1 rule") in the operation rail.

Handling failures of approved actions

If a reviewer approves an action but the tool fails to execute (e.g. due to a validation error or database issue), the Agent will inform the user. The response will include a message such as: "Your request was approved, but I couldn't complete it. Please try again."

Detailed failure information is recorded in the Activity timeline to assist with troubleshooting.

Agent data scope

To ensure data security and optimize token usage, Budibase automatically restricts the data exposed to AI Agents.

Field exclusions

When an Agent interacts with a table, it only sees plain-text and primitive data fields. The following field types are automatically excluded from the Agent's view:

• Link fields: Relationships to other tables (joined data) are not exposed to prevent accidental data leaks
• Formula fields: Calculations and relationship-derived values are hidden from the Agent.

These exclusions apply to both the table schema (metadata) and the actual row data returned by tools.

Restricted resource access

To prevent data leaks, Budibase automatically redacts tool metadata and result data when an Agent runs as a Requester who lacks sufficient permissions for a resource (such as a table).

• Redacted Metadata: The Agent cannot see the resource's schema, field names, or specific configuration. Instead, it receives a generic tool description that prevents it from inferring the data structure.
• Redacted Results: For write operations (like creating or updating rows) on restricted resources, the tool returns a generic success message instead of the full object data to prevent unauthorized reading of records.
• Discovery Tools: Legacy discovery tools like list_tables and get_table are disabled by default. Agents should be provided with the specific tools they need for their tasks via the operation configuration.

Authoritative validation

Budibase performs server-side validation before running tools that create or update rows, trigger automations, or run REST queries. The input must match the current schema of the table, automation trigger, or REST query. Validation occurs before an approval request is created or the tool runs. If a request is approved later, Budibase validates the input again against the current schema before execution.

If a tool is redacted because the requester does not have permission to view its resource, Budibase replaces validation details with the generic Tool input is invalid message. This prevents error responses from revealing the resource schema.

Read vs write tools

Separate read and write capabilities in both tooling and instructions.

Read tools:

• Safe default
• Useful for Q&A, lookup, and summaries

Write tools:

• Higher risk
• Require explicit user intent
• Should include additional rules and testing

Permission patterns

Use one of these patterns:

1. Read-only Agent
   1. The agent can retrieve and analyse data, but cannot modify anything. This is a default starting point. It’s the safest option and ideal for validation, reporting, auditing, and insight generation.
2. Read + controlled updates
   1. The agent can read data and perform limited, explicitly scoped write operations. Writes should be constrained (e.g., specific fields, specific objects, or be behind approval workflows) and validated through tests before being enabled in production.
3. Read + updates + automation triggers
   1. The agent can read data, make approved updates, and trigger downstream workflows or automations. This pattern is suitable for more mature, production-grade use cases where the agent is trusted to take actions that may have cascading effects.

Start with read-only, then add writes only when validated by tests.

Escalation and Approvals

Approvals ensure that high-impact actions are reviewed by a human. This is configured at the tool level within the Agent operation.

Configuring recipients

To choose who gets notified when an action requires approval, you must first enable at least one messaging channel in the Agent's Deployment tab.

• Requirement: You cannot select approval recipients until a deployment (e.g., Slack, MS Teams) is configured with a valid endpoint URL.
• Provider Filtering: Only providers with active deployments will be available as options in the policy configuration.
• Channel Lookup: When selecting a channel, Budibase fetches a paginated list of available channels from your configured provider. Ensure your bot has the necessary permissions (e.g., groups:read for Slack or Channel.ReadBasic.All for Teams) to list these channels.

Guardrails for write actions

When enabling update tools, include rules like:

• Only update allowed fields.
• Never overwrite non-empty critical fields unless asked.
• Confirm target row before writing.
• Refuse destructive requests.

Tool naming and clarity

Prefer clear tool names that map directly to real entities (Tickets.Get Row, Tickets.Update Row).

Ambiguous names increase wrong-tool calls and prompt complexity.

Renaming and stability

Budibase automatically maintains connections between your Agents and their tools. If you rename a Datasource, REST API, or Query, Budibase will automatically update:

1. Any references to that tool in Agent prompt instructions.
2. The enabled tools list for all affected Agents.

This ensures that reorganizing your data or APIs does not break your existing Agent configurations.

Naming constraints

To ensure compatibility with AI providers (like OpenAI), tool names are subject to a 64-character limit.

Budibase uses stable, unique identifiers for tool bindings to ensure they remain consistent even if labels are long or names change. If a tool name derived from an entity name (like a table or query) is exceptionally long, Budibase may use a shortened version with a unique suffix to prevent collisions and stay within provider limits.

Keep table and query names reasonably concise to ensure tool names remain human-readable for the Agent and in activity logs.

Checklist before enabling a tool

• Is this tool essential for the Agent's task?
• What is the worst-case outcome if it is misused?
• Do instructions define when it can be used?
• Is the tool covered by tests?

Related guides

• Agent instructions guide
• Agent testing guide
• Agent troubleshooting guide