---
title: Companies
description: The businesses the owner deals with, each with its people, Context and a timeline of conversations. 11 tools.
group: companies
tools: [companies.list, companies.read, companies.create, companies.update, companies.about, companies.timeline, companies.record, companies.unrecord, companies.open, companies.context, companies.link_person]
source: [packages/agents/src/tools/features.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

A company is a business the owner deals with: a client such as Juniper Dental, a supplier, a lead. All the owner's agents share one list.

A company holds:

- **Fields**: name, website, domains, labels, and a handler: the agent whose work it is. Work about a company goes to its handler.
- **Details**: named facts such as `Terms: net 30`. `null` clears one.
- **Context**: what everyone should know about working with them.
- **About**: what the web says about them, with sources, set with `about`.
- **People**: contacts linked with a role, and when they started and ended (`link_person`).
- **Open items**: who owes the next move, as on [contacts](/tools/contacts/).
- **Timeline**: one entry per conversation (a mail thread, meeting, call or invoice) with what was said or decided. Record one after each conversation; recording the same thread again updates its entry.

Read a company before you work for it. Record conversations, never your own steps.

## How to use it

What `find_tools` sends with these tools, word for word:

> The businesses the owner deals with, shared by all the owner's agents: each with its people and their roles, a Context, details such as terms, an About from the web, and a timeline. Read a company before you work for it. Its timeline is its conversations with the business, one entry per thread, meeting, call or invoice: after one, record what was said or decided, and recording the same thread again updates its entry. ours is who wrote for the business: your agent id when you did; leave it out when the owner did. Fix an entry by recording it again with its entryId; take one off only when the owner asks. Never record your own steps, automated mail or newsletters. Work about a company goes to its handler.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [companies.list](#list) | Companies with labels, people, what's open, last contact and handler | No |
| [companies.read](#read) | Everything to know before working for a company: Context, details, About, people with roles, open, newest 20 conversations | No |
| [companies.create](#create) | Add a company; people are contact ids, a role each | No |
| [companies.update](#update) | Change a company's name, domains, labels, handler (an agent id) or details (named facts such as Terms; null clears one) | Checked |
| [companies.about](#about) | Replace a company's About from the web: text citing sources as [1], facts, dated news | Checked |
| [companies.timeline](#timeline) | A company's conversations, newest first; before is the last item's at | No |
| [companies.record](#record) | Add a conversation to a company's timeline, or update it: same entryId, thread or link. people: contact ids or addresses on their side; ours: agent ids that wrote for the business, else the owner | No |
| [companies.unrecord](#unrecord) | Take an entry off a company's timeline; the owner can undo it | Checked |
| [companies.open](#open) | Open an item on a company (a follow-up at a time wakes you), or close one by id | Depends |
| [companies.context](#context) | Set a company's Context: what everyone should know about working with them | Checked |
| [companies.link_person](#link_person) | Link a person to a company, or change the link: role, since, ended (dates) | No |

## list

`companies.list` · Companies with labels, people, what's open, last contact and handler.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `label` | text | no | 1–40 characters |
| `query` | text | no | up to 200 characters |
| `open` | one of `you`, `them`, `follow_up` | no |  |
| `quietDays` | whole number | no | 0 or more |
| `handledBy` | text | no | 1–80 characters |
| `offset` | whole number | no | 0 or more |

Returns:

```ts
{
  items: CompanyRow[];
  nextOffset: number | null;
  total: number;
}
```

## read

`companies.read` · Everything to know before working for a company: Context, details, About, people with roles, open, newest 20 conversations.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |

Returns:

```ts
{
  timeline: {
    id: string;
    kind: "note" | "mail" | "invoice" | "meeting" | "call";
    title: string;
    at: string;
    people: {
      name: string;
      id?: string;
    }[];
    ours: {
      kind: "agent" | "user" | "system";
      id: string;
    }[];
    by: {
      kind: "agent" | "user" | "system";
      id: string;
    };
    updatedAt: string;
    summary?: string;
    count?: number;
    minutes?: number;
    link?: string;
    thread?: string;
    files?: {
      name: string;
      link?: string;
    }[];
    state?: "overdue" | "paid" | "waiting_you" | "waiting_them";
  }[];
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  labels: string[];
  context: string | null;
  contextBy: {
    kind: "agent" | "user" | "system";
    id: string;
  } | null;
  contextAt: string | null;
  details: Record<string, string>;
  about: CompanyAbout | null;
  handler: string | null;
  firstOnMail: boolean;
  alwaysAsk: boolean;
  listed: {
    id: string;
    name: string;
    ticker: string | null;
  } | null;
  files: CompanyFile[];
  open: {
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  }[];
  people: CompanyPerson[];
  known: string | null;
  last: string | null;
  counts: {
    timeline: number;
    projects: number;
    docs: number;
    files: number;
  };
  createdAt: string;
  updatedAt: string;
}
```

## create

`companies.create` · Add a company; people are contact ids, a role each.

**Owner's yes:** No. It makes something new.\
**Your work:** listed on Home.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `name` | text | yes | 1–200 characters |
| `website` | text | no | 1–300 characters |
| `domains` | list of text | no | up to 10 items, each 1–200 characters |
| `labels` | list of text | no | up to 20 items, each 1–40 characters |
| `handler` | text | no | 1–80 characters |
| `people` | list of `{ contactId, role? }` | no | up to 200 items |
| `people[].contactId` | id | yes |  |
| `people[].role` | text | no | 1–200 characters |

Returns:

```ts
CompanyRecord | {
  message: string;
}
```

## update

`companies.update` · Change a company's name, domains, labels, handler (an agent id) or details (named facts such as Terms; null clears one).

**Owner's yes:** Checked. It changes what's there.\
**Your work:** not listed on Home; the change shows on the record itself.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `name` | text | no | 1–200 characters |
| `domains` | list of text | no | up to 10 items, each 1–200 characters |
| `labels` | list of text | no | up to 20 items, each 1–40 characters |
| `handler` | text or null | no | 1–80 characters |
| `details` | named values of text or null | no |  |
| `why` | text | yes | 1–2,000 characters |

Returns:

```ts
{
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  labels: string[];
  context: string | null;
  contextBy: {
    kind: "agent" | "user" | "system";
    id: string;
  } | null;
  contextAt: string | null;
  details: Record<string, string>;
  about: CompanyAbout | null;
  handler: string | null;
  firstOnMail: boolean;
  alwaysAsk: boolean;
  listed: {
    id: string;
    name: string;
    ticker: string | null;
  } | null;
  files: CompanyFile[];
  open: {
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  }[];
  people: CompanyPerson[];
  known: string | null;
  last: string | null;
  counts: {
    timeline: number;
    projects: number;
    docs: number;
    files: number;
  };
  createdAt: string;
  updatedAt: string;
}
```

## about

`companies.about` · Replace a company's About from the web: text citing sources as [1], facts, dated news.

**Owner's yes:** Checked. It changes what's there.\
**Your work:** not listed on Home; the change shows on the record itself.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `text` | text | yes | 1–3,000 characters |
| `facts` | list of `{ label, value }` | no | up to 12 items |
| `facts[].label` | text | yes | 1–40 characters |
| `facts[].value` | text | yes | 1–200 characters |
| `lately` | list of `{ date, text, source? }` | no | up to 10 items |
| `lately[].date` | date (YYYY-MM-DD) | yes |  |
| `lately[].text` | text | yes | 1–300 characters |
| `lately[].source` | whole number | no | 1 or more |
| `sources` | list of `{ title, url }` | yes | 1–20 items |
| `sources[].title` | text | yes | 1–200 characters |
| `sources[].url` | link | yes |  |

Returns:

```ts
{
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  labels: string[];
  context: string | null;
  contextBy: {
    kind: "agent" | "user" | "system";
    id: string;
  } | null;
  contextAt: string | null;
  details: Record<string, string>;
  about: CompanyAbout | null;
  handler: string | null;
  firstOnMail: boolean;
  alwaysAsk: boolean;
  listed: {
    id: string;
    name: string;
    ticker: string | null;
  } | null;
  files: CompanyFile[];
  open: {
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  }[];
  people: CompanyPerson[];
  known: string | null;
  last: string | null;
  counts: {
    timeline: number;
    projects: number;
    docs: number;
    files: number;
  };
  createdAt: string;
  updatedAt: string;
}
```

## timeline

`companies.timeline` · A company's conversations, newest first; before is the last item's at.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `kind` | one of `mail`, `meeting`, `call`, `invoice`, `note` | no |  |
| `contactId` | id | no |  |
| `query` | text | no | up to 200 characters |
| `before` | text | no |  |

Returns:

```ts
{
  items: {
    id: string;
    kind: "note" | "mail" | "invoice" | "meeting" | "call";
    title: string;
    at: string;
    people: {
      name: string;
      id?: string;
    }[];
    ours: {
      kind: "agent" | "user" | "system";
      id: string;
    }[];
    by: {
      kind: "agent" | "user" | "system";
      id: string;
    };
    updatedAt: string;
    summary?: string;
    count?: number;
    minutes?: number;
    link?: string;
    thread?: string;
    files?: {
      name: string;
      link?: string;
    }[];
    state?: "overdue" | "paid" | "waiting_you" | "waiting_them";
  }[];
  total: number;
  counts: {
    [k: string]: number;
  };
  nextBefore: string | null;
}
```

## record

`companies.record` · Add a conversation to a company's timeline, or update it: same entryId, thread or link. people: contact ids or addresses on their side; ours: agent ids that wrote for the business, else the owner.

**Owner's yes:** No. It makes something new.\
**Your work:** not listed on Home; the change shows on the record itself.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `entryId` | text | no |  |
| `kind` | one of `mail`, `meeting`, `call`, `invoice`, `note` | yes |  |
| `title` | text | yes | 1–200 characters |
| `summary` | text | no | up to 1,000 characters |
| `at` | date and time (ISO 8601) | yes |  |
| `people` | list of text | no | up to 20 items, each 1–254 characters |
| `ours` | list of text | no | up to 10 items, each 1–80 characters |
| `count` | whole number | no | 1 or more |
| `minutes` | whole number | no | 1 or more |
| `link` | link | no |  |
| `thread` | text | no |  |
| `files` | list of `{ name, link? }` | no | up to 20 items |
| `files[].name` | text | yes | 1–200 characters |
| `files[].link` | link | no |  |
| `state` | one of `waiting_you`, `waiting_them`, `paid`, `overdue` or null | no |  |

Returns:

```ts
{
  entry: {
    id: string;
    kind: "note" | "mail" | "invoice" | "meeting" | "call";
    title: string;
    at: string;
    people: {
      name: string;
      id?: string;
    }[];
    ours: {
      kind: "agent" | "user" | "system";
      id: string;
    }[];
    by: {
      kind: "agent" | "user" | "system";
      id: string;
    };
    updatedAt: string;
    summary?: string;
    count?: number;
    minutes?: number;
    link?: string;
    thread?: string;
    files?: {
      name: string;
      link?: string;
    }[];
    state?: "overdue" | "paid" | "waiting_you" | "waiting_them";
  };
  updated: boolean;
}
```

## unrecord

`companies.unrecord` · Take an entry off a company's timeline; the owner can undo it.

**Owner's yes:** Checked. It deletes.\
**Your work:** not listed on Home; the change shows on the record itself.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `entryId` | text | yes | at least 1 characters |

Returns:

```ts
{
  historyId: string;
}
```

## open

`companies.open` · Open an item on a company (a follow-up at a time wakes you), or close one by id.

**Owner's yes:** Depends on the input: checked when it changes what's there, not when it makes something new.\
**Your work:** not listed on Home; the change shows on the record itself.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `add` | object | no |  |
| `add.kind` | one of `you`, `them`, `follow_up` | yes |  |
| `add.text` | text | yes | 1–500 characters |
| `add.at` | date and time (ISO 8601) | no |  |
| `done` | text | no |  |

Returns:

```ts
{
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  labels: string[];
  context: string | null;
  contextBy: {
    kind: "agent" | "user" | "system";
    id: string;
  } | null;
  contextAt: string | null;
  details: Record<string, string>;
  about: CompanyAbout | null;
  handler: string | null;
  firstOnMail: boolean;
  alwaysAsk: boolean;
  listed: {
    id: string;
    name: string;
    ticker: string | null;
  } | null;
  files: CompanyFile[];
  open: {
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  }[];
  people: CompanyPerson[];
  known: string | null;
  last: string | null;
  counts: {
    timeline: number;
    projects: number;
    docs: number;
    files: number;
  };
  createdAt: string;
  updatedAt: string;
}
```

## context

`companies.context` · Set a company's Context: what everyone should know about working with them.

**Owner's yes:** Checked. It changes what's there.\
**Your work:** listed on Home.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `companyId` | id | yes |  |
| `text` | text | yes | up to 1,500 characters |
| `why` | text | yes | 1–2,000 characters |

Returns:

```ts
{
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  context: string | null;
  contextBy: {
    kind: "agent" | "user" | "system";
    id: string;
  } | null;
  contextAt: string | null;
  owned: boolean;
}
```

## link_person

`companies.link_person` · Link a person to a company, or change the link: role, since, ended (dates).

**Owner's yes:** No. It makes something new.\
**Your work:** not listed on Home; the change shows on the record itself.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `contactId` | id | yes |  |
| `companyId` | id | yes |  |
| `role` | text | no | 1–200 characters |
| `since` | date (YYYY-MM-DD) | no |  |
| `ended` | date (YYYY-MM-DD) | no |  |

Returns:

```ts
{
  contactId: string;
  companyId: string;
}
```

## Types

Named types in the results above.

```ts
type CompanyRow = {
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  labels: string[];
  handler: string | null;
  people: {
    id: string;
    name: string;
  }[];
  peopleCount: number;
  open: ({
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  } & {
    person: string | null;
  }) | null;
  openCount: number;
  openKinds: ("you" | "them" | "follow_up")[];
  last: string | null;
}

type CompanyAbout = {
  text: string;
  facts: {
    label: string;
    value: string;
  }[];
  lately: {
    date: string;
    text: string;
    source?: number;
  }[];
  sources: {
    title: string;
    url: string;
  }[];
  by: {
    kind: "agent" | "user" | "system";
    id: string;
  };
  at: string;
}

type CompanyFile = {
  id: string;
  name: string;
  link: string;
  by: {
    kind: "agent" | "user" | "system";
    id: string;
  };
  at: string;
}

type CompanyPerson = {
  id: string;
  name: string;
  emails: string[];
  phone: string | null;
  labels: string[];
  open: {
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  }[];
  last: {
    first?: string;
    at?: string;
    channel?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
    members?: Record<string, string>;
    agents?: Record<string, string>;
  };
  role: string | null;
  since: string | null;
  ended: string | null;
}

type CompanyRecord = {
  id: string;
  name: string;
  website: string | null;
  domains: string[];
  labels: string[];
  context: string | null;
  contextBy: {
    kind: "agent" | "user" | "system";
    id: string;
  } | null;
  contextAt: string | null;
  details: {
    [x: string]: string;
  };
  about: CompanyAbout | null;
  handler: string | null;
  firstOnMail: boolean;
  alwaysAsk: boolean;
  listed: {
    id: string;
    name: string;
    ticker: string | null;
  } | null;
  files: CompanyFile[];
  open: {
    id: string;
    kind: "you" | "them" | "follow_up";
    text: string;
    at: string;
    thread?: string;
    link?: string;
    by?: {
      kind: "agent" | "user" | "system";
      id: string;
    };
  }[];
  people: CompanyPerson[];
  known: string | null;
  last: string | null;
  counts: {
    timeline: number;
    projects: number;
    docs: number;
    files: number;
  };
  createdAt: string;
  updatedAt: string;
}
```