Research tables

Optional research tools. A research table is built by agents that find its rows and fill each cell from a source. Building and researching rows cost money by the row, so both are always checked.

For the business’s own lists, such as a month of hours, use a Google Sheet through files or a spreadsheet in the workspace.

How to use it

What find_tools sends with these tools, word for word:

Research tables: agents find rows and fill each cell from a source. Builds cost money; Pro estimates the cost first.

Tools

Tool	What it does	Owner’s yes
tables.list	Tables	No
tables.read	A table’s columns, rows and cell values	No
tables.build	Plan and build a new table, in the project the owner names, else the one you file into. It costs money by the row	Checked
tables.add_row	Add a row by the columns that identify it	No
tables.research_rows	Research some rows again. It costs money by the row	Checked
tables.accept_cell	Accept a value waiting for review	Checked

list

tables.list · Tables.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
projectId	id	no

Returns:

{
  id: string;
  name: string;
  question: string;
  projects: {
    id: string;
    name: string;
  }[];
  row: string;
  columns: number;
  updatedAt: string;
  run: {
    id: string;
    kind: DatasetRunKind;
    status: DatasetRunStatus;
    estimateUsd: number;
    capUsd: number;
    spentUsd: number;
    rowsTotal: number;
    rowsDone: number;
    message: string | null;
    createdAt: string;
    completedAt: string | null;
  } | null;
}[]

read

tables.read · A table’s columns, rows and cell values.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
datasetId	id	yes

Returns:

{
  dataset: {
    id: string;
    projects: {
      id: string;
      name: string;
    }[];
    name: string;
    question: string;
    plan: {
      row: string;
      rule: string;
      queries: string[];
      columns: {
        name: string;
        label: string;
        type: "number" | "date" | "text" | "choice" | "rating" | "yes_no";
        unit: string | null;
        options: string[] | null;
        instructions: string;
        identifies: boolean;
      }[];
    };
    createdAt: string;
    agentId: string | null;
    spentUsd: number;
    run: {
      id: string;
      kind: DatasetRunKind;
      status: DatasetRunStatus;
      estimateUsd: number;
      capUsd: number;
      spentUsd: number;
      rowsTotal: number;
      rowsDone: number;
      message: string | null;
      createdAt: string;
      completedAt: string | null;
    } | null;
  };
  rows: StoredRow[];
}

build

tables.build · Plan and build a new table, in the project the owner names, else the one you file into. It costs money by the row.

Owner’s yes: Checked. It carries a note for the check to weigh, such as a cost.
Your work: listed on Home.

Input	Type	Required	Limits
projectId	id	no
question	text	yes	1–2,000 characters
maxRows	whole number	no	1–250, default 25

Returns:

{
  id: string;
  projects: {
    id: string;
    name: string;
  }[];
  name: string;
  question: string;
  plan: {
    row: string;
    rule: string;
    queries: string[];
    columns: {
      name: string;
      label: string;
      type: "number" | "date" | "text" | "choice" | "rating" | "yes_no";
      unit: string | null;
      options: string[] | null;
      instructions: string;
      identifies: boolean;
    }[];
  };
  createdAt: string;
  agentId: string | null;
  spentUsd: number;
  run: {
    id: string;
    kind: DatasetRunKind;
    status: DatasetRunStatus;
    estimateUsd: number;
    capUsd: number;
    spentUsd: number;
    rowsTotal: number;
    rowsDone: number;
    message: string | null;
    createdAt: string;
    completedAt: string | null;
  } | null;
}

add_row

tables.add_row · Add a row by the columns that identify it.

Owner’s yes: No. It makes something new.
Your work: listed on Home.

Input	Type	Required	Limits
datasetId	id	yes
identity	named values of text	yes

Returns:

{
  key: string;
}

research_rows

tables.research_rows · Research some rows again. It costs money by the row.

Owner’s yes: Checked. It changes what’s there. It can also carry a note for the check to weigh.
Your work: listed on Home.

Input	Type	Required	Limits
datasetId	id	yes
rowKeys	list of text	yes	1–250 items

Returns:

{
  id: string;
  projects: {
    id: string;
    name: string;
  }[];
  name: string;
  question: string;
  plan: {
    row: string;
    rule: string;
    queries: string[];
    columns: {
      name: string;
      label: string;
      type: "number" | "date" | "text" | "choice" | "rating" | "yes_no";
      unit: string | null;
      options: string[] | null;
      instructions: string;
      identifies: boolean;
    }[];
  };
  createdAt: string;
  agentId: string | null;
  spentUsd: number;
  run: {
    id: string;
    kind: DatasetRunKind;
    status: DatasetRunStatus;
    estimateUsd: number;
    capUsd: number;
    spentUsd: number;
    rowsTotal: number;
    rowsDone: number;
    message: string | null;
    createdAt: string;
    completedAt: string | null;
  } | null;
}

accept_cell

tables.accept_cell · Accept a value waiting for review.

Owner’s yes: Checked. It changes what’s there.
Your work: listed on Home.

Input	Type	Required	Limits
datasetId	id	yes
key	text	yes
column	text	yes

Returns:

{ done: true }

Types

Named types in the results above.

type DatasetRunKind = "build" | "rerun"

type DatasetRunStatus = "stopped" | "done" | "queued" | "running" | "failed"

type StoredRow = {
  key: string;
  values: {
    [x: string]: CellValue;
  };
  sources: {
    [x: string]: CellSource;
  };
}

type CellValue = string | number | null

type CellSource = {
  status: "failed" | "filled" | "needs_review" | "not_disclosed" | "edited";
  quote?: QuoteRef;
  url?: string;
  agree?: number;
  from?: string;
  human?: true;
  was?: {
    value: CellValue;
    source: CellSource | null;
  };
}

type QuoteRef = {
  page: string;
  start: number;
  end: number;
}