Skip to content
RoadstarRoadstarRoadstar Docs

Companies

Markdown

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.
  • 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

Section titled “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

Section titled “Tools”
Tool What it does Owner’s yes
companies.list Companies with labels, people, what’s open, last contact and handler No
companies.read Everything to know before working for a company: Context, details, About, people with roles, open, newest 20 conversations No
companies.create Add a company; people are contact ids, a role each No
companies.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 Replace a company’s About from the web: text citing sources as [1], facts, dated news Checked
companies.timeline A company’s conversations, newest first; before is the last item’s at No
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 No
companies.unrecord Take an entry off a company’s timeline; the owner can undo it Checked
companies.open Open an item on a company (a follow-up at a time wakes you), or close one by id Depends
companies.context Set a company’s Context: what everyone should know about working with them Checked
companies.link_person Link a person to a company, or change the link: role, since, ended (dates) No

list

Section titled “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:

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

read

Section titled “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:

{
  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

Section titled “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:

CompanyRecord | {
  message: string;
}

update

Section titled “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:

{
  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

Section titled “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:

{
  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

Section titled “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:

{
  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

Section titled “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:

{
  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

Section titled “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:

{
  historyId: string;
}

open

Section titled “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:

{
  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

Section titled “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:

{
  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;
}
Section titled “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:

{
  contactId: string;
  companyId: string;
}

Types

Section titled “Types”

Named types in the results above.

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;
}