Tools reference

This page covers the core read tools, the findings tools and the workspace context tools in detail. The overview lists every tool, including the other ones that change things. Most tools take a dataset by its name, by its source table as schema.table (for example rwzant.po), or by its ID of the form ds_019…. Use list_datasets to discover dataset IDs and list_data_connectors to discover connector IDs.

​

list_data_connectors

List the data connectors the caller can see: owned connectors plus anything shared with them. A data connector is a database, file upload, or third-party integration that contains one or more datasets. Returns: an array of { id, displayName, kind, accessLevel, database, createdAt, updatedAt }, plus count, total, truncated and nextCursor when there are more pages. kind is one of postgres, mysql, snowflake, csv, fivetran, etc. accessLevel is owner or read. A connector whose delete is running has deleteStatus: "deleting". One whose delete failed has deleteStatus: "delete_failed" and a deleteError.

“What data connectors do I have in Summand?“

​

list_connector_tables

List the source tables in a data connector, each with its tableName and schemaName. The call opens a connection to the source database, so it can take a few seconds. It works for postgres, mysql, snowflake, azure-sql, delta-sharing and fivetran connectors. Other kinds, such as csv, have no source tables to list and return an error. Use it to pick the tables to pass to ingest_tables. The same table name can exist in several schemas, and schemaName says which one you mean. Returns: an array of { tableName, schemaName }, plus count, total, truncated and nextCursor when there are more pages. schemaName is left out when the source has no schema.

“Which tables in my Postgres connector can I ingest?“

​

list_datasets

List the datasets the caller can see: owned datasets plus anything shared with them. Returns: an array of { id, name, connectorId, schemaName, tableName, kind, status, targetColumn, latestVersion, accessLevel, updatedAt }, plus count, total, truncated and nextCursor when there are more pages. connectorId is the data connector the dataset came from, and is left out when that connector isn’t visible to the caller. schemaName and tableName name the source table, and are left out for datasets that have no schema. A dataset can be passed to other tools as schemaName.tableName even after it was renamed. Two datasets with the same name are different tables when their connectorId or schemaName differs.

“List my Summand datasets.”

​

describe_dataset

Full metadata for a dataset, including its computed-context manifest. The semanticLayer.availableComponents field lists the components that are valid inputs to get_columns and get_semantic_data (e.g. column_stats, ebm_graphs, feature_metadata, umap_embedding), across recent computed-context versions. semanticLayer.manifest.components only covers the most recent run. The response also has a findings array with the dataset’s accepted, active findings. Each one has a title, statement and verdict, plus failureCount, columns, flagReason, reviewedBy and reviewedAt when they’re set. A flagReason means the finding needs re-review. If the findings can’t be loaded, the rest of the response still comes back, with a findingsError in place of findings.

“Describe ds_019abc… — what analysis components are available?“

​

get_columns

Column information for a dataset. Returns rich statistics from the column_stats component when available (type, mean, min, max, null count, distinct count), or falls back to feature names from feature_metadata.

“What columns does ds_019abc… have, and what are their distributions?“

​

get_semantic_data

Retrieve a specific computed-context component. This is the workhorse tool — call describe_dataset first to see what’s available, then pull the component you want.

“Get the EBM graphs for JobLevel in ds_019abc….”

​

get_surprises

Surprise findings for a dataset — ML-generated unexpected statistical patterns with confidence scores and natural-language explanations. Returned in display order, with deleted items filtered out.

“What are the surprising findings in my HR attrition dataset?“

​

compare_schemas

Side-by-side column comparison between two datasets. Returns columns in both, columns only in A, and columns only in B.

“Compare the schemas of ds_019abc… and ds_019def….”

​

Findings

Findings are one-sentence rules about a dataset, with an optional SQL check. These five tools read and write them, and edit a dataset’s descriptions. Each takes a dataset name or ID as dataset. list_findings is read-only and needs the datasets:read scope. The other four change things and need datasets:write, which only the Member org role and higher get. They also need the dataset access noted under each tool.

