Search

Where the workspace’s owners turn search on, Roadstar keeps a copy of the accounts they choose, and agents get this group. Search is literal and fast, costs the owner’s accounts nothing, and gives exact totals and counts, such as who the owner writes to most.

Its how-to lists, for the agent reading it, which accounts are in search and since when. The one below is for a workspace with none, so it names only the workspace’s own content.

Search several times with different words, then read what you’ll rely on. Mail and files keep their own live search for what the copy doesn’t hold yet.

How to use it

What find_tools sends with these tools, word for word:

Search and read the owner’s mail, files and meetings as copied for Roadstar, and the workspace’s own content. In search: the workspace’s docs, tables, contacts and projects. Search is literal and fast and costs the owner’s accounts nothing: search several times, with words in query and people, dates, folders, labels, sent or received as fields; identifiers as written. Totals and counts are exact over every match: counts.people shows who the owner writes with most. Results are one per thread; thread: its id lists every message. Read before you answer.

Tools

Tool	What it does	Owner’s yes
search.search	One list with the exact total, how names and dates were understood, counts by type, source, year, direction and sender, each source’s state, and next for the following page. Results with related: true matched by meaning, not by the words	No
search.read	A result in full, 30,000 characters at a time: a message with sender, recipients, date and its attachments’ ids; a whole thread by an id gmail:{account}:t:{thread}; an attachment’s or file’s text; a meeting. With next, read again from that offset	No

search

search.search · One list with the exact total, how names and dates were understood, counts by type, source, year, direction and sender, each source’s state, and next for the following page. Results with related: true matched by meaning, not by the words.

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

Input	Type	Required	What it is	Limits
query	text	no	Words; “PO 4471”, an invoice number or an email address match exactly	up to 300 characters
from	list of text	no	Sender, author or organizer: names, addresses or a company	up to 10 items, each 1–200 characters
to	list of text	no	To, cc or guests	up to 10 items, each 1–200 characters
with	list of text	no	Anyone on it, or everyone at a company	up to 10 items, each 1–200 characters
after	text	no	“2026-09-01” or “last week”	up to 40 characters
before	text	no		up to 40 characters
type	list of one of email, doc, sheet, slides, pdf, image, file, meeting, page, table, contact, project	no		up to 8 items
in	list of text	no	A folder (“Clients › Juniper Dental”) or a mail label (“label:Clients”, “label:STARRED”)	up to 5 items, each 1–200 characters
has	list of one of attachment, star	no		up to 2 items
dir	one of sent, received	no	Mail the owner sent, or mail they received
bulk	true or false	no	false: mail from people only; true: newsletters and automated mail only
waiting	one of me, them	no	Threads where a person wrote last and the owner hasn’t answered (me), or the reverse
thread	text	no	Every message of one thread, by its thread id	up to 200 characters
sort	one of relevance, newest, oldest	no
limit	whole number	no		1–50, default 10
cursor	text	no		up to 400 characters

Returns:

{
  hint?: string;
  results: {
    addedBy?: string;
    related?: boolean;
    text?: string;
    moreInThread?: number;
    thread?: string;
    money?: string[];
    attachments?: string;
    where: string;
    match: string;
    dir?: string;
    to?: string;
    from?: string;
    id: string;
    type: string;
    title: string;
    date: string;
  }[];
  counts: {
    type: Record<string, number>;
    source: Record<string, number>;
    year: Record<string, number>;
    dir: Record<string, number>;
    people: Record<string, number>;
  };
  sources: Record<string, string>;
  next: string | null;
  understood?: Record<string, string>;
  words?: string;
  related?: number;
  total: string | number;
}

read

search.read · A result in full, 30,000 characters at a time: a message with sender, recipients, date and its attachments’ ids; a whole thread by an id gmail:{account}:t:{thread}; an attachment’s or file’s text; a meeting. With next, read again from that offset.

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

Input	Type	Required	Limits
id	text	yes	3–500 characters
offset	whole number	no	0 or more

Returns:

ItemRead

Types

Named types in the results above.

type ItemRead = {
  title: string;
  url: string;
  text: string;
  source: string;
  nextOffset?: number;
  attachments?: {
    id: string;
    name: string;
    quality: string;
  }[];
}