research_company

Research the companies in a list and write the findings into a column on that same list.

The tool targets a list, ensures a Company Research column exists on it, and then runs research across the list's records (or a chosen subset). Results are written back into each record so they appear as a new column in the table.

Research methodology is a placeholder

The wiring is complete end-to-end, but the actual research prompt is a placeholder for now — it produces a best-effort summary from the model's own knowledge. The real methodology (web search, Unipile enrichment, multi-step tool use, …) will replace the prompt later without changing this tool's interface.

Arguments

Name	Type	Required	Default	Description
listId	string	yes	—	Id of the list whose company records should be researched.
recordIds	string[]	no	all records	Restrict research to these record ids. When omitted, every record in the list is researched.
columnName	string	no	"Company Research"	Display name for the research column (only used when the column is first created).
model	string	no	"claude-opus-4-8"	AI model id to run the research with (only used when the column is first created).

The workspace is taken from your API key — you never pass it.

What it does

1. Verifies the list belongs to your workspace.
2. Ensures the research column exists on the list. If missing, it creates a text AI column with key company_research. If it already exists, it's reused (so columnName/model only apply on first creation).
3. Resolves the records — your recordIds, or every record in the list.
4. Runs the AI-column pipeline — one Hatchet ai-column-execution run per record.
5. Writes results into each record's fields.company_research as its run completes.

Result

The tool returns immediately (research runs asynchronously) with a summary:

{
  "listId": "list_abc123",
  "columnId": "col_def456",
  "columnKey": "company_research",
  "recordCount": 42,
  "runIds": ["run_1", "run_2", "..."],
  "message": "Started company research for 42 record(s). Results are written into the \"Company Research\" column as each run completes."
}

Cells populate as each run finishes — refresh the list (or watch the AI run stream) to see them fill in. If the list has no records, recordCount is 0 and nothing is executed.

Requirements

• The Hatchet worker must be running (bun run worker:dev) — it executes the research runs.
• The AI gateway must be enabled (AI_GATEWAY_ENABLED not false).

Example

From a Claude Code session:

Use research_company on list list_abc123, only for records rec_1 and rec_2.

Which calls the tool with:

{
  "listId": "list_abc123",
  "recordIds": ["rec_1", "rec_2"]
}