> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent & Tools

> How the agent works: effects, permission modes, approvals, and the tools it acts through.

The Datalooma agent works on your organization's data. A wrong change there is quiet and expensive, so the agent is built around one idea: reads are cheap, and anything that changes state has to earn its way through.

## Tools

The agent acts only through tools. It can:

* **Query data**: run SQL against your [connections](/docs/foundations/plugins-and-connections.md) and read table and column schemas.
* **Work with files and code**: read and edit files in the workspace and run shell commands on its [machine](/docs/workspaces/machines.md).
* **Build notebooks**: create and edit [notebooks](/docs/notebooks/overview.md), run cells, and show outputs in the chat.
* **Use knowledge**: search and read the [knowledge base](/docs/foundations/knowledge-base.md), and record what it learns.
* **Use lineage**: trace how an asset is produced and what depends on it with [lineage](/docs/foundations/lineage.md).

Every tool call is classified by its [effect](#effects) and passes the same [permission gate](#permission-modes), so the rules below hold whether the agent is running SQL, a shell command, or a notebook cell.

## Effects

Every action is classified by its effect before it runs. When the agent asks for approval, the card tells you which effect it has.

| Effect | Meaning | Examples |
| - | - | - |
| **Read** | Only reads files or data | `SELECT`, `ls`, reading a schema |
| **Write** | May change files or data | Editing a file, `INSERT`, `UPDATE` with a `WHERE` |
| **Destroy** | May delete files or data | `rm`, `DELETE`, `DROP TABLE` |
| **Egress** | May send or fetch data over the network | Fetching a URL, copying data to an external stage |
| **Exec** | May run programs on the database server | Calling a stored procedure |
| **Memory** | May change what the agent remembers | Recording a knowledge entry |

SQL is parsed into a syntax tree, so the effect is taken from every statement in it. A `DELETE` hidden inside a CTE is still a delete. Shell commands are parsed the same way, including pipelines and subshells.

## Permission modes

The mode decides what happens when the agent reaches an action that is not a read. Pick it in the composer, or press <kbd>Shift</kbd> + <kbd>Tab</kbd> to cycle.

| Mode | Behavior |
| - | - |
| **Read-only** | Reads freely, writes only in this chat, and runs no shell. |
| **Plan** | Explores, writes only in the chat's files, and proposes a plan for you to approve. |
| **Default** | Runs reads freely and asks before changes outside the chat's files. |
| **Auto** | Works on its own and pauses only for risky or destructive steps. |
| **Bypass permissions** | Runs everything without asking. Opt in deliberately. |

Your starting mode for new chats is your saved default. Only people who can edit a chat can change its mode.

## Approving actions

When the agent is gated, it shows an approval card with what it wants to do and why. You can:

* **Allow once**: run it this time.
* **Reject once**: refuse it this time. The agent adapts and continues.
* **Always allow**: save a rule so the same kind of action passes next time.
* **Always reject**: save a rule so it is refused next time.

"Always" rules are deliberately narrow:

* For most shell commands, a rule covers the command family. Allowing `ls -la` also allows `ls src`.
* A destructive command is remembered only as its exact text, offered as **Always allow this exact command**.
* No standing rule is offered for commands whose meaning depends on what they expand to when they run.
* Rules apply to the mode you answered in, and belong to you. Only the chat's owner can save one.

## Large results

A query that returns thousands of rows should not be pasted into a conversation. It would cost a fortune in tokens, bury the reasoning, and force the agent to read numbers one by one.

So when a result is larger than 50 rows or 64 KiB, Datalooma stores it as a **result** and gives the agent a handle and a small preview. The agent can check its shape and columns, profile it, filter and sort it, and run read-only SQL over it in place. Querying a large result can produce a smaller one, so the agent can narrow a result step by step.

Open **Results** in the chat to see every result it produced. Each one pages through the full data and can be downloaded.

## What the agent reads first

Before it changes anything, the agent grounds itself in two things.

* **[Knowledge](/docs/foundations/knowledge-base.md)** tells it what your data means and what your team already decided. It reads the knowledge base before it plans, and records what it learns.
* **[Lineage](/docs/foundations/lineage.md)** tells it how your data is produced. It uses lineage to find what a change would break downstream.

## Related

> [card] [Chats](/docs/workspaces/chats.md)
>
> Where you work with the agent.

> [card] [Plugins & Connections](/docs/foundations/plugins-and-connections.md)
>
> The data the agent can reach.

> [card] [Knowledge Base](/docs/foundations/knowledge-base.md)
>
> What your data means, and what your team decided about it.

> [card] [Data Lineage](/docs/foundations/lineage.md)
>
> How your data is produced, and what breaks if you change it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.