Skip to main content

AutessaDB

The read/write surface between agents and your data: insert and update rows, filter and delete with structured conditions, run vector search over any column, browse and search the files in a Drive, and answer questions from analytics tables with SQL.

No connector is required — every tool takes a tableId identifying one of your AutessaDB tables. Writes go through the same pipeline as user edits, so table triggers fire and computed columns recompute. The write tools take a values map of column name to a typed value object — set the slot matching the column type (textValue, integerValue, floatValue, booleanValue, multiSelectValue, or filePath for file-type columns). On read paths, file-type columns come back with short-lived download links in presignedUrl.

The filter-based tools share one condition format, the same one used by the poweruser query API: whereGroups is a list of groups, each with a logicalOperator (AND/OR) combining its conditions (columnName, operator, value), and groupsLogicalOperator combines the groups. Operators include EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, LIKE, ILIKE, CONTAINS, STARTS_WITH, ENDS_WITH, IN, NOT_IN, BETWEEN, IS_NULL, and IS_NOT_NULL.

Insert Row TOOLAUTESSADB_INSERT​

Inserts one row into the table with the given column values. Triggers on the table are queued and computed columns are calculated asynchronously, exactly as if the row had been created in the UI.

The result is {"insertedId": ..., "computationStatus": ..., "newRow": {...}} with the full inserted row.

Example​

