Table tool

With the table tool, you can give an AI agent access to a Table Definition. This lets the agent read, create, update, or delete rows depending on what you enable.

Create the table tool

Go to AI Tools, create a new tool, set the type to Table Definition, and select the table you want to expose.

There is no Prompt tab for this tool type. The prompt is generated automatically at runtime from the table’s metadata.

Configure the table tool

Operations and display names

Enable each operation you want the agent to be able to perform:

Read — Query and view records.
Create — Insert new records.
Update — Modify existing records.
Delete — Delete records.

Each operation has a Display Name field. The display name is a user-friendly label shown in the chat interface when the tool is triggered, replacing the internal tool name derived from the artifact’s Name property. If left empty, the internal name is used.

If an operation is disabled, the agent has no way to invoke it — its corresponding tool is not registered at runtime.

Read Fields

When the Read operation is enabled, the Read Fields panel lists all columns available for querying and viewing. Select individual columns to restrict what the agent can access, or use Select All to allow the full column set.

The id (primary key) column is always readable regardless of the selection. Audit columns (createdAt, updatedAt, createdBy, updatedBy) are included in the available selection but can be excluded if not needed.

Update Fields

When the Update operation is enabled, the Update Fields panel lists all non-primary-key columns the agent may modify. Select individual columns to restrict which fields can be changed, or use Select All to allow updates to all listed fields.

Any attempt to update a column not in this selection is rejected at runtime. Audit fields (updatedAt, updatedBy) are always updated automatically by the platform and cannot be set by the agent.

Role-based access

The table tool enforces the read and write access roles configured on the underlying Table Definition. Roles are checked each time the agent invokes a tool:

For read operations, the current user must hold at least one of the table’s Role Read roles.
For create, update, and delete operations, the current user must hold at least one of the table’s Role Write roles.

If the user lacks the required role, the tool call fails with a permission error. This check cannot be bypassed through prompt injection.

How the tool is exposed to the agent

A single table tool entry expands into up to five individual tools at runtime — one per enabled operation plus a metadata tool. The agent calls these tools by name, following the pattern {operation}{TableName}:

Tool What it does

Tool	What it does
`get{TableName}Metadata`	Returns the full table schema: column names, types, nullable/required status, read and update access per column, and foreign key relationships.
`get{TableName}`	Executes a read-only SQL SELECT against the table. Only SELECT statements are allowed, and only the columns enabled under Read Fields are accessible.
`create{TableName}`	Inserts one or more records into the table. Audit fields are set automatically.
`update{TableName}`	Updates existing records by primary key. Only the columns enabled under Update Fields can be changed. Audit fields are updated automatically.
`delete{TableName}`	Deletes records by primary key. This operation is irreversible.

get{TableName}Metadata

Returns the full table schema: column names, types, nullable/required status, read and update access per column, and foreign key relationships.

get{TableName}

Executes a read-only SQL SELECT against the table. Only SELECT statements are allowed, and only the columns enabled under Read Fields are accessible.

create{TableName}

Inserts one or more records into the table. Audit fields are set automatically.

update{TableName}

Updates existing records by primary key. Only the columns enabled under Update Fields can be changed. Audit fields are updated automatically.

delete{TableName}

Deletes records by primary key. This operation is irreversible.

Metadata tool

The get{TableName}Metadata tool is always registered when at least one operation is enabled. It returns a structured schema description that includes:

Column names, data types, and nullable/required status
Per-column access flags (read: yes/no, update: yes/no) derived from the Read Fields and Update Fields selections
Foreign key relationships — related tables, local and referenced columns, and delete behavior
The database type and the fully qualified internal table name used in SQL

The agent uses this information to build correct queries and insert or update payloads. It calls the metadata tool only once per conversation — or when the schema is no longer present in context — to avoid redundant lookups. Vector columns are excluded from the schema description.