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
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:
- Read-only Agent
- 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.
- Read + controlled updates
- The agent can read data and perform limited, explicitly scoped write operations. Writes should be constrained (e.g., specific fields, specific objects, or behind approval workflows) and validated through tests before being enabled in production.
- Read + updates + automation triggers
- 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.
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:
- Any references to that tool in Agent prompt instructions.
- 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.
If a tool name derived from an entity name (like a table or query) exceeds this limit, Budibase automatically truncates the name and appends a unique hash to prevent collisions. For example, a tool for a very long table name might appear as VeryLongTableName_a1b2c3d4e5f6_get_row instead of the full name.
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 this tool covered by tests?
Related guides
Updated 12 days ago