Tool config
{
  "toolType": "AUTESSADB_INSERT",
  "tableId": "V1StGXR8Z5",
  "values": {
    "customer_name": { "textValue": "@@{CUSTOMER_NAME}" },
    "priority": { "integerValue": 2 },
    "status": { "textValue": "OPEN" }
  }
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    values
    Type
    object
    Description
    Required object value.

Update Row TOOLAUTESSADB_UPDATE​

Updates a single row identified by rowId, changing only the columns present in values — other columns are untouched. Table triggers fire and computed columns recompute after the update.

The result is {"updatedId": ..., "computationStatus": ..., "oldRow": {...}, "newRow": {...}}, so the agent can see exactly what changed.

Example​

Tool config
{
  "toolType": "AUTESSADB_UPDATE",
  "tableId": "V1StGXR8Z5",
  "rowId": "@@{ROW_ID}",
  "values": {
    "status": { "textValue": "RESOLVED" },
    "resolution_notes": { "textValue": "@@{RESOLUTION_NOTES}" }
  }
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    rowId
    Type
    integer
    Description
    Required integer value.
  • Name
    values
    Type
    object
    Description
    Required object value.
  • Name
    deleteOrphanedFiles
    Type
    boolean
    Description
    Opt-in: when true, a FILE/IMAGE/AUDIO/VIDEO cell whose stored S3 URI is REPLACED or NULLED by this update has its prior S3 object deleted AFTER the transaction commits (best-effort; a delete failure is logged, never fails the write). Default false = fully backward compatible.

Delete Rows TOOLAUTESSADB_DELETE​

Batch-deletes every row matching whereGroups. groupsLogicalOperator defaults to OR, so with multiple groups a row matching any group is deleted — set it to AND explicitly when you mean an intersection. A deletion that would exceed the platform's batch-size cap is rolled back entirely, and dryRun: true skips the delete (it currently returns a placeholder message rather than a matching-row count, so preview counts with Query Table instead).

The result is {"tableId": ..., "deletedCount": ..., "deletedRows": [...]}.

Example​

Tool config
{
  "toolType": "AUTESSADB_DELETE",
  "tableId": "V1StGXR8Z5",
  "whereGroups": [
    {
      "logicalOperator": "AND",
      "conditions": [
        { "columnName": "status", "operator": "EQUALS", "value": "ARCHIVED" },
        { "columnName": "created_at", "operator": "LESS_THAN", "value": "@@{CUTOFF_DATE}" }
      ]
    }
  ],
  "groupsLogicalOperator": "AND",
  "dryRun": false
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    whereGroups
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    groupsLogicalOperator
    Type
    string
    Description
    "AND" or "OR" — how to combine multiple whereGroups. Defaults to "OR".
  • Name
    dryRun
    Type
    boolean
    Description
    When true, returns the matching row count but does not delete. Defaults to false.

Bulk Insert TOOLAUTESSADB_BULK_INSERT​

Inserts many rows into the table in a single call. rows is a list of value maps, each the same shape as an AUTESSADB_INSERT values. Unlike single-row insert, table triggers are suppressed by default — bulk loads are usually ingestion where firing per-row triggers is rarely intended. Set triggerMode to PER_ROW or BATCH_CONTEXT to opt in. atomicity is ALL_OR_NOTHING (default; the whole call is one transaction) or BEST_EFFORT_PER_CHUNK (partial progress allowed). indexingMode and computeMode (IMMEDIATE/DEFERRED/SKIP) control when indexing and computed columns run. The row count per call is capped.

The result is {"insertedCount": ..., "computationStatus": ..., "results": [{ "inputIndex": ..., "insertedId": ..., "errors": [...] }, ...]}.

Example​

Tool config
{
  "toolType": "AUTESSADB_BULK_INSERT",
  "tableId": "V1StGXR8Z5",
  "rows": [
    { "name": { "textValue": "Ada" } },
    { "name": { "textValue": "Grace" } }
  ],
  "atomicity": "ALL_OR_NOTHING"
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    rows
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    atomicity
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    indexingMode
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    computeMode
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    triggerMode
    Type
    string (enum)
    Description
    Required string (enum) value.

Bulk Update TOOLAUTESSADB_BULK_UPDATE​

Updates many rows by id in a single call. updates is a list of { "id": ..., "values": {...} }, where each values is a partial patch (only the supplied columns change). Same mode fields and defaults as Bulk Insert (triggers suppressed by default).

The result is {"updatedCount": ..., "computationStatus": ..., "results": [{ "inputIndex": ..., "updatedId": ..., "errors": [...] }, ...]}.

Example​

Tool config
{
  "toolType": "AUTESSADB_BULK_UPDATE",
  "tableId": "V1StGXR8Z5",
  "updates": [
    { "id": "@@{ROW_ID_1}", "values": { "status": { "textValue": "RESOLVED" } } },
    { "id": "@@{ROW_ID_2}", "values": { "status": { "textValue": "OPEN" } } }
  ]
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    updates
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    atomicity
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    indexingMode
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    computeMode
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    triggerMode
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    deleteOrphanedFiles
    Type
    boolean
    Description
    Opt-in: when true, any FILE/IMAGE/AUDIO/VIDEO cell whose stored S3 URI is REPLACED or NULLED by this bulk update has its prior S3 object deleted AFTER commit (best-effort; a delete failure is logged, never fails the write). Default false = fully backward compatible.

Bulk Delete TOOLAUTESSADB_BULK_DELETE​

Deletes many rows by id in a single call. ids is the list of row ids to remove. Only atomicity and triggerMode apply (nothing to index or compute on a delete); triggers are suppressed by default.

The result is {"deletedCount": ..., "results": [{ "inputIndex": ..., "deletedId": ..., "errors": [...] }, ...]}.

Example​

Tool config
{
  "toolType": "AUTESSADB_BULK_DELETE",
  "tableId": "V1StGXR8Z5",
  "ids": [12345, 12346, 12347]
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    ids
    Type
    array<integer>
    Description
    Required array<integer> value.
  • Name
    atomicity
    Type
    string (enum)
    Description
    Required string (enum) value.
  • Name
    triggerMode
    Type
    string (enum)
    Description
    Required string (enum) value.

Query Table TOOLAUTESSADB_QUERY_TABLE​

Runs a structured, filtered query over the table and returns matching rows with pagination. pageSize defaults to 50 and is silently capped at 100; leave whereGroups empty to page through the whole table. File-type columns in the results carry short-lived download links.

Add orderBy to control sort order — a list of { "columnName": ..., "direction": "ASC" | "DESC" } terms in priority order. For large tables, use seek pagination instead of page: pass the prior result's nextCursor back as cursor (reusing the same orderBy), and set includeTotal to true only when you actually need the total count.

The result is {"rows": [...], "totalCount": ..., "currentPage": ..., "totalPages": ..., "nextCursor": ..., "hasMore": ..., "schema": {...}} — the schema lets the agent interpret column types without a separate lookup, and nextCursor/hasMore drive cursor pagination.

Example​

Tool config
{
  "toolType": "AUTESSADB_QUERY_TABLE",
  "tableId": "V1StGXR8Z5",
  "whereGroups": [
    {
      "logicalOperator": "OR",
      "conditions": [
        { "columnName": "assignee", "operator": "EQUALS", "value": "@@{ASSIGNEE}" },
        { "columnName": "assignee", "operator": "IS_NULL", "value": "" }
      ]
    }
  ],
  "groupsLogicalOperator": "AND",
  "orderBy": [{ "columnName": "created_at", "direction": "DESC" }],
  "pageSize": 50
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    whereGroups
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    groupsLogicalOperator
    Type
    string
    Description
    Required string value.
  • Name
    orderBy
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    page
    Type
    integer
    Description
    Required integer value.
  • Name
    pageSize
    Type
    integer
    Description
    Required integer value.
  • Name
    cursor
    Type
    string
    Description
    Required string value.
  • Name
    includeTotal
    Type
    boolean
    Description
    Required boolean value.
  • Name
    includeFileUrls
    Type
    boolean
    Description
    Required boolean value.

Aggregate TOOLAUTESSADB_AGGREGATE​

Runs a grouped aggregation over the table: filter with whereGroups, group by up to a few columns (groupBy), and compute aggregates (COUNT/SUM/AVG/MIN/MAX, each under a unique alias). Optionally filter groups with having (referencing aliases), sort with orderBy, and cap the result with limit. Columns hidden from the acting identity are treated as not existing, and columns visible only in masked form cannot be grouped or aggregated.

The result is {"groups": [{ "key": {...}, "values": {...} }, ...]} — one entry per group, with the grouping key and each alias's numeric value.

Example​

Tool config
{
  "toolType": "AUTESSADB_AGGREGATE",
  "tableId": "V1StGXR8Z5",
  "groupBy": ["status"],
  "aggregates": [
    { "function": "COUNT", "alias": "count" },
    { "function": "AVG", "column": "age", "alias": "avg_age" }
  ],
  "orderBy": [{ "columnName": "count", "direction": "DESC" }]
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    whereGroups
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    groupsLogicalOperator
    Type
    string
    Description
    Required string value.
  • Name
    groupBy
    Type
    array<string>
    Description
    Required array<string> value.
  • Name
    aggregates
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    having
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    orderBy
    Type
    array<object>
    Description
    Required array<object> value.
  • Name
    limit
    Type
    integer
    Description
    Required integer value.

Semantic Query TOOLAUTESSADB_SEMANTIC_QUERY​

Runs vector-embedding search over one column (columnName) of the table and returns scored matches as structured JSON — the tool for RAG-style retrieval where the agent needs scores, pagination, and row details. limit defaults to 10 (max 100) and scoreThreshold (0–1) defaults to 0, so by default you get the top matches regardless of similarity. Semantic searches are rate-limited per company.

The result is {"results": [...], "totalResults": ..., "currentPage": ..., "totalPages": ..., "metadata": {...}, "schema": {...}}.

Example​

Tool config
{
  "toolType": "AUTESSADB_SEMANTIC_QUERY",
  "tableId": "V1StGXR8Z5",
  "query": "@@{SEARCH_QUERY}",
  "columnName": "document_text",
  "limit": 10,
  "scoreThreshold": 0.5,
  "page": 1,
  "includeDetails": true
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    query
    Type
    string
    Description
    Required string value.
  • Name
    columnName
    Type
    string
    Description
    Required string value.
  • Name
    limit
    Type
    integer
    Description
    Required integer value.
  • Name
    scoreThreshold
    Type
    number
    Description
    Required number value.
  • Name
    page
    Type
    integer
    Description
    Required integer value.
  • Name
    includeDetails
    Type
    boolean
    Description
    Required boolean value.
  • Name
    includeFileUrls
    Type
    boolean
    Description
    Required boolean value.

General Search TOOLAUTESSADB_GENERAL_SEARCH​

The same vector search as Semantic Query, packaged for direct reading: results come back as a readable markdown string (## MATCH #1 (score: 0.84, recordId: ...) followed by the content) instead of JSON. Defaults are tuned for precision — topK defaults to 5 and scoreThreshold to 0.7 — and there is no pagination. For file, image, and video columns it returns the content of the column's auto-generated notes companion rather than the raw file.

Prefer this type when the agent just needs to read what matched; prefer Semantic Query when downstream steps need structured fields.

Example​

Tool config
{
  "toolType": "AUTESSADB_GENERAL_SEARCH",
  "tableId": "V1StGXR8Z5",
  "query": "@@{SEARCH_QUERY}",
  "columnName": "meeting_transcript",
  "topK": 5,
  "scoreThreshold": 0.7
}

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    query
    Type
    string
    Description
    Required string value.
  • Name
    columnName
    Type
    string
    Description
    Required string value.
  • Name
    topK
    Type
    integer
    Description
    Required integer value.
  • Name
    scoreThreshold
    Type
    number
    Description
    Required number value.
  • Name
    includeFileUrls
    Type
    boolean
    Description
    Required boolean value.

Drive​

TOOLAUTESSADB_DRIVE

Gives an agent access to an AutessaDB Drive: browse folders, find files, grep exact text, read pages and lines, run ranked search (meaning-based when the Drive's semantic search is on), look at files, and write text files. tableId must be a Drive. op picks the operation:

opWhat it doesMain arguments
lsList a folder's contents, folders firstpath, limit, cursor
treeOutline a folder and its subfolderspath, maxDepth, maxEntries
findFind files by name, glob, type, date, or sizepath, glob, nameRegex, type, modifiedAfter
statDetails of one file: size, version, page count, processing statuspath
grepLines containing an exact string or matching a regular expressionpattern, regex, caseInsensitive, path, glob, context
readText of a page range or line rangepath, pages or lines, maxChars
searchRanked keyword search; meaning-based when semantic search is enabledquery, mode, path, topK
fetchA 10-minute download link; with view: true, the image or PDF pages are shown to the modelpath, view, pages (at most 5), version
writeCreate, replace, or append to a text file (up to 5 MB); missing folders are createdpath, content, mode (overwrite, create, append), expectedVersion
editReplace exact text in a text filepath, oldText, newText, replaceAll, expectedVersion
mkdirCreate a folder and any missing parentspath
moveMove into a folder, or rename by giving a new pathpath, destinationPath, confirm
trashMove to the trashpath

write, edit, mkdir, move and trash need Editor access on the item or folder for the acting identity. Every write and edit is a new version of the file. edit fails with EDIT_NO_MATCH when oldText is not in the file and with EDIT_AMBIGUOUS when it occurs more than once; write and edit fail with VERSION_CONFLICT when expectedVersion is stale. Each error carries a hint that names the next call.

The arguments and their limits match the Drive API. Any argument can be a @@{...} placeholder the agent fills at run time. Set rootPath to confine the tool to one folder: every path the agent sends is resolved inside it, and nothing outside it is visible even if the acting identity could see more.

The tool sees only what its acting identity can open. When an agent acts for a user, results are exactly what that user would see in the explorer.

When a Drive is bound to an agent, the agent receives one narrow tool per operation (drive_ls, drive_tree, drive_find, drive_stat, drive_grep, drive_read, drive_search, drive_fetch, drive_write, drive_edit, drive_mkdir, drive_move, and drive_trash) with guidance to use search for topics, grep for exact strings, read the page or lines before quoting, and edit files by reading them first and copying the exact text to replace.

The result is {"output": "...", "data": {...}}. output is formatted for the model: listings as aligned text, grep hits as path (vN) p3:L12: ...match..., and read as numbered lines. data carries the same structured response as the API, including nextCursor and truncated. Cite results as path p.N L.M. A fetch with view: true also returns the images the model sees, in the same way as Fetch and View.

Example config​

Tool config
{
  "toolType": "AUTESSADB_DRIVE",
  "tableId": "V1StGXR8Z5",
  "op": "grep",
  "rootPath": "/Shared/Legal",
  "pattern": "@@{PATTERN}",
  "caseInsensitive": true,
  "context": 1
}
output
/Shared/Legal/Contracts/acme-msa.pdf (v2) p4:L12: 12.2 **Termination for Convenience**. Either party may terminate this Agreement
/Shared/Legal/Contracts/globex-msa.pdf (v1) p7:L3: 9.1 **Termination for Convenience**. Customer may terminate upon thirty (30) days
2 matches in 2 files. 1 file in scope is still processing.

Configuration fields

  • Name
    tableId
    Type
    string (ID)
    Description
    Required string (ID) value. References an AutessaDB table by ID.
  • Name
    op
    Type
    string
    Description
    ls | tree | find | stat | grep | read | search | fetch | write | edit | mkdir | move | trash | comment
  • Name
    rootPath
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    path
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    nodeId
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    glob
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    nameRegex
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    type
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    mime
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    modifiedAfter
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    modifiedBefore
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    sizeGt
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    sizeLt
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    pattern
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    regex
    Type
    boolean
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    caseInsensitive
    Type
    boolean
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    outputMode
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    context
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    maxMatchesPerFile
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    pages
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    lines
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    maxChars
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    query
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    mode
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    topK
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    maxDepth
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    maxEntries
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    limit
    Type
    integer
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    cursor
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    sort
    Type
    string
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    foldersOnly
    Type
    boolean
    Description
    Hard scope ceiling, e.g. `/Shared/Contracts`; null = the whole Drive (as the identity sees it).
  • Name
    content
    Type
    string
    Description
    write: the text; append mode adds it to the end.
  • Name
    oldText
    Type
    string
    Description
    edit: the exact text to replace, and its replacement.
  • Name
    newText
    Type
    string
    Description
    edit: the exact text to replace, and its replacement.
  • Name
    replaceAll
    Type
    boolean
    Description
    edit: the exact text to replace, and its replacement.
  • Name
    expectedVersion
    Type
    integer
    Description
    write / edit: fail with VERSION_CONFLICT unless the file is at this version.
  • Name
    view
    Type
    boolean
    Description
    fetch: show the image / PDF pages to the model.
  • Name
    version
    Type
    integer
    Description
    fetch: an earlier version.
  • Name
    destinationPath
    Type
    string
    Description
    move: the folder to move into, or the new full path.
  • Name
    confirm
    Type
    boolean
    Description
    move: proceed although access changes.
  • Name
    action
    Type
    string
    Description
    comment: `add` (default) or `list`.
  • Name
    body
    Type
    string
    Description
    comment add: the comment text.
  • Name
    page
    Type
    integer
    Description
    comment add: anchor the comment to this page (1-based).
  • Name
    quote
    Type
    string
    Description
    comment add: the exact words the comment is about (found in the file's text and highlighted).
  • Name
    range
    Type
    string
    Description
    comment add (spreadsheets): the cell or range the comment is about, such as B3:D7.
  • Name
    sheet
    Type
    string
    Description
    comment add (spreadsheets): the sheet of range.
  • Name
    parentId
    Type
    string
    Description
    comment add: reply to this comment's thread (its id from a list).
  • Name
    includeResolved
    Type
    boolean
    Description
    comment list: include resolved threads.

Describe Analytics Tables​

TOOLANALYTICS_DESCRIBE

Tells an agent what one or more analytics tables contain, so it can write correct SQL. The agent should call it before its first query. Columns the acting identity cannot see are left out.

The result is markdown, one section per table: SQL name, description, grain, row count, last load time, the partition columns ("filter on these"), each column with its type, description, synonyms, and (with includeStats) its most common values, the measures as name := sql, joins, and verified queries.

Example config​

Tool config
{
  "toolType": "ANALYTICS_DESCRIBE",
  "tableIds": ["V1StGXR8Z5", "Hq4ZpN8sXe"],
  "includeStats": true
}

Configuration fields

  • Name
    tableIds
    Type
    array<integer>
    Description
    The analytics tables this tool may describe (and nothing else). References an AutessaDB table by ID.
  • Name
    includeStats
    Type
    boolean
    Description
    Include column statistics (null counts, ranges, top values).

Query Analytics Tables​

TOOLANALYTICS_QUERY

Runs one read-only SQL query, written in ANSI SQL, over the analytics tables listed in tableIds. Usually sql is @@{sql} so the agent writes the query; it can also be fixed SQL with placeholders for values. mode is RUN (default), PREVIEW (a quick sample), or ESTIMATE (report how much data the query would scan, without running it). Queries can only read the tables in tableIds, and row-level and field-level security apply.

Queries typically take a few seconds. maxRows caps the rows returned to the agent (default 200, maximum 1,000). The tool waits up to maxWaitSeconds (default 25) for the query; if it is still running, the result is {"state": "RUNNING", "jobId": "...", "hint": "call ANALYTICS_GET_RESULT"}.

A finished result is {"jobId", "state", "columns", "rows", "totalRows", "truncated", "bytesScanned", "elapsedMs", "markdown"}, where markdown is a table of up to 50 rows for the model to read. A failed query returns {"errorCode", "errorMessage", "hint"} with codes such as PARSE_ERROR, UNKNOWN_TABLE, UNKNOWN_COLUMN (the hint lists the real columns), and SCAN_LIMIT (the hint names the partition columns to filter on). See the Analytics API errors. Download links are never put in the model's context.

Example config​

Tool config
{
  "toolType": "ANALYTICS_QUERY",
  "tableIds": ["V1StGXR8Z5", "Hq4ZpN8sXe"],
  "sql": "@@{sql}",
  "mode": "RUN",
  "maxRows": 200,
  "maxWaitSeconds": 25
}

Configuration fields

  • Name
    tableIds
    Type
    array<integer>
    Description
    The analytics tables the SQL may reference. References an AutessaDB table by ID.
  • Name
    sql
    Type
    string
    Description
    The SQL (normally filled by the LLM through the `@@{sql`} argument).
  • Name
    mode
    Type
    string
    Description
    RUN (default) | PREVIEW | ESTIMATE.
  • Name
    maxRows
    Type
    integer
    Description
    Rows returned to the agent (default 200, at most 1000).
  • Name
    maxWaitSeconds
    Type
    integer
    Description
    How long to wait for the result before returning the jobId (default 25 s).
  • Name
    maxBytesScanned
    Type
    integer
    Description
    Refuse queries that would scan more than this many bytes (default: the company limit).

Get Analytics Result​

TOOLANALYTICS_GET_RESULT

Fetches the result of a query started by Query Analytics Tables: waits up to waitSeconds for a running job, then returns one page of rows (pageSize up to 200) in the same shape as a finished query. Use it when a query returned RUNNING, or to page past the first rows of a large result.

Example config​

Tool config
{
  "toolType": "ANALYTICS_GET_RESULT",
  "jobId": "@@{jobId}",
  "page": "@@{page}",
  "pageSize": 200,
  "waitSeconds": 20
}

Configuration fields

  • Name
    tableIds
    Type
    array<integer>
    Description
    The analytics tables whose jobs this tool may read. References an AutessaDB table by ID.
  • Name
    jobId
    Type
    string
    Description
    The job id returned by ANALYTICS_QUERY (normally `@@{jobId`}).
  • Name
    page
    Type
    integer
    Description
    1-based result page (default 1).
  • Name
    pageSize
    Type
    integer
    Description
    Rows per page (default and max 200).
  • Name
    waitSeconds
    Type
    integer
    Description
    Wait up to this long for a running job to finish (default 20 s, max 25 s).

The three analytics tools are usually created together, bound to the same tables, with Create agent tools on the table's page or the create-agent-tools endpoint.