​

Preview and confirm

propose_finding, update_finding, review_finding and update_dataset_context run in two calls:

1. Call the tool with its arguments. Nothing changes. The response has status: "preview", a proposal that describes what will happen, and a confirmationToken.
2. Show the proposal to the user. If they approve it, call the tool again with the same arguments plus confirm: true and the confirmationToken.

The token expires after five minutes, and it only works for the same tool, the same arguments and the same signed-in user. Otherwise the call returns status: "confirmation_invalid" and you have to start again from the preview. A confirmed call returns status: "done" along with the result described under each tool.

​

list_findings

List a dataset’s findings, newest first. Without filters it returns findings in every review state, retired ones included. Returns: { datasetId, findings, count }. Each finding includes findingId, title, statement, columns, checkSql, verdict, lastCheck (with failureCount when the check ran), review, status, dependsOn, flag when it needs re-review, and version.

“Which findings on kc_house_data are still waiting for review?“

​

propose_finding

Save a new finding as pending. It isn’t used as context until someone accepts it in Summand. Needs read access to the dataset. Adding checkSql needs edit access. Preview: the dataset ID, the finding as it will be saved (each dependency with its title), and review: "pending". Returns: { created: true, datasetId, finding }, with the saved finding. If it has a check, the check has already run once and verdict shows the result. Confirming the same arguments again returns the finding from the first call and doesn’t create a second one.

“Record a finding on kc_house_data that every sale has a price above zero, and check it.”

​

update_finding

Edit an existing finding. Only the fields you pass change. Changing the statement, columns, check or dependencies sends an accepted or rejected finding back to pending, and a new check runs once. Changing only the title keeps the review. Needs edit access to the dataset, except that the author of a pending finding can change everything but its check. Preview: each changed field with its current and proposed value (dependencies by title), and the finding’s current review and version. Returns: { updated: true, datasetId, finding }, with the updated finding.

“On kc_house_data, make the price-per-sqft finding depend on the prices-are-positive one.”

​

review_finding

Accept or reject a finding. The signed-in user is recorded as the reviewer, so only confirm it when the user has read the finding and made the decision themselves. Needs edit access to the dataset. Preview: the decision, the note, and the finding as it stands now: title, statement, columns, check, verdict, review and version. Returns: { reviewed: true, datasetId, finding }, with the updated finding.

“Accept the price finding on kc_house_data. I’ve checked it.”

​

update_dataset_context

Edit a dataset’s description, its column descriptions, or both. Ask Summand and every analysis of the dataset see these. Needs edit access to the dataset. Send datasetContext, columnDescriptions or both. Preview: the current and proposed text for the description and for each named column. Returns: { updated: true, datasetId, datasetContext, featureContexts }, where featureContexts holds every column description after the edit.

“Describe the view column on kc_house_data as a 0 to 4 rating of the view from the property.”

​

Workspace context

A workspace’s AI context is a Markdown note its admins write for analysis in that workspace, such as KPI definitions, column conventions and who to ask. Ask Summand applies it to every chat scoped to the workspace. Each tool takes a workspaceId from list_workspaces.

​

get_workspace_context

Read a workspace’s AI context. Any member of the workspace can read it, with the datasets:read scope. Returns: { workspaceId, content, updatedBy, updatedAt }. content is an empty string, and the other two are null, when no context has been written.

“What conventions does the Finance workspace ask analyses to follow?“

​

update_workspace_context

Replace a workspace’s AI context. Needs the Member org role or higher and the admin role in the workspace. An API key needs both sharing:write and datasets:read, because the update reads the current text before it writes. It runs in two calls, as described under Preview and confirm. If someone else saved the context after you read it, the preview or the confirmed call is refused, and nothing is overwritten. Read it again and re-apply your edit. Preview: the current and the proposed text. Returns: { updated: true, workspaceId, updatedBy, updatedAt }.

“Add a line to the Finance workspace context saying revenue is always net of refunds.”